Every endpoint of the public API, generated from the route table that also
serves requests and the OpenAPI document. Request and response bodies are the
JSON mapping of the named platform.v1 messages; fetch
GET /v1/openapi.json for their full schemas. See
API overview for authentication, errors, and rate limits.
Access is read or write: read-only tokens may call only
read endpoints. Some endpoints also need a broader token scope than project;
the Scope column names the narrowest token that may call them. See
API tokens.
Two endpoints need no token: GET /v1/health and
GET /v1/openapi.json.
#Identity
| Endpoint | Description | Access | Scope |
|---|
GET /v1/me | Identity behind an account-scoped token. | read | account |
GET /v1/token | Introspect the presented token. | read | project |
#API tokens
| Endpoint | Description | Access | Scope |
|---|
GET /v1/api-tokens | List the caller's API tokens, or a workspace's tokens for its admins. Query: workspace_id, include_revoked. Returns ListAPITokensResponse. | read | account |
POST /v1/api-tokens | Create an API token; the secret is returned once. Body: CreateAPITokenRequest. Returns CreateAPITokenResponse. | write | account |
DELETE /v1/api-tokens/{tokenId} | Revoke an API token (its creator, or an admin of its workspace). | write | account |
#GitHub
| Endpoint | Description | Access | Scope |
|---|
GET /v1/github/connection | The caller's GitHub connection. Returns GitHubConnection. | read | account |
POST /v1/github/connection | Start connecting GitHub: open the returned authorization_url in a browser. Body: StartGitHubConnectionRequest. Returns StartGitHubConnectionResponse. | write | account |
DELETE /v1/github/connection | Disconnect GitHub. | write | account |
GET /v1/github/repositories | Repositories the connected GitHub account can deploy (where the GitHub App is installed). Returns ListGitHubRepositoriesResponse. | read | account |
GET /v1/github/repositories/{owner}/{repo}/branches | Branches of a repository. Returns ListGitHubBranchesResponse. | read | account |
GET /v1/github/repositories/{owner}/{repo}/dockerfiles | Dockerfile paths of a repository at a ref. Query: ref. Returns ListGitHubDockerfilesResponse. | read | account |
#Limits
| Endpoint | Description | Access | Scope |
|---|
GET /v1/limits | Workload storage, image, and process limits. | read | project |
#Regions
| Endpoint | Description | Access | Scope |
|---|
GET /v1/regions | List configured workload regions with country codes, new-service admission policy and platform default. Returns ListRegionsResponse. | read | project |
PUT /v1/regions/{regionId} | Create or update a region (operator only); closing admission preserves deployments and recovery for existing services. Body: Region. Returns Region. | write | account |
#Workspaces and members
| Endpoint | Description | Access | Scope |
|---|
GET /v1/workspaces | List the caller's workspaces and pending invitations. Returns ListWorkspacesResponse. | read | workspace |
POST /v1/workspaces | Create a workspace. Body: CreateWorkspaceRequest. Returns Workspace. | write | account |
GET /v1/workspaces/{workspaceId} | Get a workspace. Returns Workspace. | read | workspace |
PATCH /v1/workspaces/{workspaceId} | Rename a workspace. Body: RenameWorkspaceRequest. Returns Workspace. | write | account |
DELETE /v1/workspaces/{workspaceId} | Delete a workspace with no live projects (confirmation_name must match). | write | account |
GET /v1/workspaces/{workspaceId}/members | List workspace members and invitations. Returns ListWorkspaceMembersResponse. | read | workspace |
POST /v1/workspaces/{workspaceId}/invitations | Invite a member by email. Body: InviteWorkspaceMemberRequest. Returns WorkspaceInvitation. | write | account |
PATCH /v1/workspaces/{workspaceId}/members/{userId} | Change a member's role. Body: UpdateWorkspaceMemberRoleRequest. Returns WorkspaceMember. | write | account |
DELETE /v1/workspaces/{workspaceId}/members/{userId} | Remove a member (removing yourself leaves the workspace). | write | account |
DELETE /v1/workspace-invitations/{invitationId} | Revoke an invitation. | write | account |
POST /v1/workspace-invitations/{invitationId}/accept | Accept an invitation addressed to the caller. Returns Workspace. | write | account |
POST /v1/workspace-invitations/{invitationId}/decline | Decline an invitation addressed to the caller. | write | account |
#Projects
| Endpoint | Description | Access | Scope |
|---|
GET /v1/projects | List projects. Query: workspace_id, include_deleted, include_summaries. Returns ListProjectsResponse. | read | workspace |
POST /v1/projects | Create a project (empty workspace_id uses the personal workspace). Body: CreateProjectRequest. Returns Project. | write | workspace |
GET /v1/projects/{projectId} | Get a project. Returns Project. | read | project |
DELETE /v1/projects/{projectId} | Delete a project (confirmation_name must match; restorable during grace). | write | workspace |
POST /v1/projects/{projectId}/restore | Restore a deleted project. Returns Project. | write | workspace |
PATCH /v1/projects/{projectId}/log-retention | Set log retention days. Query: 1-90. Returns Project. | write | workspace |
GET /v1/projects/{projectId}/deletion-preview | Preview what deleting the project would tombstone. Returns DeletionPreview. | read | workspace |
POST /v1/projects/{projectId}/move | Move a project to another workspace. Returns Project. | write | account |
GET /v1/projects/{projectId}/environments | List environments. Query: include_deleted. Returns ListEnvironmentsResponse. | read | workspace |
POST /v1/projects/{projectId}/environments | Create an environment. Body: CreateEnvironmentRequest. Returns Environment. | write | workspace |
POST /v1/projects/{projectId}/github-repository | Link and inspect a GitHub repository for the project. Body: LinkGitHubRepositoryRequest. Returns InspectSourceResponse. | write | workspace |
POST /v1/source-inspections | Inspect a source repository without linking it. Body: InspectSourceRequest. Returns InspectSourceResponse. | read | workspace |
#Environments and releases
| Endpoint | Description | Access | Scope |
|---|
GET /v1/environments/{environmentId} | Get an environment. Returns Environment. | read | project |
PATCH /v1/environments/{environmentId} | Rename an environment. Returns Environment. | write | workspace |
PATCH /v1/environments/{environmentId}/auto-deploy | Toggle auto-deploy on tracked-ref changes. Returns Environment. | write | project |
POST /v1/environments/{environmentId}/duplicate | Duplicate an environment (copy_variables optional). Returns Environment. | write | workspace |
DELETE /v1/environments/{environmentId} | Delete an environment (production requires confirmation_name). | write | workspace |
POST /v1/environments/{environmentId}/restore | Restore a deleted environment. Returns Environment. | write | workspace |
GET /v1/environments/{environmentId}/deletion-preview | Preview what deleting the environment would tombstone. Returns DeletionPreview. | read | workspace |
POST /v1/environments/{environmentId}/releases | Release the environment: deploy every staged service change. Returns ReleaseEnvironmentResponse. | write | project |
POST /v1/environments/{environmentId}/services/from-repository | Link a GitHub repository and stage a service built from it, with defaults from its inspection. Body: CreateServiceFromRepositoryRequest. Returns Service. | write | workspace |
#Services
| Endpoint | Description | Access | Scope |
|---|
GET /v1/environments/{environmentId}/services | List services and volumes in an environment; long-poll with wait_index. Query: include_deleted, wait_index, wait_timeout_seconds. Returns ListServicesResponse. | read | project |
POST /v1/environments/{environmentId}/services | Create a service (staged until the environment is released). Body: CreateServiceRequest. Returns Service. | write | project |
GET /v1/services/{serviceId} | Get a service. Query: source. Returns Service. | read | project |
PUT /v1/services/{serviceId} | Replace a service draft (expected_spec_revision must be current; staged until release). Body: UpdateServiceRequest. Returns Service. | write | project |
DELETE /v1/services/{serviceId} | Delete a service (restorable during grace). | write | project |
POST /v1/services/{serviceId}/duplicate | Copy a service's draft and variables into a new staged service named -copy. Returns Service. | write | project |
POST /v1/services/{serviceId}/restore | Restore a deleted service. Returns Service. | write | project |
GET /v1/services/{serviceId}/status | Service with live allocation status; long-poll with wait_index. Query: wait_index, wait_timeout_seconds. Returns ServiceStatus. | read | project |
POST /v1/services/{serviceId}/scale | Set the desired replica count. Returns ServiceStatus. | write | project |
POST /v1/services/{serviceId}/discard-changes | Discard staged service changes (change_ids or discard_all). Body: DiscardServiceChangesRequest. Returns Service. | write | project |
#Deployments, builds, and logs
| Endpoint | Description | Access | Scope |
|---|
GET /v1/services/{serviceId}/deployments | List deployment attempts, newest first (limit); never-released staged configuration is not listed. Returns ListServiceDeploymentsResponse. | read | project |
POST /v1/services/{serviceId}/deployments/{deploymentId}/actions | Act on a deployment: restart, exact redeploy, rollback, cancel, remove, retry. Body: ApplyDeploymentActionRequest. Returns ServiceStatus. | write | project |
GET /v1/services/{serviceId}/logs | Service logs. Query: log_type, limit, search, times. Returns ListServiceLogsResponse. | read | project |
GET /v1/services/{serviceId}/artifacts | List built image artifacts. Query: limit. Returns ListServiceArtifactsResponse. | read | project |
GET /v1/services/{serviceId}/builds/{buildId}/attempts | List attempts of one build. Returns ListBuildAttemptsResponse. | read | project |
#Domains
| Endpoint | Description | Access | Scope |
|---|
GET /v1/services/{serviceId}/domains | List domain bindings of a service. Query: include_deleted. Returns ListDomainBindingsResponse. | read | project |
POST /v1/services/{serviceId}/domains | Bind a custom hostname to a service port. Body: DomainBindingInput. Returns DomainBinding. | write | project |
POST /v1/services/{serviceId}/generated-domain | Generate a platform hostname for a service port. Body: GenerateDomainBindingRequest. Returns DomainBinding. | write | project |
GET /v1/domains/{hostname} | Get a domain binding, with ownership and certificate state. Returns DomainBinding. | read | project |
PATCH /v1/domains/{hostname} | Retarget a domain binding to a service port. Body: DomainBindingTarget. Returns DomainBinding. | write | project |
DELETE /v1/domains/{hostname} | Delete a domain binding (restorable during grace). | write | project |
POST /v1/domains/{hostname}/restore | Restore a deleted domain binding. Returns DomainBinding. | write | project |
#Volumes
| Endpoint | Description | Access | Scope |
|---|
GET /v1/environments/{environmentId}/volumes | List volumes in an environment. Query: include_deleted. Returns ListVolumesResponse. | read | project |
POST /v1/environments/{environmentId}/volumes | Create a volume (staged until the environment is released). Body: CreateVolumeRequest. Returns Volume. | write | project |
GET /v1/volumes/{volumeId} | Get one volume by ID. Returns Volume. | read | project |
PATCH /v1/volumes/{volumeId} | Try to grow a volume without downtime; allow_offline_resize confirms a restart after live resize fails. Body: UpdateVolumeRequest. Returns Volume. | write | project |
POST /v1/volumes/{volumeId}/move | Preview an offline volume move; confirm with the preview target to authorize downtime (all plans). Body: MoveVolumeRequest. Returns VolumeMove. | write | project |
DELETE /v1/volumes/{volumeId} | Delete a volume (confirmation_name must match). | write | project |
GET /v1/volumes/{volumeId}/deletion-preview | Preview what deleting the volume affects. Returns DeletionPreview. | read | project |
#Templates
| Endpoint | Description | Access | Scope |
|---|
GET /v1/templates | List curated templates (database_only filters the same catalog). Returns ListTemplatesResponse. | read | project |
POST /v1/environments/{environmentId}/templates | Atomically stage every service, volume, and public route in a template. Body: CreateTemplateRequest. Returns CreateTemplateResponse. | write | project |
#Usage
Usage queries default end_time to now and start_time to 24 hours, 7 days, or 30 days before the end for minute, hour (default), or day resolution respectively.
| Endpoint | Description | Access | Scope |
|---|
GET /v1/workspaces/{workspaceId}/usage | Usage totals per project of a workspace. Query: start_time, end_time, resolution. Returns WorkspaceUsage. | read | workspace |
GET /v1/projects/{projectId}/usage | Project resource usage. Query: start_time, end_time, resolution, filters. Returns ProjectUsage. | read | project |
#Recently deleted
| Endpoint | Description | Access | Scope |
|---|
GET /v1/deleted-resources | Restorable deleted projects, environments, services, volumes, and domains, newest first. Query: workspace_id. Returns ListDeletedResourcesResponse. | read | workspace |
#Billing
| Endpoint | Description | Access | Scope |
|---|
GET /v1/billing/plans | Plans with their prices, limits, and rules. Returns ListBillingPlansResponse. | read | project |
GET /v1/workspaces/{workspaceId}/billing | Billing account summary for the workspace; unknown plans use trial resource caps. Returns BillingAccountSummary. | read | workspace |
GET /v1/workspaces/{workspaceId}/billing/statements | List billing statements. Query: limit. Returns ListBillingStatementsResponse. | read | workspace |
GET /v1/workspaces/{workspaceId}/billing/statements/{statementId} | Get a billing statement. Query: include_csv. Returns BillingStatement. | read | workspace |
PATCH /v1/workspaces/{workspaceId}/billing/budget | Set the gross-usage budget stop in cents (0 clears). Returns BillingAccountSummary. | write | account |
POST /v1/workspaces/{workspaceId}/billing/plan | Change the billing plan. Returns BillingAccountSummary. | write | account |
POST /v1/workspaces/{workspaceId}/billing/payment-setup | Start payment method setup; returns a checkout URL. Returns StartBillingPaymentSetupResponse. | write | account |
POST /v1/workspaces/{workspaceId}/billing/activation | Choose a paid plan; returns a Checkout link while no card is saved. Returns StartBillingActivationResponse. | write | account |
POST /v1/workspaces/{workspaceId}/billing/cancel | Cancel the billing account (effective at period end). Returns CancelBillingAccountResponse. | write | account |
#Fleet
| Endpoint | Description | Access | Scope |
|---|
GET /v1/fleet | Fleet agents with presence, allocations, and schedulable capacity (operators only). Returns Fleet. | read | account |
POST /v1/fleet/agents | Enroll a fleet agent; the bootstrap token is returned once (operators only). Body: CreateAgentRequest. Returns AgentEnrollment. | write | account |
PATCH /v1/fleet/agents/{agentId} | Update a fleet agent's placement and reserved capacity (operators only). Body: UpdateAgentRequest. Returns Agent. | write | account |
POST /v1/fleet/agents/{agentId}/lifecycle | Cordon, drain, activate, or retire a fleet agent (operators only). Body: SetAgentLifecycleRequest. Returns Agent. | write | account |