Skip to main content

API reference

Use the Hotpot API, https://api.hotpot.works, to bulk upload availability, create moments, trigger a page, and more.

Limited access beta

The Hotpot API is in heavy development and currently restricted to design partnerships.

Authentication​

All requests to the Hotpot API require authentication. Provide your API key in an HTTP Bearer Authorization header:

Authorization: Bearer <your API key>

API keys are assigned to a user, not to an organization.

Get your API key​

To create an API key in Hotpot:

  1. Go to the Hotpot app > your user icon in the upper-right corner and click API keys.
  2. On the right side of the screen, click Create API key.
  3. Name your API key and click Generate new key. This creates an entry in your API keys listing.

To see a quick paging example in cURL, click on the value in the API Token column.

Now that you have your key, use it to authenticate requests:

curl https://api.hotpot.works/<the endpoint you want>
  -H "Authorization: Bearer <your API key>"

Asynchronous requests​

Some requests to the Hotpot API are queued for delivery instead of immediately sent. This approach facilitates retries in the case of network interruption. When you issue a request to an asynchronous endpoint, the response you get is structured like:

{
    "hotpot_request_id": <a unique character string>,
    "response": {
        "success": true,
        "message": "Your request has been queued."
    }
}

You can use the returned hotpot_request_id to check the request status.

Responses​

A response from the Hotpot API contains a JSON body with three possible fields:

  • hotpot_request_id: For asynchronous requests, this is used to check the request status.
  • response: For successful requests, the relevant information is here. For example, delivery status of a page, a message telling you your request is queued for processing, and the like.
  • error: If a synchronous request encounters an error, or an asynchronous request encounters an error that prevents it from queueing, it's listed here. Asynchronous errors that occur after being queued appear in the response section of GET /request/:request_id/status.