Base URL
Send all API requests to:
Authentication
Every request requires a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Keep your keys secret. Never commit them to GitHub, paste them in Slack, or use them in client-side JavaScript. API keys give full access to your account.
Content-Type: application/json in your headers:
curl -X POST https://api.getarbol.com/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "My Agent"}'
2xx status code. List endpoints include pagination:
{
"items": [...],
"total": 42,
"page": 1,
"pageSize": 20
}
Error Handling
When something goes wrong, you’ll get an HTTP error code and a JSON error object:
{
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
}
}
| Status Code | Description |
|---|
400 | Bad Request - Invalid parameters or request body |
401 | Unauthorized - Missing or invalid API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource does not exist |
409 | Conflict - Resource already exists or state conflict |
422 | Unprocessable Entity - Validation error |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error |
Rate Limiting
We limit requests per organization to keep the API fast for everyone. Hit the limit and you’ll get a 429 status code. Check these headers to see your limits:
X-RateLimit-Limit - Maximum requests per windowX-RateLimit-Remaining - Remaining requests in the current windowX-RateLimit-Reset - Unix timestamp when the window resets
List endpoints support pagination with the following query parameters:
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number |
pageSize | integer | 20 | Number of items per page (max 100) |
ID Prefixes
Every resource ID starts with a prefix so you can tell what it is at a glance:
| Resource | Prefix | Example |
|---|
| Agent | agt_ | agt_abc123... |
| Contact | cnt_ | cnt_def456... |
| Conversation | cnv_ | cnv_ghi789... |
| Campaign | cmp_ | cmp_jkl012... |
| Property | prp_ | prp_mno345... |
| Document | doc_ | doc_pqr678... |
Need Help?
If you run into issues or need support, head to your dashboard to create a support ticket. You can also email us directly at david@getarbol.com.
