REST API
The vastframe REST API is the API the console itself uses. The CLI and the MCP server call the same endpoints, so anything you can click you can also script.
Base URL
https://console.<your-domain>/api
On the local stack, the API answers at http://localhost:4780/api. All paths in this reference are relative to /api.
Authentication
Every request needs an identity:
| Credential | How | Use |
|---|---|---|
| Console session | Requests through the console host carry your signed-in identity (the Edge adds an X-TC-User header) | The console, browser scripts on the console origin |
| Bearer token | Authorization: Bearer <token> | CLI, scripts, MCP |
curl -H "Authorization: Bearer dev-token" http://localhost:4780/api/whoami
Bearer tokens are local dev tokens today (dev-token, or dev-token:<email> to act as a directory user). OAuth access tokens for scripts and the CLI are coming with the platform's authorization server.
Requests without a valid identity answer 401:
{ "error": { "code": "UNAUTHORIZED", "message": "Not signed in. Sign in through the Edge (console), or run `tc login --dev` locally." } }
Organizations
Every request runs in one organization. The organization comes from the host name (console.acme.…). When you call the API on a host that doesn't identify an organization (for example localhost), send:
X-TC-Tenant: acme
Unknown organizations answer 404 UNKNOWN_TENANT; suspended organizations answer 403 TENANT_SUSPENDED. These two come before authentication and use a flat shape: { "error": "UNKNOWN_TENANT", "message": "…" }.
Roles
Project routes check what you may do with that project:
| Role | View | Manage | Own |
|---|---|---|---|
| Owner | Yes | Yes | Yes |
| Org Admin (every project) | Yes | Yes | Yes |
| Delegated Admin (projects in their part of the org) | Yes | Yes | Yes |
Developer (app role developer) | Yes | Yes | No |
| Auditor (every project) | Yes | No | No |
Manage covers deploy, promote, rollback, redeploy, env, access, database writes, storage writes, integration requests and jobs. Own covers transfer, renew, archive, restore and delete. Projects you can't view answer 404 PROJECT_NOT_FOUND; read-only callers get 403 READ_ONLY.
Admin routes under /api/admin need an admin role (Org Admin, Auditor or Delegated Admin). See Access & security for the role model.
Errors
Errors use one shape with a stable code:
{ "error": { "code": "PROJECT_NOT_FOUND", "message": "No project named \"budget\"." } }
Storage endpoints add a fix. Common statuses: 400 bad input, 401 no identity, 402 your licence doesn't allow it, 403 not allowed, 404 not found (or not visible to you), 409 conflict, 413 too large.
Areas
| Area | Paths | Page |
|---|---|---|
| Projects and deployments | /projects, /deployments, /projects/:name/events | Projects and deployments |
| Access, settings and lifecycle | /projects/:name/access, /env, /settings, /archive, … | Access and settings |
| Database | /projects/:name/db/* | Database |
| Storage | /projects/:name/storage/* | Storage |
| Integrations, requests and jobs | /integrations, /requests, /projects/:name/jobs | Integrations and requests |
| Account, directory and notifications | /whoami, /directory/*, /notifications, /license | Account and directory |
| Administration | /admin/* | Admin: governance, Admin: people and sign-in |