API

API for interacting with Hotpot

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

Authentication

Hotpot's API uses API keys for authentication. API keys are assigned per user. API requests use HTTP Bearer Authentication via headers:

Authorization: Token token="abc123"

Getting your API key

The Hotpot API can be found at https://api.hotpot.works.

All requests to the Hotpot API require authentication. Hotpot uses a Bearer token on HTTPS requests for this, and you can create a token in Hotpot by first heading to the dashboard.

Open the user menu in the upper right and select "API keys".

On the API keys page, click "Create API key" on the right side.

Name your API key.

You'll now have an entry in your API keys listing.

Clicking on the value in the "API Token" column will take you to a page with the full value of the token and a quick paging example in cURL.

Now that you have your key, you can use it to authenticate requests by passing it as the Authorization header, like in the example on the token page, or like so:

curl -X <method, like GET or POST> -H "Authorization: Bearer <your API key>" https://api.hotpot.works/<the endpoint you want>

Asynchronous requests

Some requests to the Hotpot API are queued for delivery instead of immediately being sent out to facilitate retries in the case of network interruption. When you issue a request to one of the asynchronous endpoints of the Hotpot API, the response you get will be structured like this:

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

The hotpot_request_id returned by those calls can be used to check the status of your request. See GET /request/:request_id/status for details.

Responses

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

• hotpot_request_id: For asynchronous requests, this is the ID you will use to check the status of your request.

• response: For successful requests, the relevant information will be here, e.g. 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 will prevent it from queueing, it will be listed here. Asynchronous errors that occur after being queued will be in the response section of GET /request/:request_id/status.