Servers API

Deployments and logs API
Backups and jobs API

See the API guide for authentication and retries, or the endpoint index for other resources. All paths below are relative to your dashboard host.

List servers

GET /api/v1/servers

List team server metadata. Unavailable to project-restricted credentials.

Permission: servers:read · Team member · Workspace-wide access required.

MCP: list_servers.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].settingsVersion integer Yes Min 1.
items[].id string Yes Min 1; max 128 characters.
items[].teamId string Yes Min 1; max 128 characters.
items[].name string Yes —
items[].status string Yes "pending", "connected", "disconnected", "disabled", "deleted".
items[].publicAddress string or null Yes —
items[].agentVersion string or null Yes —
items[].lastSeenAt string or null Yes UTC ISO 8601 timestamp.
items[].createdAt string Yes UTC ISO 8601 timestamp.
nextCursor string or null Yes —

Get server

GET /api/v1/servers/{serverId}

Read server metadata. Enrollment and agent credentials are excluded.

Permission: servers:read · Team member · Workspace-wide access required.

MCP: get_server.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

Query parameters

None.

Response: HTTP 200.

Field Type Required Details
settingsVersion integer Yes Min 1.
id string Yes Min 1; max 128 characters.
teamId string Yes Min 1; max 128 characters.
name string Yes —
status string Yes "pending", "connected", "disconnected", "disabled", "deleted".
publicAddress string or null Yes —
agentVersion string or null Yes —
lastSeenAt string or null Yes UTC ISO 8601 timestamp.
createdAt string Yes UTC ISO 8601 timestamp.

Read server metrics

GET /api/v1/servers/{serverId}/metrics

Read bounded host metric samples.

Permission: servers:read · Team member · Workspace-wide access required.

MCP: read_server_metrics.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

Query parameters

Field Type Required Details
limit integer No Default: 25. Min 1; max 100.
cursor string No Min 1; max 2048 characters.
since string No UTC ISO 8601 timestamp.

Response: HTTP 200.

Field Type Required Details
items object[] Yes max 100 items.
items[].id string Yes Min 1; max 128 characters.
items[].observedAt string Yes UTC ISO 8601 timestamp.
items[].cpuPercent number or null Yes —
items[].memoryUsedBytes number or null Yes —
items[].memoryTotalBytes number or null Yes —
items[].diskUsedBytes number or null Yes —
items[].diskTotalBytes number or null Yes —
items[].networkReceiveBytesPerSecond number or null Yes —
items[].networkTransmitBytesPerSecond number or null Yes —
nextCursor string or null Yes —

Rename server

PATCH /api/v1/servers/{serverId}

Rename a server. Requires current team administrator role.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
settingsVersion integer Yes Min 1.
name string Yes Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9]$. Min 2; max 100 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
settingsVersion integer Yes Min 1.
id string Yes Min 1; max 128 characters.
teamId string Yes Min 1; max 128 characters.
name string Yes —
status string Yes "pending", "connected", "disconnected", "disabled", "deleted".
publicAddress string or null Yes —
agentVersion string or null Yes —
lastSeenAt string or null Yes UTC ISO 8601 timestamp.
createdAt string Yes UTC ISO 8601 timestamp.

Create server

POST /api/v1/servers

Create a pending server. Enrollment credentials are generated separately in the browser.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

JSON body

Field Type Required Details
name string Yes Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*[A-Za-z0-9]$. Min 2; max 100 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 201.

Field Type Required Details
settingsVersion integer Yes Min 1.
id string Yes Min 1; max 128 characters.
teamId string Yes Min 1; max 128 characters.
name string Yes —
status string Yes "pending", "connected", "disconnected", "disabled", "deleted".
publicAddress string or null Yes —
agentVersion string or null Yes —
lastSeenAt string or null Yes UTC ISO 8601 timestamp.
createdAt string Yes UTC ISO 8601 timestamp.

Enable server

POST /api/v1/servers/{serverId}/enable

Enable a disabled server. Requires current administrator role.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

JSON body

None.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
serverId string Yes Min 1; max 128 characters.
enabled boolean Yes Exactly true.

Disable server

POST /api/v1/servers/{serverId}/disable

Disable a server using its name as confirmation. Requires current administrator role.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
confirmationName string Yes Min 1; max 100 characters.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
serverId string Yes Min 1; max 128 characters.
enabled boolean Yes Exactly false.

Delete server

DELETE /api/v1/servers/{serverId}

Delete a server using its name as confirmation. Existing deployment cancellation is an explicit option.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

JSON body

Field Type Required Details
confirmationName string Yes Min 1; max 100 characters.
cancelOngoingDeployments boolean No Default: true.

Send Idempotency-Key as a header, not a body field.

Response: HTTP 200.

Field Type Required Details
serverId string Yes Min 1; max 128 characters.
status string Yes Exactly "deleted".

Get server delete diagnostic

GET /api/v1/servers/{serverId}/delete-diagnostic

Read counts of active project and environment assignments affected by server deletion.

Permission: servers:write · Owner/admin · Workspace-wide access required.

MCP: Not exposed.

Path parameters

Field Type Required Details
serverId string Yes Min 1; max 128 characters.

Query parameters

None.

Response: HTTP 200.

Field Type Required Details
serverId string Yes Min 1; max 128 characters.
projectCount integer Yes Min 0.
environmentCount integer Yes Min 0.