The Runn API uses REST principles, exposing predictable resource-oriented URLs. It accepts request bodies and exposes data via JSON encoding. Errors are communicated via standard HTTP response codes.

The Runn API can be accessed via https://api.runn.io, unless you have been provided a different URL (check in "Account > Settings > API" in the Runn app)

All API endpoints are documented in a machine-readable way through the OpenAPI v3 standard. All available endpoints are listed on https://api.runn.io/documentation/

See API v1 Changelog

The API uses Bearer Authentication via HTTP headers, secured over TLS network connections.

API tokens are generated through the Runn application, via “Settings > API”. Only administrators in your Runn account can generate them.

Each token can have read or write scopes, and is tied to a specific account (not a user).

Keep in mind that your “Test Account” has separate tokens.

The API is versioned, with a mandatory “Accept-Version” header. Some endpoints will only be available in newer versions, or change behavior in ways defined through the Changelog.

API v1 is currently in beta and the suggested version for all new API integrations and reporting. We will endeavor to make minimal breaking changes during the beta, however we can not guarantee it.

There are many ways to make HTTP calls to the Runn API. We do not provide an official SDK for different programming languages. Every language will have capable HTTP clients to get you started. Here’s how you would make a request to get all clients in your account with the popular curl command line utility.

All endpoints for writing data via the API accept request bodies in JSON format. Here’s how you would update an existing client with id=123:

Refer to the OpenAPI documentation for available endpoints and detailed request body format. Generally speaking, the API will only update properties passed into the request body, and retain omitted properties on existing records. In order to explicitly unset properties, pass in the appropriate “null” format for the property (null, "", []). When creating records, properties may be left out unless they are required.

All collection endpoints (e.g. GET /people) are paginated, usually returning 50 items by default. The amount can be increased through the limit parameter, usually to 200 items. The API response will indicate whether more records are available through a nextCursor property in the JSON response body (using cursor-based pagination).

In order to get more results, you need to pass through the nextCursor from the response as the cursor parameter in your next request.

When no further items are available, the nextCursor value will be null.

We rate limit the API to 120 requests every 1 minute for each API key and each IP. These limits apply even if requests are spread across multiple API keys or multiple IPs. If you exceed this limit, you will receive a 429 Too Many Requests HTTP response for the remainder of that time window.

API responses contain additional metadata to indicate your current rate limit:

Runn uses conventional HTTP response codes to communicate success or failure of an API request. In general: Codes in the 2xx range indicate success. Code in the 4xx range indicate an error given the information you provided. Codes in the 5xx range indicate an error on our end.

Each error will contain the following attributes in a JSON body:

We would love to hear your feedback about our new API. Please send any feedback to help@runn.io