​
Base URL

The Carbon API is built on REST principles, enforcing HTTPS in every request to enhance data security, integrity, and privacy. Please note that the API does not support HTTP.

All requests should be directed to the following base URL:

https://api.carbon.ai

​
Authentication

For organization-wide, non-customer associated API requests, only an API key is required (for example, this endpoint). The specific routes in the API reference will indicate the applicable headers and what’s required.

Our API supports two header-based authentication methods:

​
Carbon API Key and Customer ID

For API key-based authentication, you can pass in your API key and customer-id. The customer-id is a unique identifier that denotes an individual user in your system.

Content-Type: application/json
authorization: Bearer <API KEY>
customer-id: <customer-id>

​
Access Token

You can generate an access token via the /auth/v1/access_token endpoint, and the access token can be used without needing to pass in a separate customer-id in the header.

Access tokens are valid for 10 hours, after which you need to generate a new token.

Content-Type: application/json
authorization: Token <TOKEN>

​
Rate Limit

You can find a list of rate limits broken down by API endpoint here.

After the rate limit is exceeded, you’ll hit the rate limit and receive a 429 response error code. To prevent this, we recommend reducing the rate at which you request the API. This can be done by introducing a queue mechanism or reducing the number of concurrent requests per second. If you have specific requirements, contact support to request a rate increase.

​
Response Codes

Carbon uses standard HTTP codes to indicate the success or failure of your requests.

In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

StatusDescription
200Successful request.
400Check that the parameters were correct.
401User doesn’t have access to the resource.
403User authorization issue.
404The resource was not found.
429The rate limit was exceeded.
5xxIndicates an error with Carbon servers.

​
File Sync Status

The existing files, chunks, and embeddings remain retrievable in any of the following non-READY statuses if the file was previously synchronized.
StatusDescription
QUEUED_FOR_SYNCThe file is waiting in the queue to be synced.
SYNCINGThe file is currently being synced.
READYThe file has been successfully synced and is now ready for use. Files, chunks, and embeddings are ready in this status.
SYNC_ERRORAn error occurred during the sync process for this item.
EVALUATING_RESYNCThe system is assessing whether the file needs to be re-synced.
RATE_LIMITEDThe file sync has been temporarily paused or slowed down due to hitting API rate limits with an external service.
SYNC_ABORTEDThe file sync was cancelled or aborted before it could be completed, either due to a user action or system decision.
QUEUED_FOR_OCRThe item is in the queue, waiting for optical character recognition (OCR) processing to extract text from images or scanned documents.
DELAYEDThe file sync is delayed until resources are available to process the file.

​
FAQ

Errors