Documentation Index
Fetch the complete documentation index at: https://docs.actionlayer.dev/llms.txt
Use this file to discover all available pages before exploring further.
Every request to the ActionLayer API uses a Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_KEY
nc_live_<32 alphanumeric characters>
Getting Your First Key
- Sign in to app.actionlayer.dev.
- Open Settings → API Keys.
- Click Create API Key, give it a name (e.g.
production-agent), and copy the value immediately.
Treat API keys like passwords. Never commit them to source control, never embed them in client-side code, never paste them into shared docs. Store them in a secrets manager or .env file.
Creating Additional Keys
curl -X POST https://api.actionlayer.dev/v1/api-keys \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "production-agent"}'
{
"id": "key_abc123",
"name": "production-agent",
"key": "nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"prefix": "nc_live_xxxx",
"created_at": "2026-04-30T12:00:00Z"
}
key field is present only on this initial response. Subsequent GET /v1/api-keys calls return only the prefix.
Revoking a Key
curl -X DELETE https://api.actionlayer.dev/v1/api-keys/{key_id} \
-H "Authorization: Bearer $ACTIONLAYER_API_KEY"
401 unauthorized.
Scopes
Keys created in the dashboard have full workspace access. ActionLayer enforces scopes server-side on every request:
| Scope | Endpoints |
|---|
read:threads | GET /threads, GET /threads/{id} |
write:drafts | POST /drafts, PATCH /drafts/{id}, POST /drafts/{id}/approve|reject |
write:emails | POST /emails/send, POST /emails/reply, POST /drafts/{id}/send |
read:identities / write:identities | Identity CRUD |
read:rules / write:rules | Rule CRUD |
read:billing | GET /billing/subscription |
"error": "insufficient_scope" means the key isn’t permitted for that endpoint.
Rate Limits
| Endpoint class | Limit |
|---|
Auth (/auth/*) | 5–60 requests/min depending on route |
| Read endpoints | 60/min |
| Write endpoints | 10–20/min |
/drafts/{id}/notify (re-trigger notification) | 10/min |
429 with a Retry-After header in seconds.
Error Shape
All errors return a consistent JSON envelope:
{
"error": "unauthorized",
"message": "Invalid or revoked API key"
}
| HTTP | error code | Meaning |
|---|
| 401 | unauthorized | Missing, malformed, or revoked key |
| 401 | insufficient_scope | Key lacks the required scope |
| 402 | plan_limit_reached | Workspace exceeded its plan quota — response includes upgrade_url |
| 404 | not_found | Resource does not exist or is in another workspace |
| 409 | stale_draft | Newer inbound arrived after the draft was generated |
| 422 | invalid_request / invalid_status | Validation error — message explains which field |
| 429 | rate_limited | Too many requests — back off and retry |
