Authentication
All API requests (except /healthcheck) require a valid API key passed as a Bearer token.
API keys
API keys are created from the Sybill dashboard under Settings → Integrations → API Keys. Each key is scoped to your organization and can be granted specific permissions.
Key visibility
Keys use the prefix sk_live_ followed by a random token. The full key is shown only once at creation time — store it securely.
Key format
sk_live_<YOUR_API_KEY>
Making requests
Include the key in the Authorization header:
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
https://api.sybill.ai/v1/conversations
Scopes
Each API key is granted one or more scopes that control what it can access:
| Scope | Description |
|---|---|
read | Read conversations, deals, accounts, messages, rows, documents, sources, and object types (GET endpoints) |
ingest | Push records into Sybill and manage sources / object types (POST, PATCH, DELETE endpoints) |
ask_sybill | Use the Ask Sybill AI assistant via MCP |
The mapping of REST endpoints to scopes is straightforward:
| Endpoints | Required scope |
|---|---|
GET /v1/health | any valid key |
GET on /v1/conversations, /v1/deals, /v1/accounts, /v1/messages, /v1/rows, /v1/documents, /v1/sources, /v1/object-types | read |
POST / PATCH / DELETE on the same paths | ingest |
If a request requires a scope that the key does not have, the API returns 403 Forbidden:
{
"detail": "API key missing required scope: read"
}
Key management
| Action | Method |
|---|---|
| Create a key | Sybill dashboard → Settings → Integrations → API Keys → Create |
| List keys | Sybill dashboard → Settings → Integrations → API Keys |
| Revoke a key | Sybill dashboard → Settings → Integrations → API Keys → Revoke |
Revocation is permanent
Revoked keys immediately stop working. You cannot un-revoke a key — you must create a new one.
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing, invalid, or revoked API key |
403 Forbidden | Key is valid but missing a required scope |