REST API reference

Use https://api.dexto.ai/v1 from your backend with an API key. The public API host accepts /v1/* and /healthz; dashboard sessions and the app’s private /api/* routes do not work there.

curl https://api.dexto.ai/v1/models \
  -H "Authorization: Bearer $DEXTO_API_KEY"

Authentication

A developer API key, created on your Cloud project’s page, acts in that Cloud project: everything it creates belongs to the project, and it sees only that project’s resources.

Beta. A person can also call /v1 as themselves with the OAuth access token the Dexto MCP gives them, when they granted the Read Cloud projects (cloud:read) or Build in Cloud projects (cloud:write) permission. Such a token reaches every Cloud project of its organization, so each request names one in the Dexto-Cloud-Project header:

curl https://api.dexto.ai/v1/secrets \
  -H "Authorization: Bearer $DEXTO_ACCESS_TOKEN" \
  -H "Dexto-Cloud-Project: 4f183ce0-…"

• List the projects with GET /v1/projects; /v1/projects, /v1/models and /v1/billing/summary need no header. An Owner or Admin creates projects with POST /v1/projects.
• cloud:read reads; anything that changes data needs cloud:write.
• What the person creates records them: created_by is { "type": "user", "user_id": "…" }.
• Its usage, including chat completions and media, is Cloud usage of the named project, paid from credits and counted against the project’s spend limit.
• Functions need no header: the path names the project, and the Function’s project pays.
• A key that names a project other than its own is refused with 403.

First public resources

Resource	What you can do	Guide
Models	Discover models and create chat completions	Models
Media	Find models, estimate cost, generate, and read results	Media
Sandboxes	Create project sandboxes, run commands, and work with files	Sandboxes
Files	Store, list, download and share your project’s files	Files
Agents	Define agents and run them for your own users	Agents
Automations	Run your agents on a schedule or on a signed webhook	Automations
Secrets	Store API keys your agents use without seeing them	Secrets
Projects	Beta: list and create the Cloud projects you can act in	Authentication

For the complete machine-readable list of currently published /v1 operations, request /v1/openapi.json.

The contract

https://api.dexto.ai/v1/openapi.json is the public contract of /v1: an OpenAPI 3.1 document that needs no key. Generate a client from it; the Dexto CLI does.

• Versioned by path. Everything under /v1 keeps working for /v1 clients. A change that would break one gets a new version path instead.
• Additive. Dexto adds operations, optional request fields, response fields and enum values to /v1 without notice, so a client ignores fields it doesn’t know.
• Stable names. Each operation’s operationId, method and path don’t change once published. A field that is replaced stays beside its replacement, marked deprecated in the document.
• Beta. An operation or field whose description starts with “Beta, may change” is outside these promises until that note is removed.

Common responses

Status	Meaning
400	Invalid request
401	Missing or invalid API key or access token
403	The caller cannot perform this operation
404	Resource not found or not visible to this caller
409	Resource state conflict; see the operation’s error message
429	Rate limit exceeded; wait for the Retry-After period before trying again

Every public operation has a named account-based rate limit. See the OpenAPI document for the policy on each operation. A second API key for the same account does not increase its allowance.