Authentication

API Keys

All API requests require an API key pair. Create one from Settings > Integrations > API Keys in the dashboard.

Include both headers on every request:

X-API-Key: ek_live_abc123...
X-API-Secret: es_live_xyz789...

The API secret is only shown once at creation time. Store it securely — you won't be able to retrieve it later.

Scopes

Each API key is created with specific permission scopes. A request will be rejected with 403 Forbidden if the key lacks the required scope.

proposals:read — List, get, and export proposals

proposals:write — Create, update, and archive proposals

proposals:generate — Trigger AI pipeline (analyze, generate, score)

files:write — Upload files and import URLs to proposals

webhooks:manage — Create, update, delete, and test webhook endpoints

Response format

Success responses

{
  "data": { ... },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-03-17T10:30:00.000Z"
  }
}

Paginated responses add pagination fields to meta:

{
  "data": [ ... ],
  "meta": {
    "requestId": "...",
    "timestamp": "...",
    "page": 1,
    "limit": 20,
    "total": 47,
    "hasMore": true
  }
}

Error responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [ ... ]
  },
  "meta": {
    "requestId": "...",
    "timestamp": "..."
  }
}

Common error codes

UNAUTHORIZED (401) — Missing or invalid API key

FORBIDDEN (403) — API key lacks required scope

NOT_FOUND (404) — Resource not found

VALIDATION_ERROR (400) — Invalid request body or parameters

INVALID_STATE (409) — Resource is in a state that doesn't allow this operation

CONFLICT (409) — Operation already in progress (e.g., duplicate analysis)

USAGE_LIMIT_EXCEEDED (403) — Monthly proposal limit reached

FEATURE_NOT_AVAILABLE (403) — Feature requires a higher subscription tier

RATE_LIMITED (429) — Too many requests

Rate limits

General endpoints — 60 requests / minute per API key

Pipeline triggers (analyze, generate, score) — 10 requests / minute per API key

Rate limit headers are included on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1679054460

When rate limited, you'll receive a 429 response. Wait until the X-RateLimit-Reset timestamp before retrying.