API Reference
Programmable Workspace
The HTTP surface Gridable serves today: one OpenAI-compatible model endpoint, a per-app gateway for the apps you publish, and webhook triggers for your workflows.
Authentication
All API requests must be authenticated using a Bearer token in the Authorization header. Gridable does not issue standalone API keys today — the token is the session token your account receives when you sign in, so there is nothing separate to generate. The base URL is https://gridable.ai/api; the console and the API are the same origin.
curl https://gridable.ai/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"hello"}]}'App tokens
The per-app gateway does not accept your session token. An app is called with its own credential: a share token created for that app from the console, or a machine token issued to it. A viewer token carries read scope and an editor token carries read and write; a write call made with a viewer token answers 403. The token is bound to exactly one app and one tenant, and the URL cannot widen that — naming a different app in the path answers 403, not that app’s data. Every authenticated gateway response echoes the granted role in X-Gridable-Role, so a client never needs a separate identity call.
CORS policy
The gateway never answers with a wildcard origin. It reflects a request’s Origin only when that origin is the app’s own launch origin (https://{slug}.apps.gridable.ai) or a configured preview origin; anything else gets no CORS headers at all. Access-Control-Allow-Credentials is deliberately never set — the gateway is token-only, so a browser must never send console cookies to it. The two response headers exposed to cross-origin scripts are X-Gridable-Role and X-RateLimit-Remaining.
Chat completions
One endpoint, speaking the OpenAI chat-completions dialect, so an existing OpenAI SDK can point at it unchanged. Authenticate with your session token.
/api/v1/chat/completionsChat Completion
OpenAI-compatible chat completion. Omit model and Gridable’s router picks one for you; the model field on the response names the model that actually served, not the one you asked for. finish_reason is measured rather than assumed — length on a truncated completion, null when the provider failed. Send strict: true and a provider failure becomes a 502 instead of a 200 carrying an apology.
App gateway
Every app you publish gets an HTTP surface at /api/v1/app/{app}, where {app} is the app’s id or slug. It reads and writes that app’s own entities, triggers the workflows the app installed, and records its events. Calls are rate limited per tenant and app — 240 a minute by default — and every authenticated response reports what is left in X-RateLimit-Remaining; exceeding it answers 429.
/api/v1/app/{app}/healthApp Health
Liveness only. The one route on the gateway that needs no token; it returns the app name and nothing else.
/api/v1/app/{app}/entities/{entity}List Records
Records of one entity, by entity name, plural or id. Read scope.
/api/v1/app/{app}/entities/{entity}/{recordId}Read Record
A single record. Read scope.
/api/v1/app/{app}/entities/{entity}Create Record
Create one record. Requires an editor token — a viewer token answers 403.
/api/v1/app/{app}/entities/{entity}/{recordId}Update Record
Update one record. Requires an editor token.
/api/v1/app/{app}/entities/{entity}/{recordId}Delete Record
Delete one record. Requires an editor token.
/api/v1/app/{app}/workflows/{workflowId}/triggerTrigger Workflow
Run a workflow this app installed. Answers 202 with the run id. Only a workflow whose status is exactly active will fire — one the tenant paused answers 409, so you can tell "switched off" from "wrong id". Requires an editor token.
/api/v1/app/{app}/eventsRecord Event
Append one telemetry event for the app. Answers 201 with the event id. Requires an editor token — a viewer token answers 403.
Webhooks
A workflow whose trigger is a webhook is reachable by anyone holding its id, so treat that id as a credential — and add a secret on the trigger node if the delivery matters.
/api/webhooks/{workflowId}Webhook Trigger
Anonymous trigger for a workflow whose trigger type is webhook. The workflow id in the URL is the address, and the request body becomes the trigger payload. If the trigger node declares a secret, send it in the x-gridable-webhook-secret header; a wrong one answers 401. A workflow that is not active answers 409 rather than accepting the delivery and doing nothing.