API#

This API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API in test mode, which doesn’t affect your live data. The API credentials you use to authenticate the request determines whether the request is live mode or test mode.

Authentication#

The API uses basic authentication. Credentials should be set in the Authorization header, credentials specified in the URL are ignored. The username is always prefixed with either test_ or live_. Test credentials only allow access to objects in the database that are not flagged for live mode and vice versa.

Test mode#

This service offers a built-in test mode that makes integration easier. The test mode is automatically enabled when a test token is used. When applicable resources have a live_mode field that is set accordingly. Requesting a live resource with test credentials or vice versa will result in the resource not being found, the API will return 404 Not Found.

Managing credentials#

API credentials can be requested and managed from /api-keys/.

The requested key's permissions will be equivalent to the account that created it.

Account selection#

API credentials may have access to multiple accounts, in those cases the X-OP-Account header must be set to the name of the account that is being operated on. If the token has access to only one account the header can be omitted.

Versioning#

This section will explain how the API is versioned.¹ The API has a version number, which is represented by a date (e.g. 2024-12-01). When making changes to the API, the following will happen:

• If we make backwards compatible changes, the changes are simply released without notice or version bumps
• For any changes that are not backwards compatible, we will bump the API version to the current date

When is a change backwards compatible?#

While it is difficult to provide a complete list of scenarios, here follow some examples of changes we do and do not consider to be backwards compatible.

In essence, ensure your clients do not rely on "fragile" hints such as the order of the keys in a response, an exact set of keys within a response or the length of a field.

Selecting an API version#

For every API key, you can select the desired API version to be used. Any request made using that key will make use of the version you selected. This way, you have control over the format of requests and responses.

Rate limits#

The API has no explicitly defined rate limits. Please do not hammer the API; there is no need to do so. If in doubt, do not parallelize your requests. If we observe excessive usage, we may decide to (temporarily) disable the offending API key.

Pagination#

The API uses limit-offset pagination. The client can pass optional limit and an offset query parameters. The limit indicates the maximum number of items to return. The offset indicates the starting position of the query in relation to the complete set of unpaginated items.

Results are always paginated, regardless of limit and offset query parameters being passed. A basic result looks like

{
  "count": 150,
  "next": "/api/partners/?limit=100&offset=1",
  "previous": null,
  "results": [...]
}

Documentation and "Try it out"#

Documentation can be found at /api/docs/. The generated documentation offers "Try it out" functionality. Be sure to hit the "Authorize" button and authenticate first (see Authentication).

Previous versions#

Below you can find an overview of all valid API versions.

Changelog#

2025-09-03#

• For the subscriptions endpoint, the state field was updated: from this version onwards the field's purchased value is called created.
• The name field got removed from the me endpoint

2025-06-03#

• For the bills endpoint, the partner field was updated: from this version onwards the field contains an object with more details about the partner, instead of being just a UUID string

2024-12-01#

This version contains no backwards incompatible changes.