CloudSh API Documentation

If you don't want to use the Widget you can implement your search with the CloudSh API.

API Host: https://api.cloudsh.com

Authorization

Authorization is done with a Bearer token in the Authorization header. You can grab your token from the CloudSh dashboard.

curl -v -H "Authorization: Bearer TOKEN" \
  "https://api.cloudsh.com/v1/search?q=rails&len=10"

Endpoints

All endpoints require the Authorization header and return JSON.

Search

Search your index with a query.

GET /v1/search

Parameter	Type	Required	Description
q	string	yes	The query to search the index with
start	int	no	The result count to start returning results from. Zero based
len	int	no	The number of results to return in a page. Default is 10. Max is 100.

curl -v \
  -H "Authorization: Bearer TOKEN" \
  "https://api.cloudsh.com/v1/search?q=rails&start=0&len=2"

Response

{
  "index": "candland.net",
  "status": "ok",
  "hits": 39,
  "start": 0,
  "len": 2,
  "q": "rails",
  "urls": [
    {
      "url": "https://candland.net/2019/add_webpack_to_rails5/",
      "title": "Add Webpack to Rails 5 | candland.net",
      "description": "Add Webpack to Rails 5 Dusty Candland | Fri Aug 30 2019 | rails, rails5, webpack, webpacker, scss, bootstrap, font-awesome The push to use webpack with rails is...",
      "image": "https://candland.net/assets/images/candland-icon.png"
    },
    {
      "url": "https://candland.net/2012/04/17/rails-blog-engines/",
      "title": "Rails Blog Engines | candland.net",
      "description": "Rails Blog Engines Dusty Candland | Tue Apr 17 2012 | engines, rails A list of mountable blog engines for Rails. Blogit Blogit Engine Blogit is a flexible...",
      "image": "https://candland.net/assets/images/candland-icon.png"
    }
  ],
  "duration": 20237
}

Suggest

Returns the top 10 suggestions for a query as your typing. If you implement this it should be debounced.

GET /v1/suggest

Parameter	Type	Required	Description
q	string	yes	The query to search the index with

curl -v \
  -H "Authorization: Bearer TOKEN" \
  "https://api.cloudsh.com/v1/suggest?q=rails"

Response

{
  "index": "candland.net",
  "status": "ok",
  "hits": 40,
  "start": 0,
  "len": 10,
  "q": "rails",
  "urls": [
    {
      "url": "https://candland.net/2010/10/07/tips-from-the-mountainrb-ruby-on-rails-workshop/",
      "title": "Tips from the MountainRB ruby on rails workshop | candland.net",
      "description": "Tips from the MountainRB ruby on rails workshop Dusty Candland | Thu Oct 07 2010 | cucumber, rails, ror, routes, ruby Yesterday I was at the MountainRB ruby...",
      "image": "https://candland.net/assets/images/candland-icon.png"
    },
    {
      "url": "https://candland.net/2020/rails-typed-json-fields/",
      "title": "Rails Typed JSON Fields | candland.net",
      "description": "Rails Typed JSON Fields Dusty Candland | Thu Nov 19 2020 | rails, rails6, ruby, postgresql I've been using [Rails JSON Serialized...",
      "image": "https://candland.net/assets/images/candland-icon.png"
    },
    ...
  ],
  "duration": 28569
}

Events

Use this to post events for reporting in the CloudSh dashboard. There are two event types, SearchEvent and ClickEvent.

SearchEvents are sent automatically in the search endpoint. You only need to implement ClickEvents.

Parameters can be posted as JSON or Form parameters.

POST /v1/events

Content-Type: application/json | application/x-www-form-urlencoded

Parameter	Type	Required	Description
type	string	yes	Must be either SearchEvent or ClickEvent
term	string	yes	The query used to generate the results
result_count	int	yes	The total number of results returned by the query
page_number	int	yes	They current page of results
result_rank	int	ClickEvent	The rank or index of the result being clicked on the page.
url	string	ClickEvent	Should be the URL of the result being clicked

curl -v \
  -d '{"type":"ClickEvent","term":"ruby","page_number":1,"result_count":23,"result_rank":2,"url":"https://candland.net/ruby"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  "https://api.cloudsh.com/v1/events"

Response

{
  "status": "ok"
}