{ "openapi": "3.1.0", "info": { "title": "Helicarrier Cloud automation API", "version": "2026-10-07", "description": "REST endpoints used by the hosted MCP integration, with additional REST pagination parameters. This is the customer automation surface, not the operator administration API. Generated from the application catalog and verified route registrations." }, "servers": [ { "url": "https://app.helicarrier.xyz" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "identity", "description": "Identity & plans" }, { "name": "projects", "description": "Projects & environments" }, { "name": "services", "description": "Services & configuration" }, { "name": "deployments", "description": "Deployments" }, { "name": "observability", "description": "Logs & metrics" }, { "name": "variables", "description": "Variables & references" }, { "name": "networking", "description": "Domains & networking" }, { "name": "databases", "description": "Databases & storage" }, { "name": "cron", "description": "Scheduled jobs" } ], "paths": { "/api/auth/me": { "get": { "operationId": "whoami", "summary": "Identify the current key", "description": "Identify the authenticated caller and discover the resources and permissions available to a scoped key.\n\nAny valid API key. Catalog and identity reads do not require a capability category.", "tags": [ "identity" ], "parameters": [], "responses": { "200": { "description": "The identity response describes the authenticated user and, when present, the service or project key scope, permissions, and environment restrictions. Start here when using a scoped key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "email": { "type": "string" }, "keyScope": { "type": "object", "properties": { "kind": { "type": "string" }, "serviceId": { "type": "string" }, "serviceName": { "type": "string" }, "permissions": { "type": "object", "properties": { "deployments": { "type": "string", "description": "Deployment records, ordered newest first." }, "logs": { "type": "string", "description": "Runtime log records." } }, "additionalProperties": true, "description": "Capability categories granted to the key, at read or write level." } }, "additionalProperties": true, "description": "Present for a service or project key; describes its resource and capability restrictions." } }, "additionalProperties": true }, "example": { "id": "usr_example", "name": "Alex", "email": "alex@example.com", "keyScope": { "kind": "service", "serviceId": "svc_example", "serviceName": "my-app", "permissions": { "deployments": "write", "logs": "read" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "whoami", "x-read-only": true } }, "/api/projects": { "get": { "operationId": "list_projects", "summary": "List projects", "description": "List projects visible to your account, including their service counts and environment summaries.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "projects" ], "parameters": [], "responses": { "200": { "description": "The `serviceCount` is the actual count. The `services` field is a capped preview of service types for project cards, not a list of full service records. Use Get project for services in a specific environment.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "description": { "type": "string", "description": "Description of the resource or capability." }, "serviceCount": { "type": "integer", "description": "Total number of services, not the length of the preview array." }, "services": { "type": "array", "items": { "type": "object", "properties": { "sourceType": { "type": "string", "description": "Source used to build or run the service." } }, "additionalProperties": true }, "description": "Services in the selected environment, or type previews in a project listing." } }, "additionalProperties": true } }, "example": [ { "id": "prj_example", "name": "My project", "slug": "my-project", "description": "", "serviceCount": 2, "services": [ { "sourceType": "image" }, { "sourceType": "database", "engine": "postgres" } ] } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_projects", "x-read-only": true }, "post": { "operationId": "create_project", "summary": "Create project", "description": "Create a project to organize related services and environments.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "projects" ], "parameters": [], "responses": { "201": { "description": "Returns the newly created project. Store its id and slug; subsequent project reads use the slug.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "description": { "type": "string", "description": "Description of the resource or capability." } }, "additionalProperties": true }, "example": { "id": "prj_example", "name": "My project", "slug": "my-project", "description": "" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "create_project", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name." }, "description": { "type": "string", "description": "Optional description." } }, "required": [ "name" ] }, "example": { "name": "my-service" } } } } } }, "/api/projects/{slug}": { "get": { "operationId": "get_project", "summary": "Get project", "description": "Read a project and its services in one environment. Select an environment explicitly when automating a workflow.\n\nAn account key with project access, or a project key for this project. Environment restrictions still apply.", "tags": [ "projects" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." }, { "name": "env", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Environment slug (e.g. dev, staging, production) whose services to return. Omit for the project's default environment — which is why a service you expect to see can be missing: it lives in another environment." } ], "responses": { "200": { "description": "Returns a project with the services for one environment. Omit `env` to use the default environment. A service in another environment will not appear in this result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "description": { "type": "string", "description": "Description of the resource or capability." } }, "additionalProperties": true, "description": "Project metadata." }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "description": "Services in the selected environment, or type previews in a project listing." }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "isDefault": { "type": "boolean" } }, "additionalProperties": true }, "description": "Environments visible to the caller." }, "environment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "isDefault": { "type": "boolean" } }, "additionalProperties": true, "description": "Environment selected for this response." } }, "additionalProperties": true }, "example": { "project": { "id": "prj_example", "name": "My project", "slug": "my-project", "description": "" }, "services": [ { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example" } ], "environments": [ { "id": "env_example", "projectId": "prj_example", "name": "Staging", "slug": "staging", "isDefault": false } ], "environment": { "id": "env_example", "projectId": "prj_example", "name": "Staging", "slug": "staging", "isDefault": false } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_project", "x-read-only": true } }, "/api/services/{id}": { "get": { "operationId": "get_service", "summary": "Get service", "description": "Read a service’s current state, source configuration, plan, and exposed ports.\n\nAn account key with access, or a project/service key with settings:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the service record: its identity, source configuration, plan, and current state. A failed latest deployment may coexist with a serving previous release.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_service", "x-read-only": true }, "delete": { "operationId": "delete_service", "summary": "Delete service", "description": "Delete a service and place eligible resources within the restoration window.\n\nAn account key with access, or a project key with project:write. A service key cannot perform this operation.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "A deleted service is normally retained in the restore window described by the product. Storage-specific consequences still apply: export important bucket data before deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." }, "restorable": { "type": "string", "description": "String flag indicating whether the removed service can be restored." } }, "additionalProperties": true }, "example": { "status": "removed", "restorable": "true" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "delete_service", "x-read-only": false } }, "/api/plans": { "get": { "operationId": "list_plans", "summary": "List plans", "description": "Discover the available service and database plans before creating or resizing a resource.\n\nAny valid API key. Catalog and identity reads do not require a capability category.", "tags": [ "identity" ], "parameters": [], "responses": { "200": { "description": "Returns available plans, pricing rates, display currency, and the applicable exchange rate. Read the current catalog before choosing a plan key; example plan lists are not price quotes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "description": "Display currency associated with the caller." }, "fxRate": { "type": "integer", "description": "Exchange rate for the display currency; zero when not applicable." }, "plans": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Available service and database plans." } }, "additionalProperties": true }, "example": { "currency": "USD", "fxRate": 0, "plans": [] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_plans", "x-read-only": true } }, "/api/services/{id}/deployments": { "get": { "operationId": "list_deployments", "summary": "List deployments", "description": "Read deployment history for a service, newest first, with rollback eligibility and a pagination cursor.\n\nAn account key with access, or a project/service key with deployments:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return older deployments using the nextCursor value from the previous response. REST only; this parameter is not exposed by the MCP tool." } ], "responses": { "200": { "description": "Returns `{ \"deployments\": [...], \"nextCursor\": ... }`, newest first. Pass `nextCursor` as `before` to retrieve the next REST page. Each deployment includes `rollbackable`; only eligible retained images can be rolled back to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "serviceId": { "type": "string" }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "rollbackable": { "type": "boolean", "description": "Whether a retained deployment image is eligible for rollback." }, "createdAt": { "type": "string", "description": "Resource creation timestamp." } }, "additionalProperties": true }, "description": "Deployment records, ordered newest first." }, "nextCursor": { "type": "integer", "description": "Pass as before to read the next page. Zero means no next page." } }, "additionalProperties": true }, "example": { "deployments": [ { "id": "dep_example", "serviceId": "svc_example", "status": "active", "rollbackable": true, "createdAt": "2026-10-07T12:00:00Z" } ], "nextCursor": 0 } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_deployments", "x-read-only": true } }, "/api/services/{id}/logs": { "get": { "operationId": "get_logs", "summary": "Get logs", "description": "Read runtime output from a service. Filter historical logs or read incrementally with a cursor.\n\nAn account key with access, or a project/service key with logs:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "observability" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max lines." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Substring filter." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return lines older than this log ID." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Return newer lines for live tailing. In this mode, search and time filters are not applied." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Inclusive RFC3339 timestamp filter." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exclusive RFC3339 timestamp filter." } ], "responses": { "200": { "description": "Returns `{ \"logs\": [...] }`. Each entry is a runtime log record. Use `after` for an incremental REST tail or combine `before`, `q`, `since`, and `until` to inspect historical output.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of this resource." }, "serviceId": { "type": "string" }, "line": { "type": "string", "description": "One line of log output." }, "stream": { "type": "string", "description": "Log stream that produced this line." }, "ts": { "type": "string", "description": "Runtime log timestamp." } }, "additionalProperties": true }, "description": "Runtime log records." } }, "additionalProperties": true }, "example": { "logs": [ { "id": 42, "serviceId": "svc_example", "line": "Listening on port 3000", "stream": "app", "ts": "2026-10-07T12:00:00Z" } ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_logs", "x-read-only": true } }, "/api/services/{id}/env": { "get": { "operationId": "list_env", "summary": "List environment variables", "description": "List environment variable names and masked values for a service.\n\nAn account key with access, or a project/service key with variables:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "variables" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns variable names and masked values. The empty flag identifies a variable with no value; managed identifies credentials controlled by the platform.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "key": { "type": "string", "description": "Environment variable name." }, "value": { "type": "string", "description": "Masked variable value; plaintext is not returned." }, "managed": { "type": "boolean", "description": "Whether the platform manages this variable." }, "empty": { "type": "boolean", "description": "Whether the stored value is blank." }, "updatedAt": { "type": "string", "description": "Last modification timestamp." } }, "additionalProperties": true } }, "example": [ { "id": "var_example", "key": "NODE_ENV", "value": "••••••", "managed": false, "empty": false, "updatedAt": "2026-10-07T12:00:00Z" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_env", "x-read-only": true }, "post": { "operationId": "set_env", "summary": "Set an environment variable", "description": "Create or update one environment variable. The running service receives it on its next deployment.\n\nAn account key with access, or a project/service key with variables:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "variables" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "A successful response saves the variable. The running service receives the updated value on its next deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "saved" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_env", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Variable name." }, "value": { "type": "string", "description": "Variable value." } }, "required": [ "key", "value" ] }, "example": { "key": "NODE_ENV", "value": "production" } } } } } }, "/api/services/{id}/domains": { "get": { "operationId": "list_domains", "summary": "List domains", "description": "List the custom domains attached to a service and their current verification state.\n\nAn account key with access, or a project/service key with domains:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the domains attached to this service. A pending domain needs DNS verification before it can receive traffic.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "serviceId": { "type": "string" }, "hostname": { "type": "string", "description": "Hostname assigned or attached to the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "port": { "type": "integer", "description": "Port number for the resource." } }, "additionalProperties": true } }, "example": [ { "id": "dom_example", "serviceId": "svc_example", "hostname": "app.example.com", "status": "pending", "port": 0 } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_domains", "x-read-only": true }, "post": { "operationId": "add_domain", "summary": "Add domain", "description": "Attach a custom domain to a service, then configure DNS to complete verification.\n\nAn account key with access, or a project/service key with domains:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "201": { "description": "Returns the new domain record with pending status. Configure the DNS target and finish verification in the dashboard.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "serviceId": { "type": "string" }, "hostname": { "type": "string", "description": "Hostname assigned or attached to the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "port": { "type": "integer", "description": "Port number for the resource." } }, "additionalProperties": true }, "example": { "id": "dom_example", "serviceId": "svc_example", "hostname": "app.example.com", "status": "pending", "port": 0 } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "add_domain", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "description": "Custom hostname, e.g. app.example.com." } }, "required": [ "hostname" ] }, "example": { "hostname": "app.example.com" } } } } } }, "/api/services/{id}/ports": { "get": { "operationId": "list_ports", "summary": "List ports", "description": "Inspect a service’s primary HTTP port, additional exposed ports, and detected port suggestions.\n\nAn account key with access, or a project/service key with domains:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the primary HTTP port, additional exposed ports, and detected ports that could be exposed. Exposing a port takes effect when the service is deployed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryPort": { "type": "integer", "description": "Primary internal HTTP port." }, "ports": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Additional exposed HTTP ports." }, "detected": { "type": "array", "items": { "type": "integer" }, "description": "Detected internal ports that are not yet exposed." } }, "additionalProperties": true }, "example": { "primaryPort": 3000, "ports": [], "detected": [ 8080 ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_ports", "x-read-only": true }, "post": { "operationId": "expose_port", "summary": "Expose port", "description": "Expose an additional HTTP port and create a generated hostname for it.\n\nAn account key with access, or a project/service key with domains:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "201": { "description": "Returns the exposed port and generated hostname. Port mappings apply when the service is redeployed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "port": { "type": "integer", "description": "Port number for the resource." }, "label": { "type": "string", "description": "Human-readable label." }, "hostname": { "type": "string", "description": "Hostname assigned or attached to the service." } }, "additionalProperties": true }, "example": { "port": 8080, "label": "admin", "hostname": "YOUR_PORT_HOSTNAME" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "expose_port", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "port": { "type": "string", "description": "The container port the app listens on, e.g. 9090." }, "label": { "type": "string", "description": "Short name for the port; becomes part of its hostname (lowercase letters, numbers, hyphens), e.g. \"ws\" or \"metrics\"." }, "deploy": { "type": "string", "description": "Redeploy now so the port starts serving immediately (recommended)." } }, "required": [ "port", "label" ] }, "example": { "port": "YOUR_PORT", "label": "YOUR_LABEL" } } } } } }, "/api/hangar/engines": { "get": { "operationId": "list_engines", "summary": "List engines", "description": "Discover supported database engines, versions, and provisioning capabilities.\n\nAny valid API key. Catalog and identity reads do not require a capability category.", "tags": [ "databases" ], "parameters": [], "responses": { "200": { "description": "Returns the database engine catalog. Use an engine key from this list when creating a database; available versions and capabilities differ by engine.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "engine": { "type": "string", "description": "Database engine key." }, "name": { "type": "string", "description": "Human-readable resource name." }, "port": { "type": "integer", "description": "Port number for the resource." }, "hasUser": { "type": "boolean" }, "hasDatabase": { "type": "boolean" }, "storage": { "type": "boolean" } }, "additionalProperties": true } }, "example": [ { "engine": "postgres", "name": "PostgreSQL", "port": 5432, "hasUser": true, "hasDatabase": true, "storage": false } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_engines", "x-read-only": true } }, "/api/hangar/extensions": { "get": { "operationId": "list_db_extensions", "summary": "List database extensions", "description": "Read the curated PostgreSQL extension catalog available during database creation.\n\nAny valid API key. Catalog and identity reads do not require a capability category.", "tags": [ "databases" ], "parameters": [], "responses": { "200": { "description": "Returns the curated PostgreSQL extension catalog as an array. An empty array means no entries were returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable resource name." }, "label": { "type": "string", "description": "Human-readable label." }, "description": { "type": "string", "description": "Description of the resource or capability." } }, "additionalProperties": true } }, "example": [ { "name": "vector", "label": "pgvector", "description": "Vector similarity search for embeddings / AI" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_db_extensions", "x-read-only": true } }, "/api/services/{id}/db/metrics": { "get": { "operationId": "get_db_metrics", "summary": "Get database metrics", "description": "Read engine-specific database metrics, grouped for inspection.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." }, { "name": "light", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pass 1 for the cheap subset (skips the queries that touch the engine), when you only need size and connection counts." } ], "responses": { "200": { "description": "Returns metrics grouped by engine. Inspect the error field when present: this endpoint can return HTTP 200 when the database cannot be reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "engine": { "type": "string", "description": "Database engine key." }, "running": { "type": "boolean", "description": "Whether the database is running." }, "groups": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Engine-specific metric groups." } }, "additionalProperties": true }, "example": { "engine": "postgres", "running": true, "groups": [] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_db_metrics", "x-read-only": true } }, "/api/services/{id}/dns": { "get": { "operationId": "get_dns_target", "summary": "Get DNS target", "description": "Get the DNS target to use when connecting a custom domain to this service.\n\nAn account key with access, or a project/service key with domains:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the CNAME target and IP address for this service. Use the values returned by your own request when configuring DNS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cnameTarget": { "type": "string", "description": "CNAME target to use for this service." }, "ip": { "type": "string", "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." } }, "additionalProperties": true }, "example": { "cnameTarget": "YOUR_SERVICE_HOSTNAME", "ip": "203.0.113.10" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_dns_target", "x-read-only": true } }, "/api/services/{id}/scaling": { "get": { "operationId": "get_scaling", "summary": "Get scaling", "description": "Read the instance floor, autoscaling ceiling, and effective service capacity.\n\nAn account key with access, or a project/service key with settings:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns scaling configuration, the effective instance count, and whether the service type supports autoscaling.", "content": { "application/json": { "schema": { "type": "object", "properties": { "minReplicas": { "type": "integer", "description": "Configured instance floor." }, "maxReplicas": { "type": "integer", "description": "Configured autoscaling ceiling." }, "desiredReplicas": { "type": "integer", "description": "Desired instance count selected by the scaler." }, "instances": { "type": "integer", "description": "Effective number of instances." }, "autoscaleEnabled": { "type": "boolean", "description": "Whether autoscaling is enabled." }, "autoscaleCpuPct": { "type": "integer", "description": "CPU utilization target; zero disables this signal." }, "autoscaleMemPct": { "type": "integer", "description": "Memory utilization target; zero disables this signal." }, "autoscalable": { "type": "boolean", "description": "Whether this service supports autoscaling." } }, "additionalProperties": true }, "example": { "minReplicas": 1, "maxReplicas": 4, "desiredReplicas": 2, "instances": 2, "autoscaleEnabled": true, "autoscaleCpuPct": 70, "autoscaleMemPct": 0, "autoscalable": true } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_scaling", "x-read-only": true }, "patch": { "operationId": "scale_service", "summary": "Scale service", "description": "Set the service’s instance count and, optionally, its autoscaling targets and ceiling.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the saved scaling configuration and whether an immediate redeployment was applied. The response uses minReplicas and maxReplicas for the requested floor and ceiling.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scaling": { "type": "object", "properties": { "minReplicas": { "type": "integer", "description": "Configured instance floor." }, "maxReplicas": { "type": "integer", "description": "Configured autoscaling ceiling." }, "desiredReplicas": { "type": "integer", "description": "Desired instance count selected by the scaler." }, "instances": { "type": "integer", "description": "Effective number of instances." }, "autoscaleEnabled": { "type": "boolean", "description": "Whether autoscaling is enabled." }, "autoscaleCpuPct": { "type": "integer", "description": "CPU utilization target; zero disables this signal." }, "autoscaleMemPct": { "type": "integer", "description": "Memory utilization target; zero disables this signal." }, "autoscalable": { "type": "boolean", "description": "Whether this service supports autoscaling." } }, "additionalProperties": true, "description": "Saved scaling configuration and effective capacity." }, "redeploying": { "type": "boolean", "description": "Whether the operation applied or queued a redeployment." } }, "additionalProperties": true }, "example": { "scaling": { "minReplicas": 1, "maxReplicas": 4, "desiredReplicas": 2, "instances": 2, "autoscaleEnabled": true, "autoscaleCpuPct": 70, "autoscaleMemPct": 0, "autoscalable": true }, "redeploying": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "scale_service", "x-read-only": false, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "instances": { "type": "integer", "description": "Instances to run (minimum 1). With autoscaling on this is the floor." }, "maxInstances": { "type": "integer", "description": "Ceiling autoscaling may grow to. Must be >= instances." }, "autoscaleEnabled": { "type": "boolean", "description": "Turn autoscaling on or off." }, "autoscaleCpuPct": { "type": "integer", "description": "Target CPU utilisation percent per instance (0 = ignore CPU)." }, "autoscaleMemPct": { "type": "integer", "description": "Target memory utilisation percent per instance (0 = ignore memory)." } } }, "example": { "instances": 2, "maxInstances": 4, "autoscaleEnabled": true, "autoscaleCpuPct": 70 } } } } } }, "/api/services/{id}/dependencies": { "get": { "operationId": "get_dependencies", "summary": "Get dependencies", "description": "Inspect dependency issues that can prevent a service from starting correctly.\n\nAn account key with access, or a project/service key with deployments:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns dependency issues for this service. An empty issues array means none were reported.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Reported dependency issues." } }, "additionalProperties": true }, "example": { "issues": [] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_dependencies", "x-read-only": true } }, "/api/projects/{slug}/deleted-services": { "get": { "operationId": "list_deleted_services", "summary": "List deleted services", "description": "Find services in a project that are still eligible for restoration.\n\nAn account key with project access, or a project key for this project. Environment restrictions still apply.", "tags": [ "projects" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." } ], "responses": { "200": { "description": "Returns services in this project that are still within the restore window. Use Restore service to recover an eligible service.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "deletedAt": { "type": "string", "description": "Timestamp when the service was deleted." } }, "additionalProperties": true } }, "example": [ { "id": "svc_example", "name": "my-app", "slug": "my-app", "deletedAt": "2026-10-07T12:00:00Z" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_deleted_services", "x-read-only": true } }, "/api/services": { "post": { "operationId": "create_service", "summary": "Create service", "description": "Create a service from a Git repository or container image. Creation queues a deployment and starts a billed resource.\n\nAn account key with access, or a project key with project:write. A service key cannot perform this operation.", "tags": [ "services" ], "parameters": [], "responses": { "201": { "description": "Creation also queues a deployment and starts a billed resource. Choose a plan before creating the service. Supply either a Git repository or a container image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "idle", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Billing requirement blocks this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "create_service", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Service name." }, "projectSlug": { "type": "string", "description": "Target project slug." }, "environmentSlug": { "type": "string", "description": "Target environment slug (e.g. dev, staging, production). Optional for a normal key — the project's default environment is used. REQUIRED when your API key is restricted to specific environments; call whoami to see whether yours is." }, "repoUrl": { "type": "string", "description": "Git repo URL (for source builds)." }, "image": { "type": "string", "description": "Docker image ref (for image services)." }, "internalPort": { "type": "integer", "description": "Port the app listens on." }, "planKey": { "type": "string", "description": "Plan key from list_plans (e.g. heli-s1). Prefer passing this explicitly so the service runs on the intended plan; if omitted, the cheapest plan matching the service type is applied." } }, "required": [ "name" ] }, "example": { "name": "my-app", "projectSlug": "my-project", "environmentSlug": "staging", "image": "nginx:stable", "internalPort": 80, "planKey": "heli-s1" } } } } } }, "/api/services/{id}/deploy": { "post": { "operationId": "deploy_service", "summary": "Deploy service", "description": "Queue a deployment for an existing service. For a Git service, optionally select a one-off branch, tag, or commit.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "202": { "description": "Returns `202 Accepted` with `deploymentId` and `ref`. The request queues work; it does not mean the deployment succeeded. Follow deployment history and build logs until the deployment completes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." }, "ref": { "type": "string", "description": "Git ref selected for this deployment." } }, "additionalProperties": true }, "example": { "deploymentId": "dep_example", "ref": "main" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "deploy_service", "x-read-only": false, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "description": "Optional branch, tag or commit SHA to build (git services only). Omit to build the tracked branch." } } }, "example": { "ref": "main" } } } } } }, "/api/projects/{projectSlug}/services/upload-b64": { "post": { "operationId": "deploy_upload", "summary": "Create a service from an upload", "description": "Create a new service from a base64-encoded source archive. Use reupload to update an existing upload service.\n\nAn account key with access, or a project key with project:write. A service key cannot perform this operation.", "tags": [ "deployments" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Target project slug." }, { "name": "env", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target environment slug (e.g. dev, staging, production). This route takes the environment as a query argument, not in the body. Optional for a normal key — the project's default environment is used. REQUIRED when your API key is restricted to specific environments; call whoami to see whether yours is." } ], "responses": { "201": { "description": "This creates a new service each time. To ship a new version to an existing upload service, use Reupload service instead. Exclude dependencies and repository metadata from the archive.", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." } }, "additionalProperties": true }, "example": { "service": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "upload", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example" }, "deploymentId": "dep_example" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "deploy_upload", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Service name." }, "runtimeMode": { "type": "string", "description": "web | worker | static | cron (default web)." }, "archiveBase64": { "type": "string", "description": "The build context as a base64-encoded .tar.gz (or .zip) of your project folder." }, "rootDir": { "type": "string", "description": "Subdir the app lives in (optional)." }, "installCommand": { "type": "string", "description": "Install override (optional)." }, "buildCommand": { "type": "string", "description": "Build override (optional)." }, "startCommand": { "type": "string", "description": "Start command / for static, the output dir (optional)." }, "internalPort": { "type": "integer", "description": "Port the app listens on (optional)." }, "planKey": { "type": "string", "description": "Plan key from list_plans (e.g. heli-static). Prefer passing this explicitly so the service runs on the intended plan; if omitted, the cheapest plan matching the service type is applied." } }, "required": [ "name", "archiveBase64" ] }, "example": { "name": "my-service", "archiveBase64": "BASE64_ENCODED_SOURCE_ARCHIVE" } } } } } }, "/api/services/{id}/upload-b64": { "post": { "operationId": "reupload_service", "summary": "Update uploaded source", "description": "Deploy a new source archive to an existing upload service while keeping its identity and configuration.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id (an upload-source service)." } ], "responses": { "202": { "description": "Queues a new deployment for an existing upload service. Follow the returned deploymentId to inspect the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." } }, "additionalProperties": true }, "example": { "deploymentId": "dep_example" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "reupload_service", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archiveBase64": { "type": "string", "description": "The new build context as a base64-encoded .tar.gz (or .zip) of your project folder. Exclude node_modules/.git to keep it small." } }, "required": [ "archiveBase64" ] }, "example": { "archiveBase64": "BASE64_ENCODED_SOURCE_ARCHIVE" } } } } } }, "/api/services/{id}/build": { "patch": { "operationId": "update_build_settings", "summary": "Update build settings", "description": "Update the build directory, builder, and build or runtime commands for a service.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the updated service. Saved build and runtime settings apply on the next deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." }, "rootDir": { "type": "string" }, "buildCommand": { "type": "string" }, "startCommand": { "type": "string" } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example", "rootDir": "apps/api", "buildCommand": "npm run build", "startCommand": "npm start" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "update_build_settings", "x-read-only": false, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rootDir": { "type": "string", "description": "Subdir the app lives in, e.g. apps/api. Empty for the repo root." }, "installCommand": { "type": "string", "description": "Install override, e.g. npm ci." }, "buildCommand": { "type": "string", "description": "Build override, e.g. npm run build." }, "startCommand": { "type": "string", "description": "Start command; for a static site, the output directory." }, "dockerfilePath": { "type": "string", "description": "Path to a Dockerfile relative to the root dir." }, "releaseCommand": { "type": "string", "description": "Command run once before each release (migrations)." }, "builder": { "type": "string", "description": "\"\" auto | railpack | dockerfile | next." } } }, "example": { "rootDir": "apps/api", "buildCommand": "npm run build", "startCommand": "npm start" } } } } } }, "/api/services/{id}/security": { "patch": { "operationId": "set_readonly_filesystem", "summary": "Set read-only filesystem", "description": "Configure a read-only root filesystem for the service’s next deployment.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the saved filesystem setting and when it takes effect. Redeploy the service to apply it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "readonlyRootfs": { "type": "boolean", "description": "Whether the root filesystem is read-only." }, "appliesAt": { "type": "string", "description": "When the saved setting applies." } }, "additionalProperties": true }, "example": { "readonlyRootfs": true, "appliesAt": "next deploy" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_readonly_filesystem", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "readonlyRootfs": { "type": "boolean", "description": "true to mount the root filesystem read-only, false to restore a writable one." } }, "required": [ "readonlyRootfs" ] }, "example": { "readonlyRootfs": true } } } } } }, "/api/services/{id}/metrics": { "get": { "operationId": "get_metrics", "summary": "Get metrics", "description": "Read service resource usage over a supported time window.\n\nAn account key with access, or a project/service key with metrics:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "observability" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window to report over: 1h, 6h, 24h or 7d. Defaults to 1h, so ask for a wider range when investigating a pattern rather than a spike." } ], "responses": { "200": { "description": "The `range` query accepts `1h`, `6h`, `24h`, or `7d`. Resource series aggregate the service’s replicas and are downsampled over time. They are not per-instance averages. Network rates are bytes per second; summary.instances reports the latest sampled replica count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string", "description": "Resolved metrics window." }, "series": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Runtime log timestamp." }, "cpu": { "type": "number" }, "memUsed": { "type": "integer" }, "memMax": { "type": "integer" }, "memLimit": { "type": "integer" }, "netRxRate": { "type": "integer" }, "netTxRate": { "type": "integer" } }, "additionalProperties": true }, "description": "Downsampled metric series. CPU and memory aggregate the service replicas; network rates are bytes per second." }, "summary": { "type": "object", "properties": { "samples": { "type": "integer", "description": "Number of metric samples in the selected time window." }, "instances": { "type": "integer", "description": "Effective number of instances." }, "current": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Latest sampled metrics, or null when no samples exist." } }, "additionalProperties": true, "description": "Current metrics, percentiles, and the latest sampled instance count." } }, "additionalProperties": true }, "example": { "range": "1h", "series": [], "summary": { "samples": 0, "instances": 1, "current": null } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_metrics", "x-read-only": true } }, "/api/projects/{projectSlug}/environments": { "get": { "operationId": "list_environments", "summary": "List environments", "description": "List environments visible to the caller within a project.\n\nAn account key with project access, or a project key for this project. Environment restrictions still apply.", "tags": [ "projects" ], "parameters": [ { "name": "projectSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." } ], "responses": { "200": { "description": "Returns environments visible to the caller. Use a returned slug to select an environment in a project read or creation request.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "isDefault": { "type": "boolean" } }, "additionalProperties": true } }, "example": [ { "id": "env_example", "projectId": "prj_example", "name": "Staging", "slug": "staging", "isDefault": false } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_environments", "x-read-only": true } }, "/api/services/{id}/storage": { "patch": { "operationId": "set_storage", "summary": "Set storage", "description": "Change the provisioned storage of a managed database or bucket without changing its compute plan.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id (a managed database or bucket)." } ], "responses": { "200": { "description": "Provisioned storage affects billing. Filesystem growth cannot be undone by reducing the billed size; inspect the storage guide before resizing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storageGb": { "type": "integer", "description": "New provisioned storage size in GB." }, "previousGb": { "type": "integer", "description": "Provisioned size before the change." }, "applyError": { "type": "string", "description": "Empty on successful application; otherwise describes why the runtime could not apply the change." } }, "additionalProperties": true }, "example": { "storageGb": 8, "previousGb": 4, "applyError": "" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_storage", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storageGb": { "type": "integer", "description": "New provisioned size in GB." } }, "required": [ "storageGb" ] }, "example": { "storageGb": 4 } } } } } }, "/api/services/{id}/rollback/{deploymentId}": { "post": { "operationId": "rollback_service", "summary": "Roll back a service", "description": "Queue a deployment using a retained image from an earlier release.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment to roll back to (must be within the rollback window)." } ], "responses": { "202": { "description": "Queues a deployment using the retained image from the selected release. Follow the new deploymentId; application rollback does not restore database data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." } }, "additionalProperties": true }, "example": { "deploymentId": "dep_example" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "rollback_service", "x-read-only": false } }, "/api/services/{id}/stop": { "post": { "operationId": "stop_service", "summary": "Stop service", "description": "Stop a running service. Deploy it again when you are ready to resume.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns status stopped after the stop operation. Starting the service again requires a deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "stopped" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "stop_service", "x-read-only": false } }, "/api/dedicated-ips": { "get": { "operationId": "list_dedicated_ips", "summary": "List dedicated IPs", "description": "List dedicated outbound addresses held by your account and their attachments.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [], "responses": { "200": { "description": "Returns dedicated IPs held by your account and whether you can manage them. Acquisition and payment are handled in the dashboard.", "content": { "application/json": { "schema": { "type": "object", "properties": { "held": { "type": "integer", "description": "Number of held addresses." }, "ips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "address": { "type": "string" }, "label": { "type": "string", "description": "Human-readable label." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "description": "Dedicated IPs held by this account." }, "canManage": { "type": "boolean", "description": "Whether the caller can manage these addresses." } }, "additionalProperties": true }, "example": { "held": 1, "ips": [ { "id": "ip_example", "address": "203.0.113.10", "label": "Production", "attachments": [] } ], "canManage": true } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_dedicated_ips", "x-read-only": true } }, "/api/projects/{slug}/dedicated-ip": { "get": { "operationId": "get_project_dedicated_ip", "summary": "Get project dedicated IP", "description": "Read the outbound IP attachment inherited by eligible services in this project.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." } ], "responses": { "200": { "description": "Returns the project attachment as ip, or null if none is attached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "address": { "type": "string" }, "label": { "type": "string", "description": "Human-readable label." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." } }, "additionalProperties": true }, "example": { "ip": { "id": "ip_example", "address": "203.0.113.10", "label": "Production", "attachments": [] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_project_dedicated_ip", "x-read-only": true }, "put": { "operationId": "attach_project_dedicated_ip", "summary": "Attach project dedicated IP", "description": "Attach an existing account-owned outbound IP to a project.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." } ], "responses": { "200": { "description": "Returns the attachment and effective timing. Check excluded for project services that cannot use this IP.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "address": { "type": "string" }, "label": { "type": "string", "description": "Human-readable label." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." }, "effective": { "type": "string", "description": "When the attachment starts applying." }, "excluded": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Project services that cannot use the attachment." } }, "additionalProperties": true }, "example": { "ip": { "id": "ip_example", "address": "203.0.113.10", "label": "Production", "attachments": [] }, "effective": "within about a minute — no redeploy needed", "excluded": [] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "attach_project_dedicated_ip", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ipId": { "type": "string", "description": "Dedicated IP id from list_dedicated_ips." } }, "required": [ "ipId" ] }, "example": { "ipId": "YOUR_IP_ID" } } } } }, "delete": { "operationId": "detach_project_dedicated_ip", "summary": "Detach project dedicated IP", "description": "Detach an outbound IP from a project without releasing the purchased address.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project slug." } ], "responses": { "200": { "description": "Returns ip: null after detaching. This does not release the purchased address or stop its billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." } }, "additionalProperties": true }, "example": { "ip": null } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "detach_project_dedicated_ip", "x-read-only": false } }, "/api/services/{id}/dedicated-ip": { "get": { "operationId": "get_service_dedicated_ip", "summary": "Get service dedicated IP", "description": "Read a service’s explicit outbound IP and its project-level fallback.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the explicit service attachment as ip and the project attachment as projectIp. Either value can be null.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." }, "projectIp": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "address": { "type": "string" }, "label": { "type": "string", "description": "Human-readable label." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true, "description": "Project-level IP attachment inherited by the service." } }, "additionalProperties": true }, "example": { "ip": null, "projectIp": { "id": "ip_example", "address": "203.0.113.10", "label": "Production", "attachments": [] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_service_dedicated_ip", "x-read-only": true }, "put": { "operationId": "attach_service_dedicated_ip", "summary": "Attach service dedicated IP", "description": "Attach an existing account-owned outbound IP to a service. A deployment is required to apply it.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the service attachment. Deploy the service again to apply the new outbound address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "address": { "type": "string" }, "label": { "type": "string", "description": "Human-readable label." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." }, "redeployRequired": { "type": "boolean", "description": "Whether another service deployment is required." }, "effective": { "type": "string", "description": "When the attachment starts applying." } }, "additionalProperties": true }, "example": { "ip": { "id": "ip_example", "address": "203.0.113.10", "label": "Production", "attachments": [] }, "redeployRequired": true, "effective": "on the service's next deploy" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "attach_service_dedicated_ip", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ipId": { "type": "string", "description": "Dedicated IP id from list_dedicated_ips." } }, "required": [ "ipId" ] }, "example": { "ipId": "YOUR_IP_ID" } } } } }, "delete": { "operationId": "detach_service_dedicated_ip", "summary": "Detach service dedicated IP", "description": "Remove a service’s outbound IP override without releasing the address.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns ip: null after removing the service override. The service can fall back to its project attachment. Detaching does not release the address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Attached dedicated IP, or null when detached. In DNS responses, the target IP address." } }, "additionalProperties": true }, "example": { "ip": null } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "detach_service_dedicated_ip", "x-read-only": false } }, "/api/databases": { "post": { "operationId": "create_database", "summary": "Create database", "description": "Provision a managed database in a project and environment using a supported engine and plan.\n\nAn account key with access, or a project key with project:write. A service key cannot perform this operation.", "tags": [ "databases" ], "parameters": [], "responses": { "201": { "description": "Creates a billed database service. Engine keys and plan keys should come from the engine and plan catalog endpoints. Set the target project and environment explicitly for automation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "postgres", "slug": "my-app", "sourceType": "database", "status": "idle", "planKey": "heli-db-s1", "projectId": "prj_example", "environmentId": "env_example" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "create_database", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Database name." }, "engine": { "type": "string", "description": "Engine key (e.g. postgres, redis, mysql, mongo)." }, "projectSlug": { "type": "string", "description": "Target project slug." }, "environmentSlug": { "type": "string", "description": "Target environment slug (e.g. dev, staging, production). Optional for a normal key — the project's default environment is used. REQUIRED when your API key is restricted to specific environments; call whoami to see whether yours is." }, "planKey": { "type": "string", "description": "Plan key from list_plans (e.g. heli-db-s1). Prefer passing this explicitly so the database runs on the intended plan; if omitted, the cheapest plan matching the engine is applied." } }, "required": [ "name", "engine" ] }, "example": { "name": "postgres", "engine": "postgres", "projectSlug": "my-project", "environmentSlug": "staging", "planKey": "heli-db-s1" } } } } } }, "/api/deployments/{deploymentId}/logs": { "get": { "operationId": "get_deployment_logs", "summary": "Get deployment logs", "description": "Read build and deployment output, optionally after a previously seen log identifier.\n\nAn account key with access, or a project/service key with logs:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "observability" ], "parameters": [ { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deployment id." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Return only lines after this sequence number, so a build can be followed incrementally instead of re-fetching the whole log each time." } ], "responses": { "200": { "description": "Returns a JSON array of deployment log records. Pass the last sequence number as `after` to read only newer lines.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of this resource." }, "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." }, "line": { "type": "string", "description": "One line of log output." }, "stream": { "type": "string", "description": "Log stream that produced this line." }, "createdAt": { "type": "string", "description": "Resource creation timestamp." } }, "additionalProperties": true } }, "example": [ { "id": 42, "deploymentId": "dep_example", "line": "Build completed", "stream": "system", "createdAt": "2026-10-07T12:00:00Z" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_deployment_logs", "x-read-only": true } }, "/api/services/{id}/connection": { "get": { "operationId": "get_db_connection", "summary": "Get database connection", "description": "Read connection details and credentials for a database you can access. Treat this response as a secret.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." } ], "responses": { "200": { "description": "This response can contain database URLs and credentials. Do not log it or commit it to source control. Database connection access is not granted by a service-scoped key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "engine": { "type": "string", "description": "Database engine key." }, "host": { "type": "string", "description": "Private database hostname." }, "port": { "type": "integer", "description": "Port number for the resource." }, "username": { "type": "string", "description": "Database login name." }, "password": { "type": "string", "description": "Database password. Treat this response as a secret." }, "database": { "type": "string", "description": "Database name." }, "externalAccess": { "type": "boolean", "description": "Whether external database access is enabled." }, "tls": { "type": "boolean", "description": "Whether external database TLS is enabled." }, "allowIps": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Allowed external source CIDRs. An empty list permits any source." } }, "additionalProperties": true }, "example": { "engine": "postgres", "host": "YOUR_PRIVATE_DATABASE_HOST", "port": 5432, "username": "app", "password": "REDACTED", "database": "app", "externalAccess": false, "tls": false, "allowIps": [] } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_db_connection", "x-read-only": true } }, "/api/services/{id}/backups": { "get": { "operationId": "list_backups", "summary": "List backups", "description": "List the backup records for a managed database.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." } ], "responses": { "200": { "description": "Returns this database’s backup records. An empty array means no backups were returned. Check completion before attempting a restore.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "serviceId": { "type": "string" }, "engine": { "type": "string", "description": "Database engine key." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "sizeBytes": { "type": "integer", "description": "Backup size in bytes." }, "createdAt": { "type": "string", "description": "Resource creation timestamp." }, "finishedAt": { "type": "string", "description": "Completion timestamp; can be empty while the operation is running." }, "tier": { "type": "string", "description": "Rolling-retention tier assigned to a completed backup." } }, "additionalProperties": true } }, "example": [ { "id": "bak_example", "serviceId": "svc_example", "engine": "postgres", "status": "complete", "sizeBytes": 1048576, "createdAt": "2026-10-07T12:00:00Z", "finishedAt": "2026-10-07T12:00:00Z", "tier": "Latest" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_backups", "x-read-only": true }, "post": { "operationId": "create_backup", "summary": "Create backup", "description": "Start an on-demand backup of a managed database.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." } ], "responses": { "202": { "description": "Returns the backup identifier with running status. Backup creation is asynchronous; list backups to check completion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "backupId": { "type": "string", "description": "Identifier of the asynchronous backup." }, "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "backupId": "bak_example", "status": "running" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "create_backup", "x-read-only": false } }, "/api/services/{id}/references": { "get": { "operationId": "list_references", "summary": "List references", "description": "List environment-variable references connecting this service to provider services.\n\nAn account key with access, or a project/service key with variables:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "variables" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns each injected variable and its provider service. providerEnvironment is empty when the provider is in the same environment.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "varKey": { "type": "string" }, "sourceKind": { "type": "string" }, "providerId": { "type": "string" }, "providerName": { "type": "string" }, "providerEnvironment": { "type": "string", "description": "Provider environment label; empty for the same environment." } }, "additionalProperties": true } }, "example": [ { "id": "ref_example", "varKey": "DATABASE_URL", "sourceKind": "url", "providerId": "svc_database", "providerName": "postgres", "providerEnvironment": "" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_references", "x-read-only": true }, "post": { "operationId": "add_reference", "summary": "Add reference", "description": "Inject a value from a provider service into a consumer’s environment variable.\n\nAn account key with access, or a project/service key with variables:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "variables" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CONSUMING service id (the app that needs the value). Databases can't consume references." } ], "responses": { "201": { "description": "Returns the new reference and an optional note. Redeploy the consumer to receive the injected environment value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "consumerId": { "type": "string" }, "providerId": { "type": "string" }, "sourceKind": { "type": "string" }, "varKey": { "type": "string" } }, "additionalProperties": true, "description": "New reference linking a consumer to a provider." }, "note": { "type": "string", "description": "Additional information about the result; can be empty." } }, "additionalProperties": true }, "example": { "reference": { "id": "ref_example", "consumerId": "svc_example", "providerId": "svc_database", "sourceKind": "url", "varKey": "DATABASE_URL" }, "note": "" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "add_reference", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "type": "string", "description": "The service being referenced (e.g. the database)." }, "sourceKind": { "type": "string", "description": "Which value to pull: \"url\" (default; full connection URL), \"host\", \"host-port\", \"public-url\" (web-facing services only), or \"var:NAME\" to copy a specific env var from the provider." }, "varKey": { "type": "string", "description": "Env var name to inject into the consumer. Optional — defaults to a natural name for the provider." } }, "required": [ "providerId" ] }, "example": { "providerId": "YOUR_DATABASE_SERVICE_ID", "sourceKind": "url", "varKey": "DATABASE_URL" } } } } } }, "/api/env-groups": { "get": { "operationId": "list_env_groups", "summary": "List environment groups", "description": "Discover shared environment groups owned by your account.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "variables" ], "parameters": [], "responses": { "200": { "description": "Returns environment groups owned by the caller’s account. This discovery response does not include decrypted variable values.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." } }, "additionalProperties": true } }, "example": [ { "id": "grp_example", "name": "Shared configuration" } ] } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "list_env_groups", "x-read-only": true } }, "/api/services/{id}/cron": { "get": { "operationId": "get_cron", "summary": "Get cron configuration", "description": "Read a cron service’s schedule, command, and next expected run.\n\nAn account key with access, or a project/service key with settings:read. The resource must be within the key’s project, service, and environment scope.", "tags": [ "cron" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cron service id." } ], "responses": { "200": { "description": "Returns the saved schedule, command, next run time, and schedule validity. nextRun can be null when no next run can be calculated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "string", "description": "Cron expression." }, "command": { "type": "string", "description": "Command executed by the scheduled service." }, "nextRun": { "type": "string", "description": "Next scheduled run timestamp, or null." }, "scheduleValid": { "type": "boolean", "description": "Whether the saved schedule can be parsed." } }, "additionalProperties": true }, "example": { "schedule": "0 9 * * *", "command": "npm run daily-job", "nextRun": "2026-10-08T09:00:00Z", "scheduleValid": true } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "get_cron", "x-read-only": true } }, "/api/services/{id}/env/import": { "post": { "operationId": "import_env", "summary": "Import environment variables", "description": "Import several environment variables into a service in one request.\n\nAn account key with access, or a project/service key with variables:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Variables apply on the next deployment. Values may contain secrets; do not print them in CI logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer", "description": "Number of variables imported." }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Environment variable name." }, "reason": { "type": "string", "description": "Why this variable was skipped." } }, "additionalProperties": true }, "description": "Variables skipped during import, with each key and reason." } }, "additionalProperties": true }, "example": { "imported": 1, "skipped": [] } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "import_env", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vars": { "type": "array", "description": "Array of {key,value} objects.", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } } }, "required": [ "vars" ] }, "example": { "vars": [ { "key": "NODE_ENV", "value": "production" } ] } } } } } }, "/api/services/{id}/env/{key}": { "delete": { "operationId": "delete_env", "summary": "Delete an environment variable", "description": "Delete an environment variable from a service’s saved configuration.\n\nAn account key with access, or a project/service key with variables:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "variables" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Variable name." } ], "responses": { "200": { "description": "Removes the stored variable. Redeploy the service to update the running environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "deleted" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "delete_env", "x-read-only": false } }, "/api/services/{id}/run": { "post": { "operationId": "run_cron", "summary": "Run a cron job", "description": "Queue an immediate run of a cron service without changing its schedule.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "cron" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cron service id." } ], "responses": { "202": { "description": "Returns `202 Accepted` with a `deploymentId`. Inspect that deployment’s logs for the job result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." } }, "additionalProperties": true }, "example": { "deploymentId": "dep_example" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "run_cron", "x-read-only": false } }, "/api/services/{id}/schedule": { "patch": { "operationId": "update_cron", "summary": "Update cron schedule", "description": "Update a cron service’s schedule or command.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "cron" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cron service id." } ], "responses": { "200": { "description": "Returns the updated service. The scheduler is updated immediately; a deployment is not needed just to change the schedule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." }, "schedule": { "type": "string", "description": "Cron expression." }, "startCommand": { "type": "string" } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example", "schedule": "0 9 * * *", "startCommand": "npm run daily-job" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "update_cron", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schedule": { "type": "string", "description": "Crontab expression." }, "command": { "type": "string", "description": "Command to run." } }, "required": [ "schedule" ] }, "example": { "schedule": "0 9 * * *" } } } } } }, "/api/deployments/{deploymentId}/abort": { "post": { "operationId": "abort_deploy", "summary": "Abort deploy", "description": "Request cancellation of a deployment that is still in progress.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "In-flight deployment id." } ], "responses": { "200": { "description": "Returns status aborting after requesting cancellation. Follow the deployment until it reaches its final state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "aborting" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "abort_deploy", "x-read-only": false } }, "/api/services/{id}/restore": { "post": { "operationId": "restore_service", "summary": "Restore service", "description": "Restore an eligible deleted service and redeploy it with its retained configuration.\n\nAn account key with access, or a project key with project:write. A service key cannot perform this operation.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Restores an eligible deleted service and redeploys it. The restored identifier is the same; inspect the service to follow recovery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." }, "id": { "type": "string", "description": "Unique identifier of this resource." }, "slug": { "type": "string", "description": "URL-safe resource identifier." } }, "additionalProperties": true }, "example": { "status": "restored", "id": "svc_example", "slug": "my-app" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "restore_service", "x-read-only": false } }, "/api/services/{id}/backups/{backupId}/restore": { "post": { "operationId": "restore_backup", "summary": "Restore backup", "description": "Restore a selected backup into its database. This overwrites the current database contents.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." }, { "name": "backupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Backup id." } ], "responses": { "200": { "description": "Restoration overwrites current database data. Verify the target service and backup, and retain a current backup before executing it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "restored" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is missing or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "restore_backup", "x-read-only": false } }, "/api/services/{id}/db/console": { "post": { "operationId": "db_query", "summary": "Execute a SQL query", "description": "Run a SQL query against a managed database. Queries can modify data; inspect the response for execution errors.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." } ], "responses": { "200": { "description": "Returns console output as text. Inspect error even on HTTP 200: a SQL execution failure is returned in the response body. Query execution can modify data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string", "description": "Database console output as text." } }, "additionalProperties": true }, "example": { "output": "1\n" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "db_query", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "SQL to execute." } }, "required": [ "query" ] }, "example": { "query": "SELECT 1;" } } } } } }, "/api/services/{id}/ports/{port}": { "delete": { "operationId": "remove_port", "summary": "Remove port", "description": "Remove an additional exposed HTTP port and its generated route.\n\nAn account key with access, or a project/service key with domains:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "port", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The exposed container port to stop exposing." } ], "responses": { "200": { "description": "Removes the additional port and its generated route. Clients using that route will lose access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "removed" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "remove_port", "x-read-only": false } }, "/api/services/{id}/domains/{domainId}": { "delete": { "operationId": "remove_domain", "summary": "Remove domain", "description": "Remove a custom domain from this service.\n\nAn account key with access, or a project/service key with domains:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id." } ], "responses": { "200": { "description": "Removes this custom domain from the service. DNS records at your DNS provider are not modified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "removed" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "remove_domain", "x-read-only": false } }, "/api/services/{id}/autodeploy": { "patch": { "operationId": "set_autodeploy", "summary": "Set automatic deployments", "description": "Enable or disable automatic deployments when the tracked Git source changes.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the service with the saved automatic-deployment setting. This controls future matching Git pushes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." }, "autoDeploy": { "type": "boolean" } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example", "autoDeploy": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_autodeploy", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true to enable auto-deploy." } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/api/services/{id}/search-indexing": { "patch": { "operationId": "set_search_indexing", "summary": "Set search indexing", "description": "Control search-indexing headers on a service’s generated hostname.\n\nAn account key with access, or a project/service key with domains:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "networking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the updated service. The setting controls indexing headers on the service’s generated hostname.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." }, "searchIndexing": { "type": "boolean", "description": "Whether indexing is enabled on the generated hostname." } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example", "searchIndexing": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_search_indexing", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true to allow indexing of the generated hostname." } }, "required": [ "enabled" ] }, "example": { "enabled": true } } } } } }, "/api/services/{id}/image": { "patch": { "operationId": "set_service_image", "summary": "Set service image", "description": "Change a service’s container image and optionally deploy it immediately.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the updated service when saving only (200), or a deploymentId and image when a deployment is queued (202).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this resource." }, "name": { "type": "string", "description": "Human-readable resource name." }, "slug": { "type": "string", "description": "URL-safe resource identifier." }, "sourceType": { "type": "string", "description": "Source used to build or run the service." }, "status": { "type": "string", "description": "Current state of the resource or operation." }, "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "projectId": { "type": "string", "description": "Project that owns the resource." }, "environmentId": { "type": "string", "description": "Environment that contains the service." } }, "additionalProperties": true }, "example": { "id": "svc_example", "name": "my-app", "slug": "my-app", "sourceType": "image", "status": "running", "planKey": "heli-s1", "projectId": "prj_example", "environmentId": "env_example" } } } }, "202": { "description": "Returns the updated service when saving only (200), or a deploymentId and image when a deployment is queued (202).", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Identifier to use when reading deployment history or logs." }, "image": { "type": "string" } }, "additionalProperties": true }, "example": { "deploymentId": "dep_example", "image": "nginx:stable" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_service_image", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "New image reference, e.g. ghcr.io/acme/api:v1.2.3." }, "deploy": { "type": "boolean", "description": "Deploy immediately after repointing." } }, "required": [ "image" ] }, "example": { "image": "nginx:stable" } } } } } }, "/api/services/{id}/deploy-trigger": { "post": { "operationId": "create_deploy_trigger", "summary": "Create deploy trigger", "description": "Create or rotate a secret URL that can trigger deployments. The token is shown only once.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "201": { "description": "The newly issued trigger URL is returned once. It authorizes deployment without an API key; store it as a secret. Rotating invalidates the previous URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a deploy trigger is enabled." }, "token": { "type": "string", "description": "Secret deploy-trigger token, returned once." }, "url": { "type": "string", "description": "Secret deploy-trigger URL, returned once." } }, "additionalProperties": true }, "example": { "configured": true, "token": "REDACTED", "url": "REDACTED_DEPLOY_TRIGGER_URL" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "create_deploy_trigger", "x-read-only": false }, "delete": { "operationId": "delete_deploy_trigger", "summary": "Delete deploy trigger", "description": "Revoke the service’s current deploy-trigger URL.\n\nAn account key with access, or a project/service key with deployments:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "deployments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns configured: false. The previous trigger URL no longer authorizes deployments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a deploy trigger is enabled." } }, "additionalProperties": true }, "example": { "configured": false } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "delete_deploy_trigger", "x-read-only": false } }, "/api/services/{id}/db/password": { "post": { "operationId": "rotate_db_credentials", "summary": "Rotate database credentials", "description": "Change a managed database’s password and invalidate the previous credential.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database or bucket service id." } ], "responses": { "200": { "description": "Returns confirmation after changing the database password. Update clients that hold the old credential; do not publish the replacement password.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current state of the resource or operation." } }, "additionalProperties": true }, "example": { "status": "password changed" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "rotate_db_credentials", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "New password (databases) or secret key (buckets, min 8 characters)." }, "accessKey": { "type": "string", "description": "Buckets only: a new S3 access key. Omit to keep the current one." } }, "required": [ "password" ] }, "example": { "password": "REPLACE_WITH_A_STRONG_SECRET" } } } } } }, "/api/services/{id}/db/access": { "post": { "operationId": "set_db_external_access", "summary": "Set database external access", "description": "Enable or disable external connections for a supported database.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database or bucket service id." } ], "responses": { "200": { "description": "Returns the saved external access flag. The database is redeployed to apply it; support depends on the database and runtime.", "content": { "application/json": { "schema": { "type": "object", "properties": { "externalAccess": { "type": "boolean", "description": "Whether external database access is enabled." }, "redeploying": { "type": "boolean", "description": "Whether the operation applied or queued a redeployment." } }, "additionalProperties": true }, "example": { "externalAccess": false, "redeploying": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_db_external_access", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external": { "type": "boolean", "description": "true to publish the port to the internet, false to keep it private to the project." } }, "required": [ "external" ] }, "example": { "external": false } } } } } }, "/api/services/{id}/db/allowlist": { "post": { "operationId": "set_db_allowlist", "summary": "Set database allowlist", "description": "Set the source CIDRs allowed to connect to an externally accessible database.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database or bucket service id." } ], "responses": { "200": { "description": "Returns the saved CIDRs and whether the firewall is enforcing them. An empty list allows any source; check enforced before relying on the restriction.", "content": { "application/json": { "schema": { "type": "object", "properties": { "allowIps": { "type": "array", "items": { "type": "string" }, "description": "Allowed external source CIDRs. An empty list permits any source." }, "enforced": { "type": "boolean", "description": "Whether the source-IP firewall is currently enforcing the saved rules." } }, "additionalProperties": true }, "example": { "allowIps": [ "203.0.113.4/32" ], "enforced": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_db_allowlist", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowIps": { "type": "array", "description": "IPv4 addresses or CIDRs allowed to connect. Empty list = allow all.", "items": { "type": "string" } } }, "required": [ "allowIps" ] }, "example": { "allowIps": [ "203.0.113.4/32" ] } } } } } }, "/api/services/{id}/db/tls": { "post": { "operationId": "set_db_tls", "summary": "Set database TLS", "description": "Enable or disable external TLS for a supported database.\n\nAn account key with access to the resource. Project and service keys do not authorize this operation.", "tags": [ "databases" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Database service id." } ], "responses": { "200": { "description": "Returns the saved TLS flag and redeployment state. Enable only when the database supports external TLS.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tls": { "type": "boolean", "description": "Whether external database TLS is enabled." }, "redeploying": { "type": "boolean", "description": "Whether the operation applied or queued a redeployment." } }, "additionalProperties": true }, "example": { "tls": true, "redeploying": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_db_tls", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tls": { "type": "boolean", "description": "true to serve TLS on the database port." } }, "required": [ "tls" ] }, "example": { "tls": true } } } } } }, "/api/services/{id}/plan": { "patch": { "operationId": "set_plan", "summary": "Set plan", "description": "Move a service to another available compute plan.\n\nAn account key with access, or a project/service key with settings:write. The resource must be within the key’s project, service, and environment scope.", "tags": [ "services" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service id." } ], "responses": { "200": { "description": "Returns the selected plan key and whether the change triggers a redeployment. A plan change can affect billing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "planKey": { "type": "string", "description": "Plan identifier from the plan catalog." }, "redeploying": { "type": "boolean", "description": "Whether the operation applied or queued a redeployment." } }, "additionalProperties": true }, "example": { "planKey": "heli-s2", "redeploying": true } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key scope or caller permissions do not allow this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Resource state conflicts with the requested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The operation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Authentication, authorization, validation, or runtime error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mcp-tool": "set_plan", "x-read-only": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planKey": { "type": "string", "description": "Plan key, e.g. heli-s2." } }, "required": [ "planKey" ] }, "example": { "planKey": "heli-s1" } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Helicarrier API key. Scope and the creator’s permissions both apply." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }