Profile
How to manage your personal details, language, regional formats, theme, sign-in methods and notification channels, and which account pages live outside an organization.
Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.
Profile
How to manage your personal details, language, regional formats, theme, sign-in methods and notification channels, and which account pages live outside an organization.
Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.
CentraKit REST API base URLs, authentication, organization scoping, pagination, and a map of every route under /api/v1.
The CentraKit API app serves a versioned REST API under /api/v1 and the product MCP server at /api/mcp. The SaaS app, the CLI and MCP clients all call the same routes, with the same permission checks and the same error format.
| Environment | Base URL |
|---|---|
| Production | https://api.centrakit.com/api |
| Local (Portless) | https://api.localhost/api |
Every path in the OpenAPI spec starts with /v1, so a full URL looks like https://api.centrakit.com/api/v1/organizations. Keep /api in any base URL you configure, because the route handlers live under that prefix. Locally, run pnpm dev:portless (or pnpm dev:api:portless for the API only) to serve https://api.localhost.
curl https://api.centrakit.com/api/v1/health{ "ok": true, "service": "api", "version": "v1" }Routes accept either a Supabase browser session cookie or a bearer access token:
Authorization: Bearer <access-token>When a request carries a bearer token, the API verifies its issuer, audience, signature and expiry before it runs the route. Without a bearer token, the API reads the Supabase session cookie. Use bearer tokens for scripts, CI, the CLI and MCP hosts. See Authentication for how to obtain a token.
With the CLI:
centrakit --token <access-token> orgs listTenant data lives under /api/v1/organizations/{organizationId}/..., where organizationId is the organization UUID (not its slug). There is no current-organization header or cookie: every organization-scoped request names its organization in the path.
To find the IDs you can use, call GET /api/v1/organizations. PATCH /api/v1/users/me/active-organization stores a preferred default organization on your profile for clients that need one, but it never replaces the organization ID in the path or any permission check.
Each operation under /organizations/{organizationId} checks one organization permission before it reads or writes data. Reads require the matching view permission, and mutations require the operation's create, update, delete or lifecycle permission, for example organization.webhooks.update for rotating a webhook secret. The check runs the same way for cookie and bearer requests:
401.403 with code ORGANIZATION_PERMISSION_DENIED.Row Level Security in the database still applies on top of this check. See RBAC and Tenancy for the permission model.
Most list endpoints use offset pagination with these query parameters:
| Parameter | Default | Limits | Meaning |
|---|---|---|---|
offset | 0 | 0 or more | Number of items to skip. |
limit | 50 | 1 to 100 | Page size. |
q | none | 200 characters | Free-text search, on endpoints that support it. |
A list response wraps its items in data and reports the range in pagination:
{
"data": [{ "id": "..." }],
"pagination": {
"offset": 0,
"limit": 50,
"total": 1240,
"hasMore": true,
"totalIsEstimate": true
}
}hasMore is the reliable signal for whether another page exists. Request the next page with offset plus limit.total is exact unless totalIsEstimate is true. Large collections such as tasks, quotes, invoices, customer assets, file drives, organizations and members use an estimated count by default, so treat total as approximate when the flag is set.A few endpoints use their own limits. Collaboration reference search defaults to 20 results (maximum 50), command center search to 24 (maximum 40), inbox threads to 30 (maximum 100) and the notification inbox to 10 (maximum 20). Chat message lists count offset from the newest message window. The OpenAPI reference lists the parameters for each operation.
Paths in these tables are relative to /api/v1/organizations/{organizationId}. Operation names, request bodies and response schemas are in the generated reference described on OpenAPI.
| Path | Methods |
|---|---|
| (the organization itself) | GET, PATCH, DELETE |
/members | GET, POST (invite) |
/members/{userId} | GET, PATCH (role) |
/invitations | GET |
/invitations/{invitationId} | GET, PATCH, DELETE |
/teams | GET, POST |
/teams/{teamId} | GET, PATCH, DELETE |
/teams/{teamId}/members | PUT |
/branding/logo | POST, DELETE |
/branding/brand-images | POST |
/branding/brand-images/{brandImageId} | DELETE |
| Path | Methods |
|---|---|
/customers | GET, POST |
/customers/{customerId} | GET, PATCH, DELETE |
/customers/{customerId}/contacts | POST |
/customers/{customerId}/contacts/{contactId} | GET, PATCH, DELETE |
/customers/{customerId}/contacts/{contactId}/primary | POST |
/customers/{customerId}/locations | POST |
/customers/{customerId}/locations/{locationId} | GET, PATCH, DELETE |
/customers/{customerId}/locations/{locationId}/primary | POST |
/customers/{customerId}/notes | POST |
/customers/{customerId}/notes/{noteId} | PATCH, DELETE |
/customer-assets | GET, POST |
/customer-assets/{customerAssetId} | GET, PATCH, DELETE |
/customer-assets/{customerAssetId}/notes | GET, POST |
/customer-assets/{customerAssetId}/notes/{noteId} | PATCH, DELETE |
| Path | Methods |
|---|---|
/products | GET, POST |
/products/{productId} | GET, PATCH, DELETE |
/products/{productId}/suppliers | POST |
/products/{productId}/suppliers/{linkId} | PATCH, DELETE |
/product-categories | GET, POST |
/product-categories/{categoryId} | GET, PATCH, DELETE |
/product-categories/{categoryId}/move | POST |
/suppliers | GET, POST |
/suppliers/{supplierId} | GET, PATCH, DELETE |
/brands | GET, POST |
/brands/{brandId} | GET, PATCH, DELETE |
/tags | GET, POST |
/tags/{tagId} | GET, PATCH, DELETE |
/templates | GET, POST |
/templates/{templateId} | GET, PATCH, DELETE |
Templates cover quote, invoice and task templates.
| Path | Methods |
|---|---|
/inventory/levels | GET |
/inventory/locations | GET, POST |
/inventory/stock-records | GET, POST |
/inventory/stock-records/{stockRecordId} | PATCH, DELETE (archive) |
/inventory/stock-adjustments | POST |
/inventory/movements | GET |
/inventory/allocations | GET |
| Path | Methods |
|---|---|
/quotes | GET, POST |
/quotes/{quoteId} | GET, PATCH, DELETE |
/quotes/{quoteId}/send | POST |
/quotes/{quoteId}/accept | POST |
/quotes/{quoteId}/reject | POST |
/quotes/{quoteId}/duplicate | POST |
/quotes/{quoteId}/assets | PUT |
/quotes/{quoteId}/tasks | PUT |
/quotes/{quoteId}/lifecycle | GET |
/quotes/{quoteId}/lifecycle/advance | POST |
/quotes/{quoteId}/notes | GET, POST |
/quotes/{quoteId}/notes/{noteId} | PATCH, DELETE |
See Quotes.
| Path | Methods |
|---|---|
/invoices | GET, POST |
/invoices/from-quote | POST |
/invoices/{invoiceId} | GET, PATCH, DELETE |
/invoices/{invoiceId}/send | POST |
/invoices/{invoiceId}/payments | POST |
/invoices/{invoiceId}/mark-paid | POST |
/invoices/{invoiceId}/write-off | POST |
/invoices/{invoiceId}/cancel | POST |
/invoices/{invoiceId}/duplicate | POST |
/invoices/{invoiceId}/pause-reminders | POST |
/invoices/{invoiceId}/resume-reminders | POST |
/invoices/{invoiceId}/lifecycle | GET |
/invoices/{invoiceId}/lifecycle/advance | POST |
/invoices/{invoiceId}/notes | GET, POST |
/invoices/{invoiceId}/notes/{noteId} | PATCH, DELETE |
See Invoices.
| Path | Methods |
|---|---|
/orders | GET, POST |
/orders/{orderId} | GET |
/orders/{orderId}/confirm | POST |
/orders/{orderId}/cancel | POST |
/orders/{orderId}/lifecycle | GET |
/orders/{orderId}/lifecycle/advance | POST |
/shipments | GET |
/shipments/{shipmentId} | GET |
/shipments/{shipmentId}/ship | POST |
/purchase-orders | GET, POST |
/purchase-orders/{purchaseOrderId} | GET |
/purchase-orders/{purchaseOrderId}/receive | POST |
/promotions/validate | POST |
Creating, confirming and cancelling orders, shipping a shipment, and creating or receiving a purchase order run the organization's approval policy. When a policy requires approval, the route answers 409 with code APPROVAL_REQUIRED and an approvalId. See Errors, Orders and Approvals.
| Path | Methods |
|---|---|
/tasks | GET, POST |
/tasks/reorder | POST |
/tasks/{taskId} | GET, PATCH, DELETE |
/tasks/{taskId}/status | PATCH |
/tasks/{taskId}/assignees | PUT |
/tasks/{taskId}/comments | GET, POST |
/tasks/{taskId}/comments/{commentId} | PATCH, DELETE |
/tasks/{taskId}/time-entries | GET, POST |
/tasks/{taskId}/time-entries/{entryId} | DELETE |
/tasks/{taskId}/lifecycle | GET |
/tasks/{taskId}/lifecycle/advance | POST |
/agenda/items | GET, POST |
/agenda/items/{agendaItemId} | GET, PATCH, DELETE |
/agenda/items/{agendaItemId}/move | POST |
| Path | Methods |
|---|---|
/employees | GET, POST |
/employees/{employeeId} | GET, PATCH |
/time-entries | GET, POST |
/time-off-requests | GET, POST |
/expenses | GET, POST |
/approvals | GET, POST |
/hiring/jobs | GET |
/hiring/jobs/{jobId}/applications | GET |
GET /approvals lists the time-off requests, timesheets and expense claims waiting for the caller's decision, including delegated ones. POST /approvals approves or rejects up to 100 of them at once, and each decision succeeds or fails on its own.
| Path | Methods |
|---|---|
/files/drives | GET |
/files/nodes/{nodeId} | GET |
/files/nodes/{nodeId}/children | GET |
/files/nodes/{nodeId}/download | GET |
/files/copy | POST |
/files/uploads | POST |
/files/uploads/{reservationId}/finalize | POST |
/files/uploads/{reservationId}/cancel | POST |
/files/zip-exports | POST |
/files/zip-exports/{exportId} | GET |
Uploads are reserved first, then finalized or cancelled. See Files.
| Path | Methods |
|---|---|
/inbox/threads | GET |
/inbox/threads/{threadId}/messages | GET, POST (reply) |
/inbox/threads/{threadId}/suggestions | POST |
/inbox/attachments | POST |
/inbox/attachments/{attachmentId} | GET |
/inbox/deliveries/{deliveryId} | GET |
/knowledge/retrieve | POST |
/collaboration/references | GET |
/ai/threads | GET, POST |
/ai/threads/{threadId}/messages | GET, POST |
/ai/models | GET |
/ai/activity | GET |
/ai/agent-runs/{runId} | GET |
/ai/agent-runs/{runId}/events | GET |
/ai/agent-runs/{runId}/handoff | POST |
/ai/agent-runs/{runId}/approvals/{approvalId} | POST |
/ai/contextual-actions/{actionId} | GET |
/ai/contextual-artifacts | GET |
/ai/contextual-artifacts/{artifactId} | GET, PATCH |
/channels/{connectionId}/webhook | GET, POST |
Only /ai/threads/{threadId}/messages from the /ai group is in the OpenAPI spec. The other /ai routes serve the SaaS assistant and agent-run viewer and can change without notice. /channels/{connectionId}/webhook receives provider callbacks for an inbox channel connection (WhatsApp) and queues them for processing; it is not for API clients. See Inbox, Chat and Knowledge.
| Path | Methods |
|---|---|
/notifications | GET |
/notifications/inbox | GET |
/notifications/{notificationId} | PATCH |
/notifications/mark-all-read | POST |
/notification-preferences | GET, PUT |
/notification-subscriptions | GET, POST |
/notification-subscriptions/{subscriptionId} | DELETE |
| Path | Methods |
|---|---|
/workflows/definitions | GET |
/workflows/definitions/{definitionId} | GET |
/workflows/definitions/{definitionId}/publish | POST |
/workflows/definitions/{definitionId}/runs | POST (start a run) |
/workflows/runs | GET |
/workflows/runs/{runId} | GET |
/workflows/runs/{runId}/approval | POST |
/workflows/runs/{runId}/cancel | POST |
/webhooks/destinations | GET, POST |
/webhooks/destinations/{destinationId} | GET, PATCH, DELETE |
/webhooks/destinations/{destinationId}/rotate-secret | POST |
/webhooks/endpoints | GET, POST |
/webhooks/endpoints/{endpointId} | GET, PATCH, DELETE |
/webhooks/endpoints/{endpointId}/rotate-secret | POST |
/webhooks/endpoints/{endpointId}/rotate-token | POST |
/webhooks/deliveries | GET |
/webhooks/deliveries/{deliveryId} | GET |
| Path | Methods |
|---|---|
/audit-events | GET |
/audit-exports | POST |
/audit-exports/{exportId} | GET |
See Audit log.
These paths are relative to /api/v1.
| Path | Methods | Purpose |
|---|---|---|
/health | GET | Versioned health check. No authentication. |
/auth/login | POST | Email and password sign-in. Creates a cookie session and returns the user. |
/auth/signup | POST | Create an account with email and password. |
/auth/logout | POST | Clear the current session. |
/auth/oauth/start | GET | Create the authorization URL for an OAuth sign-in provider. |
/auth/password/reset | POST | Send a password reset email. |
/auth/password/update | POST | Set a new password for the signed-in user. |
/users/me | GET | The authenticated user. |
/users/me/active-organization | PATCH | Store the preferred default organization. |
/organizations | GET, POST | List organizations you can access, or create one. |
/command-center/search | GET | Search records for the command center. |
/agenda/google-calendar/oauth/start | GET | Start the Google Calendar integration authorization. |
The /ai/chat routes (/ai/chat, /ai/chat/threads, /ai/chat/{threadId} with participants, share, stop and stream, /ai/chat/attachments, /ai/chat/follow-ups and /ai/chat/starter-suggestions), /ai/specialists and /ai/transcribe power the in-app assistant. /workflows/graph-operations powers AI edits in the workflow editor. They are session transports for the SaaS app, are not in the OpenAPI spec, and are not a stable integration surface.
These routes take no session. The token or the published record in the path is the credential.
| Path | Methods | Purpose |
|---|---|---|
/public/calendars/{token} | GET | iCalendar feed for a shared agenda calendar. |
/public/time-off/{token} | GET | iCalendar feed of approved team leave. |
/public/chats/{token} | GET | Read-only shared chat. |
/public/files/{token} | GET | Redirect to a signed download URL for a shared file. |
/public/onboarding/{token} | GET, POST | New-hire pre-boarding page and details form. |
/public/onboarding/{token}/documents | POST | Upload a pre-boarding document. |
/public/portal/{orgSlug}/quotes/{quoteId}/request-changes | POST | A customer requests changes to a sent quote. |
/public/webhooks/{token} | POST | Receive an incoming organization webhook. |
The pre-boarding, quote change request and incoming webhook routes are rate limited and answer 429 when a caller sends too many requests. See Customer portal and Webhooks.
| Path | Methods | Caller |
|---|---|---|
/billing/stripe/webhook | POST | Stripe, verified with the stripe-signature header. |
/email/resend/webhook | POST | Resend, verified with the svix-* signature headers. |
/email/supabase/auth | POST | The Supabase Auth send-email hook. |
/organizations/{organizationId}/channels/{connectionId}/webhook (listed above) is the per-connection inbox channel callback. See Stripe billing.
Vercel Cron calls these GET routes with Authorization: Bearer <CRON_SECRET>. They answer 401 to any other caller.
| Path | Schedule (UTC) |
|---|---|
/internal/webhook-deliveries | Every minute |
/internal/channel-webhook-jobs | Every minute |
/internal/files/zip-exports | Every minute |
/internal/inventory/signals | Every minute |
/internal/google-calendar-sync | Every 5 minutes |
/workflows/scheduler/watchdog | Every 5 minutes |
/internal/approvals/sweep | Every 10 minutes |
/internal/files/upload-reconciliation | Every 15 minutes |
/workflows/audit-log/retention | Daily at 02:17 |
/internal/people/daily | Daily at 06:07 |
/internal/commerce/daily | Daily at 06:17 |
/admin/subscriptions/{orgSlug}/invoices/{invoiceId}/pdf serves subscription invoice PDFs to platform administrators with system.billing.view.
Every error is an RFC 9457 problem details document served as application/problem+json, with a stable code and a messageKey. See Errors.
The OpenAPI spec is committed at apps/api/public/openapi.json. Inside the monorepo, @workspace/api-client wraps a Hey API client generated from that spec, and the CLI and the MCP server both use it. See OpenAPI.
Last updated on
Profile
How to manage your personal details, language, regional formats, theme, sign-in methods and notification channels, and which account pages live outside an organization.
Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.