Skip to main content

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:

CredentialHowUse
Console sessionRequests 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 tokenAuthorization: Bearer <token>CLI, scripts, MCP
curl -H "Authorization: Bearer dev-token" http://localhost:4780/api/whoami
Availability

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:

RoleViewManageOwn
OwnerYesYesYes
Org Admin (every project)YesYesYes
Delegated Admin (projects in their part of the org)YesYesYes
Developer (app role developer)YesYesNo
Auditor (every project)YesNoNo

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​

AreaPathsPage
Projects and deployments/projects, /deployments, /projects/:name/eventsProjects 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/jobsIntegrations and requests
Account, directory and notifications/whoami, /directory/*, /notifications, /licenseAccount and directory
Administration/admin/*Admin: governance, Admin: people and sign-in
Was this page helpful?