Capacities API (Beta) ​

The Capacities API is a REST API that allows you access, create and manipulate your content.

Authentication ​

The Capacities API uses Bearer authentication (token-based authentication, OAuth 2.0 RFC 6750). You can obtain an access token in the desktop app at Settings > Capacities API.

The obtained token needs to be passed in the header of each request as follows:

Authorization: Bearer <your_access_token>

Rate limits ​

The Capacities API is protected with a rate limits to prevent abuse. If you exceed the rate limits, you will receive a 429 Too Many Requests response. The rate limits are applied on a user basis for every endpoint individually.

Current rate limits can be obtained from the response header based on the RateLimit-Remaining header fields (HTTP standardization draft, IETF).

RateLimit-Policy: 120;w=60 # <requests>;w=<window in seconds>
RateLimit-Limit: 100 # requests per rate limit window
RateLimit-Remaining: 98 # requests left in the current rate limit window
RateLimit-Reset: 53 # seconds until the rate limit is reset

Errors ​

The Capacities API uses standard HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed because of the the information provided (e.g., a required parameter was omitted, non-existing content was referenced, etc.), and codes in the 5xx range indicate an error with Capacities's servers.

Here are some common errors you might encounter when using the Capacities API:

• 400 Bad Request - The request was unacceptable, often due to missing a required parameter.
• 401 Unauthorized - No valid access token provided or not allowed to access resource.
• 429 Too Many Requests - Too many requests hit the API too quickly. We recommend to implement rules based on the rate limit headers or add an exponential backoff of your requests (More here).
• 500 Something went wrong - Something went wrong on Capacities's end.
• 503 Temporarily unavailable - The API is inactive or in maintenance.
• 555 Temporarily unavailable - Capacities is getting an update. The API is temporarily unavailable.

API Reference ​

The Capacities API offers various endpoints to interact with your data. You can read about all API endpoints here:

Reference

If you need programmatic access to the API specification, you can download the OpenAPI 3.0 Specification.

Important API knowledge ​

Content IDs ​

The Capacities API uses unique IDs to reference content.

• SpaceId: You can find the ID of a space under Settings > Space settings.

• ObjectId: You can find the ID of an object in the app by clicking on the object menu and selecting Copy object reference. In the clipboard, you will find an URL to the object. The last part of the URL is the ID of the object. For example, the ID of the object with the URL capacities://0e1dc99b-693d-4d19-9ga3-ab637a55d1b3/95896927-2dd3-4167-8a15-0e1ad56a5e8d is 95896927-2dd3-4167-8a15-0e1ad56a5e8d.

Structures ​

Object types in Capacities are represented as structures in the API. Each structure has a unique ID. Every object in Capacities has a structureId property that references the structure of the object.

All structures of a space can be obtained by using the GET /space-info endpoint.

Basic structures (structures provided by Capacities) have the following structureIds:

Property Definitions ​

Each structure has a set of property definitions (properties on your object pages). The property definitions are represented as a list of objects containing information about the type of property, etc. You can obtain property definition by using the GET /space-info endpoint.