Get Started
Understand general concepts, response codes, and authentication strategies.
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:
Authentication
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.
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.
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.
Status | Description |
---|---|
200 | Successful request. |
400 | Check that the parameters were correct. |
401 | User doesn’t have access to the resource. |
403 | User authorization issue. |
404 | The resource was not found. |
429 | The rate limit was exceeded. |
5xx | Indicates an error with Carbon servers. |
File Sync Status
READY
statuses if the file was previously synchronized.Status | Description |
---|---|
QUEUED_FOR_SYNC | The file is waiting in the queue to be synced. |
SYNCING | The file is currently being synced. |
READY | The file has been successfully synced and is now ready for use. Files, chunks, and embeddings are ready in this status. |
SYNC_ERROR | An error occurred during the sync process for this item. |
EVALUATING_RESYNC | The system is assessing whether the file needs to be re-synced. |
RATE_LIMITED | The file sync has been temporarily paused or slowed down due to hitting API rate limits with an external service. |
SYNC_ABORTED | The file sync was cancelled or aborted before it could be completed, either due to a user action or system decision. |
QUEUED_FOR_OCR | The item is in the queue, waiting for optical character recognition (OCR) processing to extract text from images or scanned documents. |
DELAYED | The file sync is delayed until resources are available to process the file. |