#Overview

Every endpoint lives under the /api path on the same host that serves the app (for example https://yourworkspace.example.com/api/...). Routes are Next.js App Router handlers found under src/app/api/. There is no separate API subdomain today — you call the same origin you sign in to.

An interactive endpoint browser ships at /api-docs. It groups planned resources (Contacts, Leads, Deals, Activities, Automations) into an expandable reference and includes copy-ready curl snippets. Use it to explore method + path shapes; treat the exact set of resources there as the product roadmap surface, and this page as the description of what is wired up and callable today.

#Authentication & tenant scope

Authenticated routes call requireTenantUser() (see src/lib/supabase/helpers.ts). It resolves the current user with supabase.auth.getUser(), then resolves an active tenant membership from the tenant_users table. Both must succeed or the request is rejected.

• No user session -> 401 with body { "error": "Unauthorized" }.
• Signed in but no active membership -> 403 with body { "error": "No active tenant membership" }.
• Success -> the handler runs with { user, tenantId, role } and every query is filtered to that tenant_id.

Choosing the tenant

If you belong to more than one workspace, pick which one a request targets with the x-tenant-id request header. When the header is absent, the server falls back to the active-tenant cookie, and finally to your most recently joined active membership.

curl -X GET "https://yourworkspace.example.com/api/crm/deals?limit=50" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: <your_tenant_uuid>" \
  --cookie "sb-access-token=<supabase_session_cookie>"

#Response format & error codes

Newer routes use the shared envelope in src/lib/api-response.ts. Success responses look like { "success": true, "data": ..., "message": ... }; failures look like { "success": false, "error": ..., "code": ..., "message": ..., "details": ... } with a machine-readable code.

#Endpoints that exist today

The table below lists live handlers under src/app/api/. Paths are relative to your app host. Session means requireTenantUser is enforced; Public means no auth (tenant is resolved from the URL slug); Signed means HMAC request signing (see the server-to-server section).

#Worked example: importing leads

POST /api/v1/import/leads is the most complete write endpoint. Send a leads array; each item is validated (email is required), the source is normalized, and unknown keys like company are tucked into custom_fields. Rows are inserted into crm_leads and the batch is recorded in import_jobs.

emailstring (required)

Lead email. Rows without it are skipped and reported in errors.

first_namestring

Optional given name; stored null if omitted.

last_namestring

Optional family name; stored null if omitted.

phonestring

Optional phone number.

statusstring

Lifecycle status; defaults to "new".

lead_source / sourcestring

Origin of the lead; normalized server-side. Defaults to "api_import".

companystring

Not a column — merged into custom_fields.company.

custom_fieldsobject

Arbitrary extra key/values persisted on the lead.

curl -X POST "https://yourworkspace.example.com/api/v1/import/leads" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: <your_tenant_uuid>" \
  --cookie "sb-access-token=<supabase_session_cookie>" \
  -d '{
    "leads": [
      {
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+15551234567",
        "source": "webinar",
        "company": "Acme LLC"
      },
      { "first_name": "NoEmail" }
    ]
  }'

{
  "success": true,
  "imported": 1,
  "failed": 1,
  "errors": [
    { "index": 1, "error": "Email is required" }
  ],
  "data": [
    { "id": "…", "email": "jane@example.com", "status": "new", "source": "webinar" }
  ]
}

#Signed server-to-server calls

Machine-to-machine receivers under /api/migrate/* do not use a session. They require an HMAC-SHA256 signature, verified by verifyOlyronMigrateRequest (src/lib/olyron-migrate/verify.ts). This is the pattern to follow for any future keyless backend integration.

1. 1
   Configure the shared secret

   Set OLYRON_MIGRATE_SIGNING_SECRET on the server. When it is absent, verification fails and the receiver rejects the request with 401 missing_signing_secret.
2. 2
   Build the signing string

   Join method, path, timestamp (ms), nonce, and the raw request body with newline (\n) separators.
3. 3
   Sign it

   Compute HMAC-SHA256 over that string with the secret and hex-encode the digest.
4. 4
   Send the headers

   Attach x-olyron-signature, x-olyron-timestamp, and x-olyron-nonce to the request.

#Pagination, limits & troubleshooting

List endpoints cap result size with a limit query parameter — for example GET /api/crm/deals?limit=50 (default 100). Helpers in src/lib/supabase/helpers.ts (applyPagination, buildPaginatedResult) and the apiPaginated response builder support page-based pagination with page, pageSize, sortBy, and sortOrder, returning { items, total, page, pageSize, totalPages }.

Rate limits

The /api-docs page advertises per-plan rate limiting (up to 1,000 requests/min) and a 429 RATE_LIMIT_EXCEEDED code exists in the response library. Treat a 429 as retryable with backoff, and honor a details.retryAfter value if present.