REST API

Base URL

https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1

All paths on this page are relative to this base. The API is HTTPS-only, and every request and response body is JSON. Breaking changes only ship under a new version prefix — /v1 paths stay stable.

Authentication

Every request carries two headers:

GET /v1/deals
Authorization: Bearer kyo_at_…
apikey: <public anon key>

• Authorization — a Kyo access token (prefix kyo_at_) obtained through the OAuth 2.0 flow. Access tokens expire after 1 hour; refresh tokens rotate on every use.
• apikey — a public routing key, the same value the Kyo web app ships. It grants nothing by itself; all authorization comes from the bearer token.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InB2b3pia3Voam9meml0c21wc3BmIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzUwMzU0ODMsImV4cCI6MjA5MDYxMTQ4M30.PccqZEYqEHdG1dnFn1AtCcrBGSCqU5ptcP5Vxt-KhBY

Resources

Every resource lives under /v1/ and needs its scope with :read for GET and :write for POST/PATCH — see scopes. Scope alone is not enough: the authorizing user must also hold the matching feature permission in the workspace, see permissions.

Read is GET /v1/<resource> and GET /v1/<resource>/{id}; write is POST to create and PATCH to update. Resources marked detach are join records with no /{id} form — unlink them with POST … ?detach=true, see deleting. /v1/workspace is a singleton: the list returns your one workspace row. /v1/users and /v1/workspace are marked read · update — both can be updated but never created through the API; members arrive by invitation.

Writable fields

Creates and updates accept only these fields; anything else in the body is ignored. Server-owned columns (workspace_id, created_by, and the requester on comments, leave_requests and metric_entries) are always set from your token, never from the body — and a status change on leave_requests or hr_change_requests stamps reviewed_by/reviewed_at as you.

Permissions

Two gates stack on every call. The token's scope says what the app was granted; the authorizing user's permission says what that member may do in Kyo. Both must allow the call — granting an app finance:read cannot give a member finance access they don't have in the app.

• Feature grants — crm, hr, finance, metrics, competitors and agents resources require the member's grant for that feature: read-only or full for GET, full for writes. Missing it returns 403 insufficient_permission.
• Workspace settings — PATCH /v1/workspace is admin-only.
• Member profiles — a non-admin may only PATCH their own /v1/users/{id}. Roles, permissions and billing fields are not writable by anyone through the API.
• Automations — creating or updating one requires admin, enforced in the database.
• Private tasks stay hidden exactly as they are in the app: a token can only see the private tasks its authorizing user can see.

Beneath both gates, every request runs against the database as the authorizing user, so workspace isolation and row-level security apply unchanged. The API can never read or write outside the workspace the token was issued for.

Reading data

GET /v1/<resource> lists records; GET /v1/<resource>/{id} fetches one. The join resources (deal_people, deal_labels, space_members) and credits have no /{id} form — list them instead.

curl "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/deals?limit=20" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY"

{
  "data": [
    { "id": "…", "name": "Acme Corp", "value": 5000, "created_at": "…" }
  ],
  "next_cursor": "MjAyNi0wNy0…"
}

Single reads, creates, and updates return { "data": { … } }.

Pagination

Lists use keyset cursors ordered by (created_at, id) descending — stable under concurrent writes, no offsets. The join resources, project_stages and credits are naturally small and return a single bounded page with next_cursor: null.

• limit — page size, default 50, max 200.
• cursor — the next_cursor from the previous page. null means you're on the last page.

GET /v1/deals?limit=100&cursor=MjAyNi0wNy0…

Filtering

Lists accept exact-match query parameters — the "List filters" column in the resources table:

GET /v1/tasks?completed=false&space_id=9a1f…

Writing data

Create

POST /v1/<resource> with a JSON body returns 201 and the created record:

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/deals" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp", "pipeline_id": "<uuid>", "value": 5000 }'

Update

PATCH /v1/<resource>/{id} with a partial body returns 200 and the updated record:

curl -X PATCH "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/deals/<id>" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_stage_id": "<uuid>" }'

Deleting

There is no DELETE in v1 — it returns 405 method_not_allowed everywhere. Records can be created and updated, never hard-deleted through the API.

The one exception is detaching a junction row. To unlink a person or label from a deal, POST to the junction resource with ?detach=true (or "_detach": true in the body). Requires deals:write:

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/deal_people?detach=true" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deal_id": "<uuid>", "person_id": "<uuid>" }'

Errors

Errors are JSON with a machine-readable code and a request id:

{
  "error": "insufficient_scope",
  "message": "…",
  "request_id": "…"
}

Every response includes an X-Request-Id header — include it when reporting an issue so we can trace the request.

Rate limits

• 60 requests / minute per token
• 600 requests / minute per workspace

Responses carry X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding a limit returns 429 rate_limited with Retry-After: 60.

Enrichment

POST /v1/enrich looks up firmographics for a company domain — name, website, industry, and socials. This is the API's only metered endpoint: fresh lookups spend workspace credits, and it requires the opt-in enrich:write scope.

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/enrich" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme.com" }'

Returns 402 insufficient_credits when the workspace balance is too low.

Scopes

Scopes are resource:read / resource:write (the wildcard resource:* is also accepted). A request without the required scope fails with 403 insufficient_scope. Scopes are granted by the user during the OAuth flow and can never exceed what that user can do in the app — see permissions. There is no :delete scope: v1 cannot delete anything.

Changes

Changes to the /v1 surface are listed here, newest first. New resources, scopes and fields are additive — existing calls keep working.