Documentation Index
Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
CLI First
# Register (new account)
naive register --name "My Agent" --email owner@example.com --password securepassword123 --company "Acme Corp"
# Login (existing account)
naive login --email owner@example.com --password securepassword123
# Passwordless link flow
naive link --email existing@example.com
naive verify --email existing@example.com --code 482901
API Keys
Every request requires a Bearer token: Authorization: Bearer nv_sk_live_...
Keys are scoped to one agent inside one company. Identity is resolved automatically — you never need to pass agent or company IDs.
Getting a Key
Option A: Self-Register (new account)
POST /v1/auth/register
{
"name": "My Agent",
"email": "owner@example.com",
"password": "securepassword123",
"company_name": "Acme Corp"
}
Option B: Login (existing account)
If you already registered or have a dashboard account:
POST /v1/auth/login
{
"email": "owner@example.com",
"password": "securepassword123"
}
POST /v1/auth/select-company to switch.
Option C: Link Existing Account (passwordless)
If your owner already has a Naive account and prefers email verification:
Request verification code
POST /v1/auth/link
{ "email": "existing@example.com" }
Verify with code
POST /v1/auth/verify
{ "email": "existing@example.com", "code": "482901" }
Select company (if multiple)
POST /v1/auth/select-company
{ "company_id": "uuid" }
Key Management
# List keys
GET /v1/auth/keys
# Create new key
POST /v1/auth/keys
{ "name": "Production Key" }
# Revoke key (immediate, irreversible)
DELETE /v1/auth/keys/:id
Revoking a key takes effect immediately. Any clients using that key will start receiving 401 errors.
Rate Limiting
| Tier | Rate |
|---|
| Free | 60 requests/minute |
| Pro | 300 requests/minute |
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1714250400
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header",
"hint": "Set header: Authorization: Bearer nv_sk_...",
"docs": "https://docs.usenaive.ai/getting-started/authentication"
}
}
Error Codes
| Code | Status | Meaning |
|---|
unauthorized | 401 | Missing or invalid Bearer token |
forbidden | 403 | Key valid but not authorized for this resource |
insufficient_credits | 402 | Not enough credits |
rate_limited | 429 | Too many requests |
invalid_inbox | 400 | Inbox UUID not found or not owned |
resource_not_found | 404 | Entity doesn’t exist |
invalid_input | 400 | Validation failure |
provider_error | 502 | External service failed |
duplicate_request | 409 | Idempotency-Key already used |
duplicate_record | 409 | Record already exists (e.g., email taken) |
Idempotency
For mutation requests, pass an Idempotency-Key header to prevent duplicate operations:
curl -X POST https://api.usenaive.ai/v1/email/send \
-H "Authorization: Bearer nv_sk_live_..." \
-H "Idempotency-Key: unique-request-id-123" \
-H "Content-Type: application/json" \
-d '{ ... }'
