{ "openapi": "3.1.0", "info": { "title": "InstaCloud API — Project level", "version": "0.1.0", "description": "Endpoints under `/projects/{projectId}`: branches, services, deploys, secrets, databases, storage, cron, observability, governance. Callable with any token whose binding covers the project.\n\nGenerated from the platform's own OpenAPI document (https://api.instacloud.com/openapi.json); see the [API overview](/reference/api/overview) for authentication and token scopes." }, "servers": [ { "url": "https://api.instacloud.com", "description": "InstaCloud" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Projects", "description": "Projects inside an organization." }, { "name": "Branches", "description": "Branch environments of a project: isolated database, storage and compute per branch." }, { "name": "Services", "description": "Services on a branch: compute, postgres, storage and managed databases." }, { "name": "Deploy", "description": "Deploy an image or a source to a compute service." }, { "name": "Compute", "description": "Build output of a compute service." }, { "name": "Secrets", "description": "User secrets, service credentials and how they bind into compute env." }, { "name": "Database", "description": "Postgres databases, extensions, credentials and ad-hoc SQL." }, { "name": "Storage", "description": "Objects in a storage service." }, { "name": "Backups", "description": "Database backups and restores." }, { "name": "Cron", "description": "Scheduled HTTP calls against a service or an external URL." }, { "name": "Observability", "description": "Logs, metrics, deploy events and database insight." }, { "name": "Governance", "description": "Per-project agent policy and the approval queue." }, { "name": "Audit", "description": "The project's event timeline, including agent-ingested events." }, { "name": "Domains", "description": "Domains bought through InstaCloud, bring-your-own zones and their DNS records." }, { "name": "Billing", "description": "Usage, cycles, invoices and credits." }, { "name": "Templates", "description": "Deploy a template into a project." } ], "paths": { "/projects/{id}/builds/{source}/{buildId}/logs": { "get": { "operationId": "readBuildLogs", "summary": "Read build steps or one page of step output", "tags": [ "Compute" ], "parameters": [ { "schema": { "pattern": "^sha256:[a-f0-9]{64}$", "type": "string" }, "in": "query", "name": "step", "required": false }, { "schema": { "maxLength": 16384, "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "archive" ] } ] }, "in": "path", "name": "source", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "buildId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildLogPage" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Read build steps or one page of step output", "sidebarTitle": "Read build logs" } } } }, "/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Project detail (branches + live resources)", "tags": [ "Projects" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Project detail (branches + live resources)", "sidebarTitle": "Get project" } } }, "patch": { "operationId": "renameProject", "summary": "Rename project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 100, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRename a project (display name only).", "x-mint": { "metadata": { "title": "Rename project", "sidebarTitle": "Rename project" } } }, "delete": { "operationId": "deleteProject", "summary": "Delete project", "tags": [ "Projects" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teardown": { "$ref": "#/components/schemas/TeardownSummary" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a project (destroy resources + rows). Gated — secrets.read/deploy not required, project.delete is.", "x-mint": { "metadata": { "title": "Delete project", "sidebarTitle": "Delete project" } } } }, "/projects/{projectId}/agent-policy": { "get": { "operationId": "getAgentPolicy", "tags": [ "Governance" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "full_access" ] }, { "type": "string", "enum": [ "read_only" ] }, { "type": "string", "enum": [ "branch_specific" ] }, { "type": "string", "enum": [ "customize" ] } ] }, "protectedBranchIds": { "type": "array", "items": { "format": "uuid", "type": "string" } }, "rules": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "branchDeveloperRules": { "deprecated": true, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "updatedBy": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "mode", "protectedBranchIds", "rules", "branchDeveloperRules" ] }, "agentSessionEpoch": { "type": "integer" }, "actions": { "type": "array", "items": { "type": "string" } }, "actionCatalog": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "group": { "type": "string" }, "groupLabel": { "type": "string" }, "label": { "type": "string" }, "hint": { "type": "string" }, "editable": { "description": "false when a rule naming this action is refused as a fixed invariant", "type": "boolean" }, "fixedDecision": { "description": "what a non-editable action resolves to under the restricted modes; null when editable. full_access allows even the denied ones, so this and the current decision disagree for exactly what stops being allowed when full access is left", "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] }, { "type": [ "object", "null" ], "enum": [ null, null ] } ] } }, "required": [ "action", "group", "groupLabel", "label", "hint", "editable", "fixedDecision" ] } }, "defaultRules": { "type": "object", "properties": { "project": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "unprotectedBranch": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "protectedBranch": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } } }, "required": [ "project", "unprotectedBranch", "protectedBranch" ] }, "effectiveRules": { "type": "object", "properties": { "project": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "unprotectedBranch": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "protectedBranch": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } } }, "required": [ "project", "unprotectedBranch", "protectedBranch" ] }, "bootstrapRules": { "type": "object", "properties": { "project.create": { "type": "string", "enum": [ "allow" ] } }, "required": [ "project.create" ] }, "ruleNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "policy", "agentSessionEpoch", "actions", "actionCatalog", "defaultRules", "effectiveRules", "bootstrapRules", "ruleNotes" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "summary": "Get agent policy", "x-mint": { "metadata": { "title": "Get agent policy", "sidebarTitle": "Get agent policy" } } }, "put": { "operationId": "setAgentPolicy", "tags": [ "Governance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "full_access" ] }, { "type": "string", "enum": [ "read_only" ] }, { "type": "string", "enum": [ "branch_specific" ] }, { "type": "string", "enum": [ "customize" ] }, { "deprecated": true, "type": "string", "enum": [ "branch_developer" ] } ] }, "protectedBranchIds": { "type": "array", "items": { "format": "uuid", "type": "string" } }, "rules": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "branchDeveloperRules": { "deprecated": true, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "updatedBy": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "mode", "protectedBranchIds" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "full_access" ] }, { "type": "string", "enum": [ "read_only" ] }, { "type": "string", "enum": [ "branch_specific" ] }, { "type": "string", "enum": [ "customize" ] } ] }, "protectedBranchIds": { "type": "array", "items": { "format": "uuid", "type": "string" } }, "rules": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "branchDeveloperRules": { "deprecated": true, "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "allow" ] }, { "type": "string", "enum": [ "deny" ] }, { "type": "string", "enum": [ "approve" ] } ] } }, "updatedBy": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "mode", "protectedBranchIds", "rules", "branchDeveloperRules" ] } }, "required": [ "policy" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "summary": "Set agent policy", "x-mint": { "metadata": { "title": "Set agent policy", "sidebarTitle": "Set agent policy" } } } }, "/projects/{projectId}/agent-sessions/revoke": { "post": { "operationId": "revokeAgentSessions", "tags": [ "Governance" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentSessionEpoch": { "type": "integer" } }, "required": [ "agentSessionEpoch" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "summary": "Revoke agent sessions", "x-mint": { "metadata": { "title": "Revoke agent sessions", "sidebarTitle": "Revoke agent sessions" } } } }, "/projects/{projectId}/apply": { "post": { "operationId": "applyBatch", "summary": "Apply batch", "tags": [ "Secrets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "description": "branch name (default branch if omitted)", "type": "string" }, "entries": { "maxItems": 600, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "set" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "branch": { "type": "string" }, "service": { "type": "string" } }, "required": [ "kind", "name", "value" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "delete" ] }, "name": { "type": "string" }, "branch": { "type": "string" }, "service": { "type": "string" } }, "required": [ "kind", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rename" ] }, "serviceId": { "type": "string" }, "name": { "maxLength": 256, "type": "string" } }, "required": [ "kind", "serviceId", "name" ] } ] } }, "skipDeploy": { "type": "boolean" }, "excludeFromDeploy": { "maxItems": 100, "type": "array", "items": { "type": "string" } }, "deployOnly": { "maxItems": 100, "type": "array", "items": { "type": "string" } } }, "required": [ "entries" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "written": { "type": "boolean" } }, "required": [ "name", "written" ] } }, "services": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string" }, "result": { "anyOf": [ { "type": "string", "enum": [ "deployed" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "skipped" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "reason": { "type": "string" } }, "required": [ "serviceId", "result" ] } } }, "required": [ "entries", "services" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nWrite a batch of user secrets, then redeploy the compute services those values reach, one deploy per service. Entries are reported written individually and services are reported deployed, started, skipped or failed individually, because the writes commit before the deploys run and a failed deploy never rolls a value back. `skipDeploy` writes without deploying. `excludeFromDeploy` drops services the caller is deploying itself; `deployOnly` names the services to deploy and ignores derivation, which is how a failed deploy is retried with no entries. A rename writes no env, so it deploys nothing on its own and needs no `deploy` grant — a batch that both renames and writes still deploys, for the write. Gated on what the body contains: `secrets.write` for any set or delete, `service.rename` for a rename, `deploy` only for what can actually deploy. A project-scoped entry is authorized against every branch, since that is where its value lands. Deploying a stopped service starts it. A suspended service is skipped instead of deployed: a deploy would invalidate the RAM snapshot suspension exists to preserve, so it is left untouched and reported with reason `suspended`.", "x-mint": { "metadata": { "title": "Apply batch", "sidebarTitle": "Apply batch" } } } }, "/projects/{projectId}/approvals": { "get": { "operationId": "listApprovals", "summary": "List approvals", "tags": [ "Governance" ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApprovalStatus" }, "in": "query", "name": "status", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } } } } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List approvals", "sidebarTitle": "List approvals" } } } }, "/projects/{projectId}/approvals/{approvalId}/approve": { "post": { "operationId": "approveRequest", "summary": "Approve request", "tags": [ "Governance" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "approvalId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "$ref": "#/components/schemas/Approval" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nApprove one pending agent request (human admin+).", "x-mint": { "metadata": { "title": "Approve request", "sidebarTitle": "Approve request" } } } }, "/projects/{projectId}/approvals/{approvalId}/deny": { "post": { "operationId": "denyRequest", "summary": "Deny a pending request (admin+)", "tags": [ "Governance" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "approvalId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "$ref": "#/components/schemas/Approval" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Deny a pending request (admin+)", "sidebarTitle": "Deny request" } } } }, "/projects/{projectId}/backups": { "post": { "operationId": "createBackup", "summary": "Create a backup of the postgres service root branch", "tags": [ "Backups" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "name", "required": false, "description": "snapshot name" }, { "schema": { "type": "string", "enum": [ "manual" ] }, "in": "query", "name": "type", "required": false, "description": "manual backup tag; createBackup always creates manual backups" }, { "schema": { "type": "string" }, "in": "query", "name": "expiresAt", "required": false, "description": "RFC3339 expiry; omitted = keep until deleted" }, { "schema": { "type": "string" }, "in": "query", "name": "timestamp", "required": false, "description": "RFC3339 past point within the history window; omitted = now" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbSnapshot" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Create a backup of the postgres service root branch", "sidebarTitle": "Create backup" } } }, "get": { "operationId": "listBackups", "summary": "List postgres backups", "tags": [ "Backups" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbSnapshotList" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List postgres backups", "sidebarTitle": "List backups" } } } }, "/projects/{projectId}/backups/{backupId}": { "delete": { "operationId": "deleteBackup", "summary": "Delete a postgres backup", "tags": [ "Backups" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "in": "path", "name": "backupId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Delete a postgres backup", "sidebarTitle": "Delete backup" } } } }, "/projects/{projectId}/backups/{backupId}/restore": { "post": { "operationId": "restoreBackup", "summary": "Restore backup", "tags": [ "Backups" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "in": "path", "name": "backupId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbRestoreResult" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRestore the postgres service root branch to a backup (in-place rollback; requires approval)", "x-mint": { "metadata": { "title": "Restore backup", "sidebarTitle": "Restore backup" } } } }, "/projects/{projectId}/branches": { "post": { "operationId": "createBranch", "summary": "Create branch", "tags": [ "Branches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 256, "description": "lower-kebab: a-z, 0-9, hyphen (max 39)", "type": "string" }, "from": { "default": "main", "description": "parent branch name", "type": "string" }, "empty": { "default": false, "description": "create the branch and nothing else: none of the parent's services are forked and none of its branch-scoped secrets are copied (project-scoped secrets still apply). `from` only sets the parent link.", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/Branch" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nCreate a branch (database branch + Tigris fork + cloned compute groups, or empty)", "x-mint": { "metadata": { "title": "Create branch", "sidebarTitle": "Create branch" } } }, "get": { "operationId": "listBranches", "summary": "List branches", "tags": [ "Branches" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } } }, "required": [ "branches" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List branches", "sidebarTitle": "List branches" } } } }, "/projects/{projectId}/branches/{branchId}": { "delete": { "operationId": "deleteBranch", "summary": "Delete branch", "tags": [ "Branches" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "branchId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teardown": { "$ref": "#/components/schemas/TeardownSummary" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a branch (not the default). Gated — branch.delete.", "x-mint": { "metadata": { "title": "Delete branch", "sidebarTitle": "Delete branch" } } }, "patch": { "operationId": "renameBranch", "summary": "Rename branch", "tags": [ "Branches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "description": "lower-kebab: a-z, 0-9, hyphen", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "branchId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/Branch" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRename a branch (metadata only; not the default). Provider resources keep their original names.", "x-mint": { "metadata": { "title": "Rename branch", "sidebarTitle": "Rename branch" } } } }, "/projects/{projectId}/branches/{branch}/merge": { "post": { "operationId": "mergeBranch", "summary": "Merge branch", "tags": [ "Branches" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "from" ], "type": "object", "properties": { "from": { "description": "source branch name", "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "branch", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "name" ] } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "type", "name" ] } } }, "required": [ "created", "skipped" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nStructurally merge services from a source branch into this branch (no data). Gated — service.add.", "x-mint": { "metadata": { "title": "Merge branch", "sidebarTitle": "Merge branch" } } } }, "/projects/{projectId}/cron-jobs": { "post": { "operationId": "createCronJob", "summary": "Create cron job", "tags": [ "Cron" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "expression", "target" ], "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 64, "description": "unique per branch", "type": "string" }, "expression": { "minLength": 1, "maxLength": 256, "description": "5-field cron expression, always evaluated in UTC", "type": "string" }, "branch": { "description": "target branch (default: the project’s default branch)", "type": "string" }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "description": "Stored encrypted; its VALUES are never returned. Send the whole object to replace it — reads answer with `request` (method and header names only).", "type": "object", "properties": { "method": { "description": "default GET", "type": "string", "enum": [ "GET", "POST" ] }, "headers": { "description": "literal headers; put credentials in secretRefs instead", "type": "object", "additionalProperties": { "type": "string" } }, "body": { "description": "request body (POST only)", "type": "string" }, "secretRefs": { "description": "header name → project secret NAME. Resolved per attempt from whatever is current, so rotating a secret takes effect on the next attempt with no edit to the job. Looked up in the JOB’S own branch, then its project — not the target’s — so a service in another project or branch of this org sees a different scope than its own env; for a service target IN THE SAME project and branch, secrets bound to that service also count (the same value the service reads from its env there). Only user-defined secrets resolve — platform-managed credentials such as DATABASE_URL never do. A header may not be in both `headers` and `secretRefs`.", "type": "object", "additionalProperties": { "type": "string" } } } }, "requestTimeoutMs": { "minimum": 1000, "maximum": 300000, "description": "excludes cold start: the wake is timed separately", "type": "integer" }, "retry": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "description": "A cron schedule. Header values are write-only; `request` describes the stored request without them.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "branch_id": { "format": "uuid", "type": "string" }, "branch": { "description": "branch name, joined for readability — the id is the identity", "type": "string" }, "name": { "type": "string" }, "expression": { "type": "string" }, "timezone": { "description": "UTC in v1, so preview and the materializer can never disagree", "type": "string" }, "enabled": { "type": "boolean" }, "revision": { "description": "the If-Match guard for PATCH", "type": "integer" }, "next_run_at": { "format": "date-time", "type": [ "string", "null" ] }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "required": [ "method", "headerNames", "secretRefs" ], "description": "The non-secret description of the job’s request.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME for the secret-backed headers. Names are not credentials, so they are returned: an edit can re-send these as they are, where a literal header’s value must be supplied again.", "type": "object", "additionalProperties": { "type": "string" } } } }, "request_timeout_ms": { "type": "integer" }, "retry_policy": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "project_id", "branch_id", "branch", "name", "expression", "timezone", "enabled", "revision", "next_run_at", "target", "request", "request_timeout_ms", "retry_policy", "created_at", "updated_at" ] } }, "required": [ "job" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "invalid expression, target or name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "a job of this name already exists on the branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nCreate a cron job on a branch. Gated — cron.write. 403 also when the org is billing-suspended, its schedule quota is full, or the target service belongs to another organization.", "x-mint": { "metadata": { "title": "Create cron job", "sidebarTitle": "Create cron job" } } }, "get": { "operationId": "listCronJobs", "summary": "List cron jobs", "tags": [ "Cron" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name; omitted lists every branch" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "description": "A cron schedule. Header values are write-only; `request` describes the stored request without them.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "branch_id": { "format": "uuid", "type": "string" }, "branch": { "description": "branch name, joined for readability — the id is the identity", "type": "string" }, "name": { "type": "string" }, "expression": { "type": "string" }, "timezone": { "description": "UTC in v1, so preview and the materializer can never disagree", "type": "string" }, "enabled": { "type": "boolean" }, "revision": { "description": "the If-Match guard for PATCH", "type": "integer" }, "next_run_at": { "format": "date-time", "type": [ "string", "null" ] }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "required": [ "method", "headerNames", "secretRefs" ], "description": "The non-secret description of the job’s request.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME for the secret-backed headers. Names are not credentials, so they are returned: an edit can re-send these as they are, where a literal header’s value must be supplied again.", "type": "object", "additionalProperties": { "type": "string" } } } }, "request_timeout_ms": { "type": "integer" }, "retry_policy": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "project_id", "branch_id", "branch", "name", "expression", "timezone", "enabled", "revision", "next_run_at", "target", "request", "request_timeout_ms", "retry_policy", "created_at", "updated_at" ] } } }, "required": [ "jobs" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList the project’s cron jobs, optionally for one branch.", "x-mint": { "metadata": { "title": "List cron jobs", "sidebarTitle": "List cron jobs" } } } }, "/projects/{projectId}/cron-jobs/preview": { "post": { "operationId": "previewCronExpression", "summary": "Preview cron expression", "tags": [ "Cron" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "expression" ], "type": "object", "properties": { "expression": { "minLength": 1, "maxLength": 256, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "error": { "description": "why the expression was rejected; absent when valid", "type": "string" }, "description": { "description": "human reading of the expression; empty when invalid", "type": "string" }, "next": { "description": "the next five fire times in UTC; empty when invalid", "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "valid", "description", "next" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nValidate a cron expression and show its next five fire times (UTC).", "x-mint": { "metadata": { "title": "Preview cron expression", "sidebarTitle": "Preview cron expression" } } } }, "/projects/{projectId}/cron-jobs/{id}": { "get": { "operationId": "getCronJob", "summary": "Get cron job", "tags": [ "Cron" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "description": "A cron schedule. Header values are write-only; `request` describes the stored request without them.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "branch_id": { "format": "uuid", "type": "string" }, "branch": { "description": "branch name, joined for readability — the id is the identity", "type": "string" }, "name": { "type": "string" }, "expression": { "type": "string" }, "timezone": { "description": "UTC in v1, so preview and the materializer can never disagree", "type": "string" }, "enabled": { "type": "boolean" }, "revision": { "description": "the If-Match guard for PATCH", "type": "integer" }, "next_run_at": { "format": "date-time", "type": [ "string", "null" ] }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "required": [ "method", "headerNames", "secretRefs" ], "description": "The non-secret description of the job’s request.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME for the secret-backed headers. Names are not credentials, so they are returned: an edit can re-send these as they are, where a literal header’s value must be supplied again.", "type": "object", "additionalProperties": { "type": "string" } } } }, "request_timeout_ms": { "type": "integer" }, "retry_policy": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "project_id", "branch_id", "branch", "name", "expression", "timezone", "enabled", "revision", "next_run_at", "target", "request", "request_timeout_ms", "retry_policy", "created_at", "updated_at" ] } }, "required": [ "job" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nRead one cron job. Header values are write-only; `request` gives the method, the header names, and the secret each secret-backed header names.", "x-mint": { "metadata": { "title": "Get cron job", "sidebarTitle": "Get cron job" } } }, "patch": { "operationId": "updateCronJob", "summary": "Update cron job", "tags": [ "Cron" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Changing `target` on a POST job, or one that sends headers, requires `request` in the same PATCH: stored header values and the body are write-only and never follow the job to a new destination.", "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 64, "type": "string" }, "expression": { "minLength": 1, "maxLength": 256, "type": "string" }, "enabled": { "description": "false pauses the job; in-flight runs are blocked at the send boundary", "type": "boolean" }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "description": "Stored encrypted; its VALUES are never returned. Send the whole object to replace it — reads answer with `request` (method and header names only).", "type": "object", "properties": { "method": { "description": "default GET", "type": "string", "enum": [ "GET", "POST" ] }, "headers": { "description": "literal headers; put credentials in secretRefs instead", "type": "object", "additionalProperties": { "type": "string" } }, "body": { "description": "request body (POST only)", "type": "string" }, "secretRefs": { "description": "header name → project secret NAME. Resolved per attempt from whatever is current, so rotating a secret takes effect on the next attempt with no edit to the job. Looked up in the JOB’S own branch, then its project — not the target’s — so a service in another project or branch of this org sees a different scope than its own env; for a service target IN THE SAME project and branch, secrets bound to that service also count (the same value the service reads from its env there). Only user-defined secrets resolve — platform-managed credentials such as DATABASE_URL never do. A header may not be in both `headers` and `secretRefs`.", "type": "object", "additionalProperties": { "type": "string" } } } }, "requestTimeoutMs": { "minimum": 1000, "maximum": 300000, "type": "integer" }, "retry": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } } } } } }, "description": "Changing `target` on a POST job, or one that sends headers, requires `request` in the same PATCH: stored header values and the body are write-only and never follow the job to a new destination." }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "if-match", "required": true, "description": "the job’s current `revision`" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "description": "A cron schedule. Header values are write-only; `request` describes the stored request without them.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "branch_id": { "format": "uuid", "type": "string" }, "branch": { "description": "branch name, joined for readability — the id is the identity", "type": "string" }, "name": { "type": "string" }, "expression": { "type": "string" }, "timezone": { "description": "UTC in v1, so preview and the materializer can never disagree", "type": "string" }, "enabled": { "type": "boolean" }, "revision": { "description": "the If-Match guard for PATCH", "type": "integer" }, "next_run_at": { "format": "date-time", "type": [ "string", "null" ] }, "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "request": { "required": [ "method", "headerNames", "secretRefs" ], "description": "The non-secret description of the job’s request.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME for the secret-backed headers. Names are not credentials, so they are returned: an edit can re-send these as they are, where a literal header’s value must be supplied again.", "type": "object", "additionalProperties": { "type": "string" } } } }, "request_timeout_ms": { "type": "integer" }, "retry_policy": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "project_id", "branch_id", "branch", "name", "expression", "timezone", "enabled", "revision", "next_run_at", "target", "request", "request_timeout_ms", "retry_policy", "created_at", "updated_at" ] } }, "required": [ "job" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "missing/invalid If-Match, an invalid expression or target, or a new target without `request` on a POST job or one that sends headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the job changed since that revision — re-read it and retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nUpdate a cron job. Requires If-Match: . Gated — cron.write.", "x-mint": { "metadata": { "title": "Update cron job", "sidebarTitle": "Update cron job" } } }, "delete": { "operationId": "deleteCronJob", "summary": "Delete cron job", "tags": [ "Cron" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a cron job. It stops firing and cannot be restored; its run history is no longer readable. Gated — cron.delete.", "x-mint": { "metadata": { "title": "Delete cron job", "sidebarTitle": "Delete cron job" } } } }, "/projects/{projectId}/cron-jobs/{id}/runs": { "post": { "operationId": "triggerCronJob", "summary": "Trigger cron job", "tags": [ "Cron" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "maxLength": 255, "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "dedupes a retried trigger onto the same run" } ], "responses": { "202": { "description": "accepted (runId) — or approval_required from the governance gate", "content": { "application/json": { "schema": { "description": "accepted (runId) — or approval_required from the governance gate", "anyOf": [ { "description": "the run was accepted", "type": "object", "properties": { "runId": { "format": "uuid", "type": "string" } }, "required": [ "runId" ] }, { "$ref": "#/components/schemas/ApprovalRequired" } ] } } } }, "400": { "description": "missing, blank, or over-255-character Idempotency-Key (a paused job is still triggerable: pause stops the clock, not a manual run)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "a run with this Idempotency-Key is still being created — retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nTrigger a run now. Requires Idempotency-Key. Gated — cron.run. 403 also when the org is billing-suspended.", "x-mint": { "metadata": { "title": "Trigger cron job", "sidebarTitle": "Trigger cron job" } } }, "get": { "operationId": "listCronRuns", "summary": "List cron runs", "tags": [ "Cron" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "default 20" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "schedule_id": { "format": "uuid", "type": "string" }, "scheduled_at": { "format": "date-time", "description": "the tick this run belongs to (manual runs: when it was asked for)", "type": "string" }, "trigger_type": { "type": "string", "enum": [ "scheduled", "manual" ] }, "schedule_revision": { "description": "the schedule as of dispatch; a later edit does not change a run in flight", "type": "integer" }, "status": { "description": "the terminal status IS the result — there is no separate outcome", "type": "string", "enum": [ "queued", "preparing", "sending", "retry_wait", "succeeded", "failed", "unknown", "cancelled", "skipped" ] }, "skip_reason": { "type": [ "string", "null" ], "enum": [ "overlap", "late", null ] }, "skipped_count": { "type": "integer" }, "dispatch_generation": { "type": "integer" }, "dispatched_at": { "format": "date-time", "type": [ "string", "null" ] }, "execution_epoch": { "description": "bumped per attempt; a superseded worker’s late result is dropped against it", "type": "integer" }, "platform_retry_count": { "type": "integer" }, "application_retry_count": { "type": "integer" }, "next_attempt_at": { "format": "date-time", "type": [ "string", "null" ] }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "finished_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "config": { "type": "object", "properties": { "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME, as frozen for this run", "type": "object", "additionalProperties": { "type": "string" } }, "requestTimeoutMs": { "type": "integer" }, "retry": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } } }, "required": [ "target", "method", "headerNames", "secretRefs", "requestTimeoutMs", "retry" ] } }, "required": [ "id", "schedule_id", "scheduled_at", "trigger_type", "schedule_revision", "status", "skip_reason", "skipped_count", "dispatch_generation", "dispatched_at", "execution_epoch", "platform_retry_count", "application_retry_count", "next_attempt_at", "started_at", "finished_at", "created_at", "config" ] } } }, "required": [ "runs" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList a cron job’s runs, most recent first.", "x-mint": { "metadata": { "title": "List cron runs", "sidebarTitle": "List cron runs" } } } }, "/projects/{projectId}/cron-jobs/{id}/runs/{runId}": { "get": { "operationId": "getCronRun", "summary": "Get cron run", "tags": [ "Cron" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "runId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "schedule_id": { "format": "uuid", "type": "string" }, "scheduled_at": { "format": "date-time", "description": "the tick this run belongs to (manual runs: when it was asked for)", "type": "string" }, "trigger_type": { "type": "string", "enum": [ "scheduled", "manual" ] }, "schedule_revision": { "description": "the schedule as of dispatch; a later edit does not change a run in flight", "type": "integer" }, "status": { "description": "the terminal status IS the result — there is no separate outcome", "type": "string", "enum": [ "queued", "preparing", "sending", "retry_wait", "succeeded", "failed", "unknown", "cancelled", "skipped" ] }, "skip_reason": { "type": [ "string", "null" ], "enum": [ "overlap", "late", null ] }, "skipped_count": { "type": "integer" }, "dispatch_generation": { "type": "integer" }, "dispatched_at": { "format": "date-time", "type": [ "string", "null" ] }, "execution_epoch": { "description": "bumped per attempt; a superseded worker’s late result is dropped against it", "type": "integer" }, "platform_retry_count": { "type": "integer" }, "application_retry_count": { "type": "integer" }, "next_attempt_at": { "format": "date-time", "type": [ "string", "null" ] }, "started_at": { "format": "date-time", "type": [ "string", "null" ] }, "finished_at": { "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "config": { "type": "object", "properties": { "target": { "description": "Where the job sends its request. An internal target names the SERVICE, never a URL: the worker resolves the live route at send time, so a redeploy or a region move cannot leave a job firing at a dead host.", "anyOf": [ { "required": [ "kind", "url" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] }, "url": { "description": "absolute http(s) URL", "type": "string" } } }, { "required": [ "kind", "serviceId", "path" ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "service" ] }, "serviceId": { "format": "uuid", "description": "a compute service in this project’s organization", "type": "string" }, "path": { "description": "request path on that service, leading slash required (e.g. /tasks/nightly)", "type": "string" } } } ] }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "headerNames": { "description": "names only, literal and secret-backed alike — never values", "type": "array", "items": { "type": "string" } }, "secretRefs": { "description": "header name → secret NAME, as frozen for this run", "type": "object", "additionalProperties": { "type": "string" } }, "requestTimeoutMs": { "type": "integer" }, "retry": { "type": "object", "properties": { "platformMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for failures where nothing was sent (wake/transport). Default 2.", "type": "integer" }, "applicationMaxRetries": { "minimum": 0, "maximum": 10, "description": "retries for a non-2xx answer. Default 0 — a broken endpoint should not be hammered.", "type": "integer" }, "retryableStatuses": { "maxItems": 20, "description": "e.g. [429, 503]; empty means none", "type": "array", "items": { "minimum": 100, "maximum": 599, "type": "integer" } }, "maxRunAgeMs": { "minimum": 0, "description": "give up on the run once it is this old, whatever the retry budget says", "type": "integer" } } } }, "required": [ "target", "method", "headerNames", "secretRefs", "requestTimeoutMs", "retry" ] } }, "required": [ "id", "schedule_id", "scheduled_at", "trigger_type", "schedule_revision", "status", "skip_reason", "skipped_count", "dispatch_generation", "dispatched_at", "execution_epoch", "platform_retry_count", "application_retry_count", "next_attempt_at", "started_at", "finished_at", "created_at", "config" ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "run_id": { "format": "uuid", "type": "string" }, "attempt_no": { "type": "integer" }, "execution_epoch": { "type": "integer" }, "started_at": { "format": "date-time", "type": "string" }, "finished_at": { "format": "date-time", "type": [ "string", "null" ] }, "wake_ms": { "description": "time spent waking the target, excluded from the request timeout", "type": [ "integer", "null" ] }, "request_ms": { "type": [ "integer", "null" ] }, "failure_kind": { "type": [ "string", "null" ], "enum": [ "wake_failed", "blocked", "http_error", "timeout", "transport", "interrupted", null ] }, "error_code": { "type": [ "string", "null" ] }, "http_status": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] } }, "required": [ "id", "run_id", "attempt_no", "execution_epoch", "started_at", "finished_at", "wake_ms", "request_ms", "failure_kind", "error_code", "http_status", "response_excerpt" ] } } }, "required": [ "run", "attempts" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nRead one run and every attempt it made.", "x-mint": { "metadata": { "title": "Get cron run", "sidebarTitle": "Get cron run" } } } }, "/projects/{projectId}/database/activity": { "get": { "operationId": "getDatabaseActivity", "summary": "Get database activity", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbActivity" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nCurrently running queries (pg_stat_activity/provider API, ≤100). Provider-specific; may wake a suspended database.", "x-mint": { "metadata": { "title": "Get database activity", "sidebarTitle": "Get database activity" } } } }, "/projects/{projectId}/database/databases": { "get": { "operationId": "listDatabases", "summary": "List databases", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbDatabaseList" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList databases in the postgres server.", "x-mint": { "metadata": { "title": "List databases", "sidebarTitle": "List databases" } } }, "post": { "operationId": "createDatabase", "summary": "Create database", "tags": [ "Database" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbDatabase" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nCreate a database in the postgres server. Host remains the same; only the database name changes in connection URLs.", "x-mint": { "metadata": { "title": "Create database", "sidebarTitle": "Create database" } } } }, "/projects/{projectId}/database/databases/{database}": { "delete": { "operationId": "deleteDatabase", "summary": "Delete database", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "in": "path", "name": "database", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a database from the postgres server.", "x-mint": { "metadata": { "title": "Delete database", "sidebarTitle": "Delete database" } } } }, "/projects/{projectId}/database/extensions": { "get": { "operationId": "listDatabaseExtensions", "summary": "List database extensions", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbExtensionsView" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList installed and available allowlisted postgres extensions.", "x-mint": { "metadata": { "title": "List database extensions", "sidebarTitle": "List database extensions" } } }, "patch": { "operationId": "updateDatabaseExtensions", "summary": "Update database extensions", "tags": [ "Database" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enable": { "type": "array", "items": { "type": "string" } }, "disable": { "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbExtensionsView" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nInstall or uninstall allowlisted postgres extensions.", "x-mint": { "metadata": { "title": "Update database extensions", "sidebarTitle": "Update database extensions" } } } }, "/projects/{projectId}/database/insight": { "get": { "operationId": "getDatabaseInsight", "summary": "Get database insight", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbInsight" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nDeep database health: size breakdown, per-table stats, vacuum health, unused indexes. Read-only; insta-db-backed services answer without waking a suspended instance.", "x-mint": { "metadata": { "title": "Get database insight", "sidebarTitle": "Get database insight" } } } }, "/projects/{projectId}/database/instance": { "get": { "operationId": "getDatabaseInstance", "summary": "Get database instance", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbInstanceInfo" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nThe postgres instance's current settings and resource ceiling (cpuMilli/memoryMib). insta-db-backed services only.", "x-mint": { "metadata": { "title": "Get database instance", "sidebarTitle": "Get database instance" } } } }, "/projects/{projectId}/database/metrics": { "get": { "operationId": "getDatabaseMetrics", "summary": "Get database metrics", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbMetricsSnapshot" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPoint-in-time DB metrics (connections, size, deadlocks, tuple churn, cache hit). Provider-specific; may wake a suspended database.", "x-mint": { "metadata": { "title": "Get database metrics", "sidebarTitle": "Get database metrics" } } } }, "/projects/{projectId}/database/password": { "post": { "operationId": "setDatabasePassword", "summary": "Set database password", "tags": [ "Database" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "description": "new password; omit to generate one", "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbCredentials" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code credential_change_in_progress: another credential change for this database (a rotation or a private-access toggle) is in flight — nothing was changed and the password is not rotated; retry in a moment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet or regenerate the postgres user password. Omitting password asks the provider to generate one.", "x-mint": { "metadata": { "title": "Set database password", "sidebarTitle": "Set database password" } } } }, "/projects/{projectId}/database/query": { "post": { "operationId": "runDatabaseQuery", "summary": "Run database query", "tags": [ "Database" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "sql" ], "type": "object", "properties": { "sql": { "minLength": 1, "type": "string" }, "params": { "description": "positional parameter values for $1..$n — audited as a count, never as values", "type": "array", "items": {} }, "maxRows": { "minimum": 1, "maximum": 1000, "default": 1000, "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "type": "string" }, "in": "query", "name": "database", "required": false, "description": "database on the instance (default: the connection-string database)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "dataTypeID": { "type": "integer" } }, "required": [ "name", "dataTypeID" ] } }, "rows": { "description": "rows as positional cells — duplicate column names stay distinct; numeric/int8 arrive as strings", "type": "array", "items": { "type": "array", "items": {} } }, "rowCount": { "type": "integer" }, "truncated": { "description": "true when maxRows clipped the result — narrow with WHERE/LIMIT", "type": "boolean" }, "queryId": { "description": "reserved for future cancellation", "type": [ "object", "null" ], "enum": [ null, null ] } }, "required": [ "columns", "rows", "rowCount", "truncated", "queryId" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code public_access_closed: the database's public access is closed and the console has no private lane on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRun one SQL statement with the service credential (full privileges — the gate and audit are a record, not a permission boundary). The audit log records a statement hash and parameter count, never SQL text or values. Gated — db.query. May wake a suspended database.", "x-mint": { "metadata": { "title": "Run database query", "sidebarTitle": "Run database query" } } } }, "/projects/{projectId}/database/query-stats": { "get": { "operationId": "getDatabaseQueryStats", "summary": "Get database query stats", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "max rows (1–100, default 20)" }, { "schema": { "type": "string", "enum": [ "total", "mean", "calls" ] }, "in": "query", "name": "sort", "required": false, "description": "order by (default total)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbQueryStats" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nTop statements by execution time (pg_stat_statements/provider API). Provider-specific; may wake a suspended database.", "x-mint": { "metadata": { "title": "Get database query stats", "sidebarTitle": "Get database query stats" } } } }, "/projects/{projectId}/database/restart": { "post": { "operationId": "restartDatabase", "summary": "Restart database", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbInstanceInfo" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRestart the postgres server (insta-db only) so settings written with ALTER SYSTEM that need a restart (wal_level, max_wal_senders, max_replication_slots, …) take effect. Connections drop while it restarts. Waits for the restart to finish. `pending: true` means it was still in progress when the wait ran out — GET .../database/instance reads `running` throughout, so confirm with `SHOW ` instead. A suspended database stays suspended — its next connection starts it with the new settings. Gated — deploy.", "x-mint": { "metadata": { "title": "Restart database", "sidebarTitle": "Restart database" } } } }, "/projects/{projectId}/database/settings": { "patch": { "operationId": "updateDatabaseSettings", "summary": "Update database settings", "tags": [ "Database" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionPooling": { "description": "enable provider-managed PgBouncer/connection pooling", "type": "boolean" }, "deletionProtection": { "type": "boolean" }, "scaleToZero": { "description": "enable or disable scale-to-zero", "type": "boolean" }, "cpu": { "description": "resource ceiling — vCPU as a provider quantity ('2', '4', '2500m'). PAID PLANS: the ceiling is the tier lever. Moves both directions (insta-db only)", "type": "string" }, "memory": { "description": "resource ceiling — memory as a provider quantity ('4Gi', '8Gi'). PAID PLANS. Moves both directions (insta-db only)", "type": "string" }, "idleTimeout": { "minimum": 0, "description": "scale-to-zero idle timeout in seconds", "type": "integer" }, "volumeSize": { "description": "the volume (block disk) size cap as whole Gi ('10Gi'). PAID PLANS: the ceiling is the tier lever. Grow-only — a provisioned disk cannot shrink (insta-db only)", "type": "string" }, "storageSize": { "deprecated": true, "description": "DEPRECATED alias of volumeSize — dropped next release", "type": "string" }, "privateAccess": { "description": "insta-db only — true: give the database a private network connection string and mint DATABASE_PRIVATE_URL (with the password) into its credentials beside DATABASE_URL, which is unchanged; compute services on the insta-compute provider bind it to connect without the public endpoint. false: retract DATABASE_PRIVATE_URL (refused while public access is closed); the response `warnings` name computes still bound to it. Gated — service.setAccess. 409 {code: private_lane_disabled} until the private lane is enabled on this deployment. Public access is NOT set here: use PUT /projects/{projectId}/services/{serviceId}/access.", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbInstanceInfo" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code private_lane_disabled: private network access is not yet available on this deployment. code private_lane_unavailable_in_region: the database's region has no private network lane yet — privateAccess was turned back off and nothing was minted. code credential_change_in_progress (privateAccess only): another credential change for this database (a private-access toggle or a password rotation) is in flight — nothing was changed; retry in a moment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nUpdate postgres settings: connection pooling, scale-to-zero, idle timeout, storage, deletion protection, and private network access.", "x-mint": { "metadata": { "title": "Update database settings", "sidebarTitle": "Update database settings" } } } }, "/projects/{projectId}/database/tables": { "get": { "operationId": "getDatabaseTables", "summary": "Get database tables", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "type": "string" }, "in": "query", "name": "database", "required": false, "description": "database on the instance (default: the connection-string database)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "schema": { "type": "string" }, "name": { "type": "string" }, "approxRows": { "description": "pg_class.reltuples estimate — render as \"~N rows\"", "type": "integer" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "dataType": { "type": "string" }, "default": { "type": [ "string", "null" ] }, "identity": { "type": "boolean" } }, "required": [ "name", "dataType", "nullable", "default", "identity" ] } }, "primaryKey": { "type": "array", "items": { "type": "string" } }, "foreignKeys": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "foreignSchema": { "type": "string" }, "foreignTable": { "type": "string" }, "foreignColumns": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "columns", "foreignSchema", "foreignTable", "foreignColumns" ] } } }, "required": [ "schema", "name", "approxRows", "columns", "primaryKey", "foreignKeys" ] } } }, "required": [ "tables" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code public_access_closed: the database's public access is closed and the console has no private lane on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList schemas, tables, columns, and keys (live introspection, never cached). Gated — db.query. May wake a suspended database.", "x-mint": { "metadata": { "title": "Get database tables", "sidebarTitle": "Get database tables" } } } }, "/projects/{projectId}/database/tables/{schema}/{table}/rows": { "get": { "operationId": "getDatabaseTableRows", "summary": "Get database table rows", "tags": [ "Database" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "type": "string" }, "in": "query", "name": "database", "required": false, "description": "database on the instance (default: the connection-string database)" }, { "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "schema", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "table", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "dataTypeID": { "type": "integer" } }, "required": [ "name", "dataTypeID" ] } }, "rows": { "description": "rows as positional cells — duplicate column names stay distinct; numeric/int8 arrive as strings", "type": "array", "items": { "type": "array", "items": {} } }, "rowCount": { "type": "integer" }, "truncated": { "description": "true when the 5MB byte budget dropped wide rows from this page", "type": "boolean" }, "approxRows": { "description": "reltuples estimate — exact COUNT(*) would scan the table on the user's compute", "type": "integer" } }, "required": [ "columns", "rows", "rowCount", "truncated", "approxRows" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code public_access_closed: the database's public access is closed and the console has no private lane on this deployment yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPage through a table in a stable order (primary key, else every column). Gated — db.query. May wake a suspended database.", "x-mint": { "metadata": { "title": "Get database table rows", "sidebarTitle": "Get database table rows" } } } }, "/projects/{projectId}/deploy": { "post": { "operationId": "deploy", "summary": "Deploy", "tags": [ "Deploy" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "minLength": 1, "description": "a prebuilt image ref. An archive-lane deploy sends the ref its own build produced, so this route takes images and nothing else", "type": "string" }, "branch": { "description": "branch name (default branch if omitted)", "type": "string" }, "group": { "description": "compute group name (default: the branch's sole compute service, else 'default')", "type": "string" }, "port": { "default": 8080, "type": "integer" }, "websocket": { "description": "compute only — omit to keep the service’s current setting; false turns it off", "type": "boolean" }, "endpoint": { "description": "compute only — how the service is reached from this deploy on; omit to keep its current endpoint. tcp: raw TCP on `port` at the service’s own public IPv6 address (IPv6 clients only, no platform TLS); refuses a service with a custom domain, websocket, and ports that are commonly scanned, web (80/443) or reserved by the platform. http: back to the HTTPS domain. insta-compute provider only.", "anyOf": [ { "type": "string", "enum": [ "http" ] }, { "type": "string", "enum": [ "tcp" ] } ] }, "replaceSource": { "description": "when the service deploys from a repo: switch it to this image and remove the repo connection (admin+). Without it such a deploy is refused with 409.", "type": "boolean" } }, "required": [ "image" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployResult" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "the app failed its deploy health gate (didn't answer on the routed port) — fix the app or its port and redeploy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "the compute provider deliberately refused: the capability is not enabled on this deployment — retrying cannot help", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "the compute provider could not roll the deploy — the previous version keeps serving; safe to retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDeploy a container image to a branch's compute group. Gated — deploy.", "x-mint": { "metadata": { "title": "Deploy", "sidebarTitle": "Deploy" } } } }, "/projects/{projectId}/deploy-events": { "get": { "operationId": "getDeployEvents", "summary": "Get deploy events", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string", "enum": [ "compute", "redis", "mysql", "mongodb" ] }, "in": "query", "name": "component", "required": false, "description": "service type (default 'compute'); 'db' has no machines and is invalid here" }, { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "service group (default: the branch's sole service of the component type, else 'default')" }, { "schema": { "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "instance", "required": false, "description": "limit to a single machine id" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployEventsResult" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nDeploy events for a compute service (machine lifecycle events; compute and managed databases)", "x-mint": { "metadata": { "title": "Get deploy events", "sidebarTitle": "Get deploy events" } } } }, "/projects/{projectId}/domains/{domainName}/attach": { "post": { "operationId": "attachPurchasedDomain", "summary": "Attach purchased domain", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "description": "the domain itself or any subdomain of it (default: the domain and its www)", "type": "string" }, "branch": { "description": "branch name (default branch if omitted)", "type": "string" }, "group": { "description": "compute service (default: the branch's sole compute service)", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasedDomain" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the hostnames already serve this service, a previous move or sweep has not landed, or the domain is delegated to nameservers outside the registrar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nPoint one hostname of a bought domain at a compute service of this project. Gated — deploy.", "x-mint": { "metadata": { "title": "Attach purchased domain", "sidebarTitle": "Attach purchased domain" } } } }, "/projects/{projectId}/events": { "get": { "operationId": "listEvents", "summary": "Audit + agent-event timeline (newest first)", "tags": [ "Audit" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch id; also includes project-scoped events" }, { "schema": { "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Audit + agent-event timeline (newest first)", "sidebarTitle": "List events" } } }, "post": { "operationId": "ingestEvents", "summary": "Ingest agent/resource events (idempotent per (project, dedupKey))", "tags": [ "Audit" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "maxItems": 100, "type": "array", "items": { "required": [ "source" ], "type": "object", "properties": { "source": { "type": "string", "enum": [ "agent", "resource" ] }, "kind": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "branchId": { "format": "uuid", "type": [ "string", "null" ] }, "dedupKey": { "type": [ "string", "null" ] } } } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "integer" }, "skipped": { "type": "integer" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Ingest agent/resource events (idempotent per (project, dedupKey))", "sidebarTitle": "Ingest events" } } } }, "/projects/{projectId}/events/stream": { "get": { "operationId": "streamEvents", "summary": "Live audit-event stream (Server-Sent Events)", "tags": [ "Audit" ], "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA long-lived `text/event-stream`. Each `audit` event carries the new row's id, projectId, branchId, source, kind and createdAt — never its payload; read that from `GET /projects/{projectId}/events`. Send the last event `id` back as `Last-Event-ID` to have what followed replayed (the opening frame carries an `id` too, so an idle stream can resume); the replay overlaps, so an event can arrive twice — dedupe by its `id`. A `reset` event means the gap could not be replayed in full (or the server lost its own subscription): refetch every view. A `live` event (projectId, branchId, kind; no `id`) signals progress that records no audit row — a service coming online, a build or deploy changing stage, a template run advancing — so refetch what its kind names; it is never replayed. The server ends each stream after a few minutes; reconnect with the cursor.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "last-event-id", "required": false, "description": "the `id` of the last event received; what followed it is replayed first" } ], "responses": { "200": { "description": "Server-Sent Events: `audit`, `live` and `reset` events", "content": { "text/event-stream": { "schema": { "type": "string" } } } } }, "x-mint": { "metadata": { "title": "Live audit-event stream (Server-Sent Events)", "sidebarTitle": "Stream events" } } } }, "/projects/{projectId}/logs": { "get": { "operationId": "getLogs", "summary": "Get logs", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string", "enum": [ "db", "compute", "redis", "mysql", "mongodb" ] }, "in": "query", "name": "component", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "service group/name (default: the branch's sole matching service, else 'default')" }, { "schema": { "default": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "region", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "instance", "required": false }, { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds — window start; compute pages the provider log cursor from here (~7-day retention)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds — window end (default now)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsResult" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nRuntime logs (compute and managed databases via the compute plane's logs API; DB via provider API when available)", "x-mint": { "metadata": { "title": "Get logs", "sidebarTitle": "Get logs" } } } }, "/projects/{projectId}/metrics": { "get": { "operationId": "getMetrics", "summary": "Get metrics", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string", "enum": [ "db", "compute", "redis", "mysql", "mongodb" ] }, "in": "query", "name": "component", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "one service by name; omit for EVERY service of this component on the branch, each series tagged with labels.group" }, { "schema": { "type": "string", "enum": [ "instance" ] }, "in": "query", "name": "breakdown", "required": false, "description": "CPU and memory per replica, labelled with labels.instance. Requires component=compute and an explicit nonempty group. Omit for service totals; network and disk remain service totals only." }, { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default now-3600)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default now)" }, { "schema": { "default": "60s", "type": "string" }, "in": "query", "name": "step", "required": false, "description": "PromQL step" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResult" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nResource metrics (compute and managed databases via the compute plane's metrics API; insta-db serves CPU/memory/storage series, other database providers return a note instead)", "x-mint": { "metadata": { "title": "Get metrics", "sidebarTitle": "Get metrics" } } } }, "/projects/{projectId}/operations": { "get": { "operationId": "listOperations", "summary": "List operations", "tags": [ "Observability" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch name (default branch if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "group", "required": false, "description": "postgres service name (default: the sole postgres service)" }, { "schema": { "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "max operations (provider default if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "pagination cursor from a previous page" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DbOperationsPage" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nRecent database provider operations. Control-plane — does NOT wake the database.", "x-mint": { "metadata": { "title": "List operations", "sidebarTitle": "List operations" } } } }, "/projects/{projectId}/runtime-health": { "get": { "operationId": "getProjectRuntimeHealth", "summary": "Get project runtime health", "tags": [ "Services" ], "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "branch to report on (omit for the project's default branch; must be non-empty) — scoped because a services table is per-branch, so reading every branch would cost a provider call per branch for rows the caller isn't showing" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "healthy", "crashed", "starting", "standby", "offline", "none", "unknown" ], "description": "healthy = started and answering (compute: at least one replica ready; postgres: instance running) · crashed = started but the check is critical / the machine or instance is in a failed state · starting = booting, no ready replicas yet · standby = scaled to zero at rest, wakes on request (normal) · offline = held down on purpose and NOT waking on request: stopped by the developer (start it to bring it back), or a reserved identity with no machine behind it yet (deploy to it) — insta-compute only · none = nothing deployed yet · unknown = the provider could not be read, or reported a state we don't recognize" }, "machines": { "description": "machines/instances the provider still knows about", "type": "integer" }, "failing": { "description": "machines/instances failed or carrying a critical check", "type": "integer" }, "lastRequestAt": { "format": "date-time", "description": "insta-compute only — when the plane last saw this service active, the clock its idle sweep consults before suspending. Omitted until the first activity, and on a plane that predates it. Evidence, not liveness: reading it renews nothing.", "type": "string" }, "lastActivitySource": { "description": "insta-compute only — what the last activity was: inbound_http · inbound_tcp · inbound_ip · outbound (measured egress, e.g. a worker calling a model) · shell_session · ready (a readiness probe) · unknown (recorded before the plane kept provenance). Open vocabulary: the plane may add sources.", "type": "string" }, "message": { "description": "insta-compute only — set when status is crashed: why the service failed, as the compute plane reported it", "type": "string" }, "desiredReplicas": { "minimum": 1, "description": "compute only — replicas the plane is converging to now (an autoscaled service moves this within its cap)", "type": "integer" }, "currentReplicas": { "minimum": 0, "description": "compute only — live non-terminating replicas; omitted when the runtime cannot be read", "type": "integer" }, "readyReplicas": { "minimum": 0, "description": "compute only — live ready replicas; omitted when the runtime cannot be read", "type": "integer" } }, "required": [ "serviceId", "status", "machines", "failing" ] } } }, "required": [ "services" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nLive runtime health of a branch's compute + postgres + managed database services (one entry each; storage omitted — object storage has no runtime). 'standby' means scaled to zero and waking on request, NOT a failure.", "x-mint": { "metadata": { "title": "Get project runtime health", "sidebarTitle": "Get project runtime health" } } } }, "/projects/{projectId}/secret-bindings": { "get": { "operationId": "getSecretBindings", "summary": "Get secret bindings", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "target", "required": false, "description": "target compute service ref: \"compute/\"; omit for every binding on the branch" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretBindings" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList explicit provider credential bindings — for one compute service, or for the whole branch when target is omitted. Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get secret bindings", "sidebarTitle": "Get secret bindings" } } } }, "/projects/{projectId}/secret-bindings/{name}": { "put": { "operationId": "setSecretBinding", "summary": "Set secret binding", "tags": [ "Secrets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "target", "source" ], "type": "object", "properties": { "branch": { "description": "Branch name (defaults to the project's default branch)", "type": "string" }, "target": { "description": "target compute service ref: \"compute/\"", "type": "string" }, "source": { "description": "source service ref, e.g. \"postgres/db\"", "type": "string" }, "sourceName": { "description": "source credential name; optional only when the source exposes exactly one credential", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true, "description": "^[A-Z][A-Z0-9_]{0,63}$" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nBind a provider-minted credential into a compute env var. Gated — secrets.write.", "x-mint": { "metadata": { "title": "Set secret binding", "sidebarTitle": "Set secret binding" } } }, "delete": { "operationId": "unsetSecretBinding", "summary": "Unset secret binding", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "target", "required": true, "description": "target compute service ref: \"compute/\"" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true, "description": "^[A-Z][A-Z0-9_]{0,63}$" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRemove an explicit provider credential binding from a compute env var. Gated — secrets.write.", "x-mint": { "metadata": { "title": "Unset secret binding", "sidebarTitle": "Unset secret binding" } } } }, "/projects/{projectId}/secret-sources": { "get": { "operationId": "getSecretSources", "summary": "Get secret sources", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretSources" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nCredential sources available for explicit compute env binding. Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get secret sources", "sidebarTitle": "Get secret sources" } } } }, "/projects/{projectId}/secrets": { "get": { "operationId": "getSecrets", "summary": "Get secrets", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "service", "required": false, "description": "Answer with ONE compute service's slice of this seam, as \"/\": that service's user secrets, the unbound ones, its explicit provider bindings, and the branch's canonical provider credentials. This is the .env seam NARROWED BY SERVICE, not a container inspection — a container receives a provider credential only where bound, so this read is deliberately wider than the deployed env. Compute only; a managed service is a 400 naming /services/:serviceId/credentials." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "merge" ] }, { "type": "string", "enum": [ "withhold" ] } ] }, "in": "query", "name": "on_collision", "required": false, "description": "How to answer a name several services define. \"merge\" (the default, and today's behaviour) returns whichever row is newest; \"withhold\" omits it. Either way the name is listed in `collisions`." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "$ref": "#/components/schemas/SecretsBundle" }, "collisions": { "type": "array", "items": { "$ref": "#/components/schemas/SecretCollision" } } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nThe secret seam — decrypt and return the branch's credential bundle, or one compute service's slice of it with ?service=/. Both carry the branch's canonical provider credentials (the .env contract, #323); NEITHER reports what a container receives, which needs an explicit binding. A name several services define is listed in `collisions`, and omitted from the bundle when ?on_collision=withhold. Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get secrets", "sidebarTitle": "Get secrets" } } } }, "/projects/{projectId}/secrets/tree": { "get": { "operationId": "getSecretTree", "summary": "Get secret tree", "tags": [ "Secrets" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretTree" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nSecret inventory (names only) as project→branch→service→secrets. Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get secret tree", "sidebarTitle": "Get secret tree" } } } }, "/projects/{projectId}/secrets/{name}": { "put": { "operationId": "setUserSecret", "summary": "Set user secret", "tags": [ "Secrets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "value" ], "type": "object", "properties": { "value": { "description": "secret value, max 8 KiB", "type": "string" }, "branch": { "description": "branch name (project-scoped if omitted)", "type": "string" }, "service": { "description": "bind to a branch service: \"/\" (requires branch)", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true, "description": "^[A-Z][A-Z0-9_]{0,63}$" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet a user-defined secret at project or branch scope. Gated — secrets.write.", "x-mint": { "metadata": { "title": "Set user secret", "sidebarTitle": "Set user secret" } } }, "delete": { "operationId": "unsetUserSecret", "summary": "Unset user secret", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (project-scoped if omitted)" }, { "schema": { "type": "string" }, "in": "query", "name": "service", "required": false, "description": "Service ref \"/\" to unset the secret bound to that service; omitted = the unbound secret. Scopes the delete so a per-service key does not wipe a sibling service’s same-name value." }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true, "description": "^[A-Z][A-Z0-9_]{0,63}$" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRemove a user-defined secret at project or branch scope. Gated — secrets.write.", "x-mint": { "metadata": { "title": "Unset user secret", "sidebarTitle": "Unset user secret" } } } }, "/projects/{projectId}/services": { "get": { "operationId": "listServices", "summary": "List services", "tags": [ "Services" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } }, "required": [ "services" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList the project's services (postgres | storage | compute | redis | mysql | mongodb)", "x-mint": { "metadata": { "title": "List services", "sidebarTitle": "List services" } } }, "post": { "operationId": "addService", "summary": "Add service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "name" ], "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "postgres" ] }, { "type": "string", "enum": [ "storage" ] }, { "type": "string", "enum": [ "compute" ] }, { "type": "string", "enum": [ "redis" ] }, { "type": "string", "enum": [ "mysql" ] }, { "type": "string", "enum": [ "mongodb" ] } ] }, "name": { "description": "lower-kebab: a-z, 0-9, hyphen", "type": "string" }, "branch": { "description": "target branch (default: project default branch)", "type": "string" }, "region": { "description": "region for postgres/compute/managed databases (see GET /regions); invalid for storage", "anyOf": [ { "type": "string", "enum": [ "us-east" ] }, { "type": "string", "enum": [ "eu-central" ] }, { "type": "string", "enum": [ "ap-southeast" ] } ] }, "public": { "description": "storage only — provision the bucket with anonymous public-read (default false)", "type": "boolean" }, "image": { "description": "compute only — container image to run at creation (e.g. nginx:1.27)", "type": "string" }, "port": { "description": "compute only — port the image listens on (default 8080)", "type": "integer" }, "endpoint": { "description": "compute only — how the service is reached. http (default): HTTPS at the service domain. tcp: raw TCP on `port` at the service’s own public IPv6 address (IPv6 clients only, no platform TLS, no custom domain). tcp needs an explicit port, and refuses ports that are commonly scanned (21, 22, 23, 25, 53, 445, 3389), web ports (80, 443) or reserved by the platform. Available on the insta-compute provider only.", "anyOf": [ { "type": "string", "enum": [ "http" ] }, { "type": "string", "enum": [ "tcp" ] } ] }, "alwaysOn": { "description": "compute and databases (postgres, redis, mysql, mongodb) — idle mode at creation; not for storage. Omitted: the platform default per kind. Compute: INSTA_COMPUTE_ALWAYS_ON_DEFAULT (false on InstaCloud: scale-to-zero — a machine with no inbound or outbound traffic suspends and wakes on the next request). Databases: INSTA_DB_ALWAYS_ON_DEFAULT (true on InstaCloud: the database stays warm, so an app waking from scale-to-zero never waits on a database cold start too; false opts a new database into scale-to-zero — the idle instance suspends and its first connection after idling cold-starts). true = always-on: never scales to zero. A worker (port 0) is always-on regardless; false with port 0 is refused. For postgres the value is recorded on the database instance (GET /projects/{projectId}/database/instance, scaleToZero) and changed with PATCH .../database/settings; for the other types on the service row (always_on) and changed with PUT .../services/{serviceId}/always-on. All plans; billing is actual usage either way — an always-on database bills its resident memory while idle.", "type": "boolean" }, "volumeMountPath": { "description": "Compute only: container mount path chosen on attachment; defaults to /data. Requires volumeGib only when attaching. Existing path changes are staged until the next deploy.", "type": "string" }, "volumeGib": { "minimum": 1, "description": "compute only — attach a persistent volume of this many whole Gi (attachable later too via PUT /services/:id/volume; the volume never detaches, but DELETE /services/:id/volume destroys it, data and all). Any plan may create up to the configured free volume cap (10Gi by default, env-overridable per deployment); a larger size is paid and capped at the org's own plan cap (50Gi on paid plans by default), like growing it later. Constraints: machineCount stays 1, and scale-to-zero uses stop (cold wake) instead of suspend — both lift if the volume is deleted.", "type": "integer" }, "pgVersion": { "description": "postgres only — the Postgres major version to create the database on: 16, 17, 18. Omitted: the platform default (INSTA_DB_POSTGRES_MAJOR; 16 on InstaCloud). Fixed for the database's lifetime; branches keep it. 501 when the database provider cannot create that major yet.", "type": "integer" }, "source": { "required": [ "owner", "repo" ], "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "owner": { "type": "string" }, "repo": { "type": "string" }, "installationId": { "description": "GitHub App installation id; required unless public", "type": "integer" }, "repoId": { "description": "GitHub repository id; required unless public", "type": "integer" }, "public": { "description": "a public repo, connected without an App installation: one-shot deploys, auto_deploy is always false", "type": "boolean" }, "branch": { "description": "the repo branch to track; default: the repo’s default branch", "type": "string" }, "rootDir": { "description": "subdirectory to build from (monorepo); relative, no leading / or ..; null/omitted = repo root. It also decides which pushes deploy this service: the build context is this directory, so a push that changed nothing under it is skipped", "type": [ "string", "null" ] }, "autoDeploy": { "description": "rebuild on every push to `branch` (default true; must be false or omitted for a public repo)", "type": "boolean" }, "buildCommand": { "type": [ "string", "null" ] }, "startCommand": { "type": [ "string", "null" ] }, "watchPaths": { "description": "An include list of gitignore patterns, matched against paths RELATIVE TO THE REPOSITORY ROOT rather than to `rootDir` — e.g. [\"apps/web/**\", \"packages/ui/**\"]. A push deploys this service only when it changed a matching path; omit or null to fall back to the root-directory rule (a service with `rootDir` deploys when a push changed something under it, one building from the repo root deploys on every push). `!` narrows the list under git's own rule that a path cannot be re-included once an earlier pattern took its directory, so [\"apps/web/**\", \"!**/*.md\"] drops apps/web/README.md but not apps/web/docs/guide.md. Inert on a public repo, which cannot auto-deploy at all", "type": [ "array", "null" ], "items": { "type": "string" } }, "port": { "description": "the port the app listens on; written to the service", "minimum": 1, "maximum": 65535, "type": [ "integer", "null" ] } } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "source": { "$ref": "#/components/schemas/ServiceSource" }, "build": { "type": "object", "properties": { "buildId": { "format": "uuid", "type": "string" }, "queued": { "description": "false when this commit already has a build (dedup)", "type": "boolean" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "buildId", "queued", "serviceId" ] }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "the database provider cannot create the requested pgVersion yet — nothing was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "the provider could not provision the service — nothing was created; safe to retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nAdd a service on demand. Assigns a default access domain (postgres/compute). Gated — service.add.", "x-mint": { "metadata": { "title": "Add service", "sidebarTitle": "Add service" } } } }, "/projects/{projectId}/services/{serviceId}": { "delete": { "operationId": "removeService", "summary": "Remove service", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "teardown": { "$ref": "#/components/schemas/TeardownSummary" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRemove a service and destroy its resources. Gated — service.remove.", "x-mint": { "metadata": { "title": "Remove service", "sidebarTitle": "Remove service" } } }, "patch": { "operationId": "updateService", "summary": "Update service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 256, "description": "new service name (lower-kebab, max 39); applied last so the other fields in this request still address the service by its current name", "type": "string" }, "alwaysOn": { "description": "true = machines never autostop; false = scale-to-zero (the platform default for new compute services; refused on a worker)", "type": "boolean" }, "memoryMb": { "description": "memory ceiling in MB — a multiple of 256, within the per-vCPU band", "type": "integer" }, "cpu": { "description": "vCPU ceiling; requires memoryMb, derived from it when omitted", "type": "integer" }, "startCommand": { "maxLength": 8192, "description": "Compute runtime startup override via sh -c, including source-built images; overrides the built image CMD on next deploy or restart. Empty resets to image default. Persisted as readable service settings; use secrets for credentials.", "type": "string" }, "volumeMountPath": { "description": "Compute only: container mount path chosen on attachment; defaults to /data. Requires volumeGib only when attaching. Existing path changes are staged until the next deploy.", "type": "string" }, "volumeGib": { "description": "the persistent volume size in whole Gi — attaches when none exists, grows an existing one (never shrinks)", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "applied": { "type": "array", "items": { "description": "the fields that actually changed: name, alwaysOn, limits, volume, volumeMountPath, startCommand", "type": "string" } }, "limits": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" } }, "required": [ "cpu", "memoryMb" ] }, "cap": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpu", "memoryMb", "volumeGib" ] }, "volume": { "type": "object", "properties": { "sizeGib": { "type": "integer" }, "mountPath": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "appliedMountPath": { "type": [ "string", "null" ] }, "pending": { "type": "boolean" } }, "required": [ "sizeGib", "mountPath" ] }, "volumeAttached": { "description": "true when this patch attached the volume (it mounts on the next deploy)", "type": "boolean" } }, "required": [ "applied" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nApply several service settings at once (compute and managed databases): rename, always-on, resource ceiling and data volume size. The whole patch is validated before anything applies, and every machine-facing change lands as one reconfigure per machine (one restart, not one per field).", "x-mint": { "metadata": { "title": "Update service", "sidebarTitle": "Update service" } } } }, "/projects/{projectId}/services/{serviceId}/access": { "put": { "operationId": "setServiceAccess", "summary": "Set service access", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "public" ], "type": "object", "properties": { "public": { "description": "storage: true = anonymous public-read, false = private (credential-gated). postgres: true = reachable on the public endpoint (the default), false = not reachable from the internet", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "impact": { "$ref": "#/components/schemas/AccessImpact" }, "notice": { "description": "postgres, when the access actually changed: it takes effect on the database proxy within about 30 seconds (connections opened before then may still use the previous setting). Absent when nothing changed.", "type": "string" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "postgres: code private_lane_disabled — closing public access needs the private network lane, which is not yet available on this deployment (re-opening is never refused)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "502": { "description": "the provider refused the change for the named bucket; the service flag is unchanged, and buckets earlier in the lineage may already have switched — retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet a service's public access mode. Storage: anonymous public-read on the bucket (lineage-wide). Managed databases (redis/mysql/mongodb): expose the database port on a dedicated public hostname and mint *_PUBLIC_URL/*_PUBLIC_HOST credentials (branch-scoped; internal credentials never move; password-auth on the open internet — a dev/test posture). Postgres (insta-db): born public; false closes the public endpoint (it refuses every connection with SQLSTATE 28000) so the database is not reachable from the internet and only the private network lane connects — requires private access on first (PATCH .../database/settings {privateAccess:true}), branch-scoped, and the response `impact` lists what will break (GET .../access/impact previews it). A change reaches the database proxy within about 30 seconds (the response `notice` says so); re-opening a database that is already public makes no provider call. Gated — service.setAccess.", "x-mint": { "metadata": { "title": "Set service access", "sidebarTitle": "Set service access" } } } }, "/projects/{projectId}/services/{serviceId}/access/impact": { "get": { "operationId": "getServiceAccessImpact", "summary": "Get service access impact", "tags": [ "Services" ], "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "public", "required": true, "description": "the access mode being considered" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "What changing a service's public access will break. Advisory: the change is never blocked on it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessImpact" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPreview what changing a service's public access would break, without changing anything. Postgres: closing public access (public=false) lists compute services that will lose the database (on the legacy compute plane, which cannot use the private network lane, or on insta-compute but still bound to the public DATABASE_URL) plus the external clients, CI and local development that will no longer be able to connect. Advisory only — the change is never blocked.", "x-mint": { "metadata": { "title": "Get service access impact", "sidebarTitle": "Get service access impact" } } } }, "/projects/{projectId}/services/{serviceId}/always-on": { "put": { "operationId": "setServiceAlwaysOn", "summary": "Set service always on", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "enabled" ], "type": "object", "properties": { "enabled": { "description": "true = machines never autostop (the default for new compute services); false = idle machines suspend and wake on request", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet a compute or managed-database service always-on (never scale to zero) or scale-to-zero (the platform default for new compute services). A worker (port 0) cannot be set scale-to-zero. All plans; billing is actual usage either way.", "x-mint": { "metadata": { "title": "Set service always on", "sidebarTitle": "Set service always on" } } } }, "/projects/{projectId}/services/{serviceId}/builds": { "get": { "operationId": "listServiceBuilds", "summary": "This service’s GitHub and uploaded-source builds, newest first", "tags": [ "Services" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "$ref": "#/components/schemas/BuildHistoryEntry" } } }, "required": [ "builds" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "This service’s GitHub and uploaded-source builds, newest first", "sidebarTitle": "List service builds" } } } }, "/projects/{projectId}/services/{serviceId}/credentials": { "get": { "operationId": "getServiceCredentials", "summary": "Get service credentials", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the service's branch)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "$ref": "#/components/schemas/SecretsBundle" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA service's provider-minted credentials (values). Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get service credentials", "sidebarTitle": "Get service credentials" } } } }, "/projects/{projectId}/services/{serviceId}/exec": { "post": { "operationId": "execService", "summary": "Exec service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "command" ], "type": "object", "properties": { "command": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "maxLength": 65536, "type": "string" } }, "timeoutSec": { "minimum": 1, "maximum": 180, "description": "default 30s", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "exitCode": { "type": "integer" }, "stdout": { "type": "string" }, "stderr": { "type": "string" }, "truncated": { "description": "true when stdout or stderr was cut at the 1 MiB cap", "type": "boolean" } }, "required": [ "exitCode", "stdout", "stderr" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "the command ran past timeoutSec; not retryable as-is — detach long work or raise timeoutSec", "content": { "application/json": { "schema": { "description": "the command ran past timeoutSec; not retryable as-is — detach long work or raise timeoutSec", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "exec_timeout" ] }, "stdout": { "description": "what the command printed before the deadline; absent when the provider did not return it", "type": "string" }, "stderr": { "description": "what the command printed to stderr before the deadline; absent when the provider did not return it", "type": "string" } }, "required": [ "error", "code" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRun a one-shot command inside a compute service's machine (wakes it first if scaled to zero). `command` is argv — no shell is invoked; use [\"sh\", \"-c\", \"...\"] for shell features. Gated under both `deploy` and `secrets.read`.", "x-mint": { "metadata": { "title": "Exec service", "sidebarTitle": "Exec service" } } } }, "/projects/{projectId}/services/{serviceId}/instances/{instanceId}": { "delete": { "operationId": "removeServiceInstance", "summary": "Remove service instance", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true }, { "schema": { "pattern": "^inst-[a-f0-9]{12}$", "type": "string" }, "in": "path", "name": "instanceId", "required": true, "description": "instance id, as per-instance metrics and logs report it" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nStop one named compute instance. The last instance cannot be removed.", "x-mint": { "metadata": { "title": "Remove service instance", "sidebarTitle": "Remove service instance" } } } }, "/projects/{projectId}/services/{serviceId}/limits": { "get": { "operationId": "getServiceLimits", "summary": "Get service limits", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "limits": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" } }, "required": [ "cpu", "memoryMb" ] }, "cap": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpu", "memoryMb", "volumeGib" ] }, "volume": { "description": "present only when the service has a volume", "type": "object", "properties": { "sizeGib": { "type": "integer" }, "mountPath": { "description": "configured container mount path (defaults to /data for compute)", "type": "string" } }, "required": [ "sizeGib", "mountPath" ] } }, "required": [ "limits", "cap" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA compute or managed-database service's current resource ceiling plus this plan's maximum (render a slider with its plan-limit marker). Includes the data volume (size + fixed mount path) when one is attached.", "x-mint": { "metadata": { "title": "Get service limits", "sidebarTitle": "Get service limits" } } }, "put": { "operationId": "setServiceLimits", "summary": "Set service limits", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "memoryMb" ], "type": "object", "properties": { "memoryMb": { "description": "memory ceiling in MB — a multiple of 256, within the per-vCPU band", "type": "integer" }, "cpu": { "description": "vCPU ceiling; omit to derive the smallest size that carries memoryMb. Explicit values must be a provider vCPU size (1, 2, 4, 6, 8)", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "limits": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" } }, "required": [ "cpu", "memoryMb" ] }, "cap": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpu", "memoryMb", "volumeGib" ] } }, "required": [ "limits", "cap" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet a compute or managed-database service's resource ceiling (paid plans; raise or lower). `memoryMb` is the dial — `cpu` is derived from it unless given, and the pair is validated against the provider's vCPU sizes and per-vCPU memory band. Billing is actual usage, so the ceiling is a cap, not a price.", "x-mint": { "metadata": { "title": "Set service limits", "sidebarTitle": "Set service limits" } } } }, "/projects/{projectId}/services/{serviceId}/objects": { "get": { "operationId": "listServiceObjects", "summary": "List service objects", "tags": [ "Storage" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "prefix", "required": false, "description": "Key prefix filter (S3 has no substring search)" }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque continuation token from a previous page" }, { "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false, "description": "max objects per page" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "objects": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "size": { "description": "object size in bytes", "type": "integer" }, "lastModified": { "format": "date-time", "type": "string" }, "etag": { "type": "string" } }, "required": [ "key", "size", "lastModified", "etag" ] } }, "nextCursor": { "description": "absent on the last page", "type": "string" } }, "required": [ "objects" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nList a storage service's bucket objects (prefix-filtered, cursor-paged). Gated — storage.read.", "x-mint": { "metadata": { "title": "List service objects", "sidebarTitle": "List service objects" } } }, "delete": { "operationId": "deleteServiceObject", "summary": "Delete service object", "tags": [ "Storage" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "key", "required": true, "description": "full object key, as returned by the listing" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "description": "also true when the key was already gone — S3 delete is idempotent", "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete one object from a storage service's bucket. DESTRUCTIVE, immediate and irreversible. Gated — storage.delete.", "x-mint": { "metadata": { "title": "Delete service object", "sidebarTitle": "Delete service object" } } } }, "/projects/{projectId}/services/{serviceId}/objects/delete": { "post": { "operationId": "deleteServiceObjects", "summary": "Delete service objects", "tags": [ "Storage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "keys" ], "type": "object", "properties": { "keys": { "minItems": 1, "maxItems": 1000, "description": "full object keys, as returned by the listing (S3's DeleteObjects cap is 1000)", "type": "array", "items": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "description": "keys deleted, counting keys that were already gone", "type": "integer" }, "failed": { "description": "per-key reasons; a batch may half-succeed", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "message": { "type": "string" } }, "required": [ "key", "message" ] } } }, "required": [ "deleted", "failed" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a batch of objects from a storage service's bucket. DESTRUCTIVE, immediate and irreversible. Gated — storage.delete.", "x-mint": { "metadata": { "title": "Delete service objects", "sidebarTitle": "Delete service objects" } } } }, "/projects/{projectId}/services/{serviceId}/objects/download": { "get": { "operationId": "presignServiceObjectDownload", "summary": "Presign service object download", "tags": [ "Storage" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "type": "string" }, "in": "query", "name": "key", "required": true, "description": "full object key, as returned by the listing" }, { "schema": { "type": "string", "enum": [ "attachment", "inline" ], "default": "attachment" }, "in": "query", "name": "disposition", "required": false, "description": "attachment (default) makes the browser save the file; inline lets it render one" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "presigned GET, 60s TTL, carrying the requested content disposition", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "url", "expiresAt" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPresign a short-lived download URL for one bucket object. Gated — storage.read.", "x-mint": { "metadata": { "title": "Presign service object download", "sidebarTitle": "Presign service object download" } } } }, "/projects/{projectId}/services/{serviceId}/objects/upload": { "post": { "operationId": "presignServiceObjectUpload", "summary": "Presign service object upload", "tags": [ "Storage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "key", "contentType", "size" ], "type": "object", "properties": { "key": { "description": "full object key to write, overwriting any object already there", "type": "string" }, "contentType": { "description": "MIME type of the file; the policy pins it, so the upload must send the same one", "type": "string" }, "size": { "minimum": 0, "maximum": 5368709120, "description": "file size in bytes; over the cap is refused before anything is signed", "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "branch", "required": false, "description": "Branch name (defaults to the project's default branch)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "POST the multipart form here — straight to the provider, not through this API", "type": "string" }, "fields": { "description": "policy form fields; send them verbatim BEFORE the file part", "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "format": "date-time", "description": "5 minutes out — an upload takes longer than a download click", "type": "string" } }, "required": [ "url", "fields", "expiresAt" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nPresign a short-lived upload straight to a storage service's bucket. Gated — storage.write.", "x-mint": { "metadata": { "title": "Presign service object upload", "sidebarTitle": "Presign service object upload" } } } }, "/projects/{projectId}/services/{serviceId}/rename": { "post": { "operationId": "renameService", "summary": "Rename service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "description": "lower-kebab: a-z, 0-9, hyphen", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRename a service. Gated — service.rename.", "x-mint": { "metadata": { "title": "Rename service", "sidebarTitle": "Rename service" } } } }, "/projects/{projectId}/services/{serviceId}/restart": { "post": { "operationId": "restartService", "summary": "Restart service", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "state": { "description": "live runtime state: running|suspended|stopped|none|unknown", "type": "string" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "not a compute service, nothing deployed yet, deliberately stopped/suspended, or the app did not answer on its port coming back up — in that last case the machines are rolled back to the config they were serving, best-effort: the message names any the provider could not put back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "the compute provider could not roll the restart — safe to retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nRestart a compute service by re-submitting the image reference recorded on it, against a freshly resolved env bundle. This is how a changed secret or binding reaches a running machine, and how a machine that is up but wedged gets cycled (`start` only wakes a machine that is DOWN — it no-ops on one that is already started). It asks for no new version and no new spec, but it does not pin a digest: a service recorded against a MOVING tag (`app:latest`) gets whatever that tag resolves to now, exactly as a redeploy of the same tag would. Requires desired_state 'running': a stopped or suspended service is brought back with `start`, which also re-enables auto-wake. All plans. Gated under `deploy`, like the deploy route it shares its pipeline with — a policy denying deploys denies this too, and `start`/`stop` stay ungated for cycling a wedged machine without one.", "x-mint": { "metadata": { "title": "Restart service", "sidebarTitle": "Restart service" } } } }, "/projects/{projectId}/services/{serviceId}/scale": { "post": { "operationId": "scaleService", "summary": "Scale service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "machineCount" ], "type": "object", "properties": { "machineCount": { "minimum": 1, "maximum": 10, "description": "replica cap: a scale-to-zero service runs 1 up to this many on demand; an always-on service runs exactly this many", "type": "integer" }, "region": { "description": "must equal the service's own region (fixed at creation); any other region is refused (400)", "anyOf": [ { "type": "string", "enum": [ "us-east" ] }, { "type": "string", "enum": [ "eu-central" ] }, { "type": "string", "enum": [ "ap-southeast" ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSet a compute service's replica cap (raising it needs a paid plan; free → 403).", "x-mint": { "metadata": { "title": "Scale service", "sidebarTitle": "Scale service" } } } }, "/projects/{projectId}/services/{serviceId}/secrets": { "get": { "operationId": "getServiceSecrets", "summary": "Get service secrets", "tags": [ "Secrets" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceSecrets" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA service's secret names (names only). Gated — secrets.read.", "x-mint": { "metadata": { "title": "Get service secrets", "sidebarTitle": "Get service secrets" } } } }, "/projects/{projectId}/services/{serviceId}/source": { "get": { "operationId": "getServiceSource", "summary": "Get service source", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ServiceSource" } }, "required": [ "source" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nWhere this compute service's image comes from: an image somebody deployed (type=image) or a connected repository (type=github, with the branch it tracks, auto-deploy and its newest build)", "x-mint": { "metadata": { "title": "Get service source", "sidebarTitle": "Get service source" } } }, "put": { "operationId": "setServiceSource", "summary": "Set service source", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "owner", "repo" ], "type": "object", "properties": { "type": { "type": "string", "enum": [ "github" ] }, "owner": { "type": "string" }, "repo": { "type": "string" }, "installationId": { "description": "GitHub App installation id; required unless public", "type": "integer" }, "repoId": { "description": "GitHub repository id; required unless public", "type": "integer" }, "public": { "description": "a public repo, connected without an App installation: one-shot deploys, auto_deploy is always false", "type": "boolean" }, "branch": { "description": "the repo branch to track; default: the repo’s default branch", "type": "string" }, "rootDir": { "description": "subdirectory to build from (monorepo); relative, no leading / or ..; null/omitted = repo root. It also decides which pushes deploy this service: the build context is this directory, so a push that changed nothing under it is skipped", "type": [ "string", "null" ] }, "autoDeploy": { "description": "rebuild on every push to `branch` (default true; must be false or omitted for a public repo)", "type": "boolean" }, "buildCommand": { "type": [ "string", "null" ] }, "startCommand": { "type": [ "string", "null" ] }, "watchPaths": { "description": "An include list of gitignore patterns, matched against paths RELATIVE TO THE REPOSITORY ROOT rather than to `rootDir` — e.g. [\"apps/web/**\", \"packages/ui/**\"]. A push deploys this service only when it changed a matching path; omit or null to fall back to the root-directory rule (a service with `rootDir` deploys when a push changed something under it, one building from the repo root deploys on every push). `!` narrows the list under git's own rule that a path cannot be re-included once an earlier pattern took its directory, so [\"apps/web/**\", \"!**/*.md\"] drops apps/web/README.md but not apps/web/docs/guide.md. Inert on a public repo, which cannot auto-deploy at all", "type": [ "array", "null" ], "items": { "type": "string" } }, "port": { "description": "the port the app listens on; written to the service", "minimum": 1, "maximum": 65535, "type": [ "integer", "null" ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ServiceSource" }, "build": { "type": "object", "properties": { "buildId": { "format": "uuid", "type": "string" }, "queued": { "description": "false when this commit already has a build (dedup)", "type": "boolean" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "buildId", "queued", "serviceId" ] } }, "required": [ "source", "build" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nConnect a repository to this compute service (admin+; replaces any previous source) — the tracked branch is built now and deployed into the service; every later push to it redeploys (unless autoDeploy is false, or the repo is public).", "x-mint": { "metadata": { "title": "Set service source", "sidebarTitle": "Set service source" } } }, "patch": { "operationId": "updateServiceSource", "summary": "Update service source", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "type": "string" }, "rootDir": { "type": [ "string", "null" ] }, "autoDeploy": { "type": "boolean" }, "buildCommand": { "type": [ "string", "null" ] }, "startCommand": { "type": [ "string", "null" ] }, "watchPaths": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ServiceSource" }, "build": { "type": "object", "properties": { "buildId": { "format": "uuid", "type": "string" }, "queued": { "description": "false when this commit already has a build (dedup)", "type": "boolean" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "buildId", "queued", "serviceId" ] } }, "required": [ "source" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nChange how a connected service builds (admin+): the tracked branch, root directory, auto-deploy, build/start commands. A branch, root-directory or command change deploys the new configuration now (even at the same commit).", "x-mint": { "metadata": { "title": "Update service source", "sidebarTitle": "Update service source" } } }, "delete": { "operationId": "clearServiceSource", "summary": "Clear service source", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/ServiceSource" } }, "required": [ "ok", "source" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDisconnect the repository (admin+). The service keeps running its current image; only future deploys stop.", "x-mint": { "metadata": { "title": "Clear service source", "sidebarTitle": "Clear service source" } } } }, "/projects/{projectId}/services/{serviceId}/source/builds": { "get": { "operationId": "listServiceSourceBuilds", "summary": "This service’s repo builds, newest first (history survives a disconnect)", "tags": [ "Services" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "builds": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceBuild" } } }, "required": [ "builds" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "This service’s repo builds, newest first (history survives a disconnect)", "sidebarTitle": "List service source builds" } } } }, "/projects/{projectId}/services/{serviceId}/source/deploy": { "post": { "operationId": "deployServiceSource", "summary": "Deploy service source", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "build": { "type": "object", "properties": { "buildId": { "format": "uuid", "type": "string" }, "queued": { "description": "false when this commit already has a build (dedup)", "type": "boolean" }, "serviceId": { "format": "uuid", "type": "string" } }, "required": [ "buildId", "queued", "serviceId" ] } }, "required": [ "build" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nBuild and deploy the tracked branch’s tip now — the redeploy for a public repo or a service with auto-deploy off; a terminal build of the same tip is re-run.", "x-mint": { "metadata": { "title": "Deploy service source", "sidebarTitle": "Deploy service source" } } } }, "/projects/{projectId}/services/{serviceId}/start": { "post": { "operationId": "startService", "summary": "Start service", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "state": { "description": "live runtime state: running|suspended|stopped|none|unknown", "type": "string" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nStart a compute service: brings it back up and clears any stop intent, re-enabling wake-on-request. All plans.", "x-mint": { "metadata": { "title": "Start service", "sidebarTitle": "Start service" } } } }, "/projects/{projectId}/services/{serviceId}/state": { "get": { "operationId": "getServiceState", "summary": "Get service state", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "desiredState": { "description": "running|stopped|suspended", "type": "string" }, "state": { "description": "running|suspended|stopped|none|unknown", "type": "string" }, "lastFailure": { "description": "the newest deploy attempt's failure; omitted when the newest attempt succeeded", "type": "object", "properties": { "kind": { "description": "build: no image was produced; deploy: the image was built (or given) but did not go live", "anyOf": [ { "type": "string", "enum": [ "deploy" ] }, { "type": "string", "enum": [ "build" ] } ] }, "at": { "format": "date-time", "type": "string" }, "reason": { "description": "tenant-safe: the same message the failing deploy or build already reported", "type": "string" }, "buildId": { "format": "uuid", "description": "when the attempt was a build: `insta build logs --source `", "type": "string" }, "buildSource": { "anyOf": [ { "type": "string", "enum": [ "github" ] }, { "type": "string", "enum": [ "archive" ] } ] } }, "required": [ "kind", "at", "reason" ] } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA compute service's desired (developer intent) vs. live runtime state.", "x-mint": { "metadata": { "title": "Get service state", "sidebarTitle": "Get service state" } } } }, "/projects/{projectId}/services/{serviceId}/stop": { "post": { "operationId": "stopService", "summary": "Stop service", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "state": { "description": "live runtime state: running|suspended|stopped|none|unknown", "type": "string" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nStop a compute service: it stays offline until an explicit start — on the microvm plane the router REFUSES traffic rather than waking it, so a stray request cannot bring it back (and cannot bill for it). All plans.", "x-mint": { "metadata": { "title": "Stop service", "sidebarTitle": "Stop service" } } } }, "/projects/{projectId}/services/{serviceId}/suspend": { "post": { "operationId": "suspendService", "summary": "Suspend service", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "state": { "description": "live runtime state: running|suspended|stopped|none|unknown", "type": "string" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nSuspend a compute service: takes it offline now, but on the microvm plane it still WAKES ON REQUEST (use stop to keep it offline). On the legacy plane it stays down until start. All plans.", "x-mint": { "metadata": { "title": "Suspend service", "sidebarTitle": "Suspend service" } } } }, "/projects/{projectId}/services/{serviceId}/upgrade": { "post": { "operationId": "upgradeService", "summary": "Upgrade service", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "spec" ], "type": "object", "properties": { "spec": { "description": "compute: a named rung 1vcpu-256mb..8vcpu-8gb (compute services only); up-only, and never above the org's plan ceiling", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nChange a compute/postgres service's spec (paid plans only; up-only).", "x-mint": { "metadata": { "title": "Upgrade service", "sidebarTitle": "Upgrade service" } } } }, "/projects/{projectId}/services/{serviceId}/volume": { "get": { "operationId": "getServiceVolume", "summary": "Get service volume", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "volume": { "description": "null = no volume attached (attach one any time with PUT …/volume)", "type": [ "object", "null" ], "properties": { "sizeGib": { "type": "integer" }, "mountPath": { "description": "configured container mount path (defaults to /data for compute)", "type": "string" }, "id": { "type": [ "string", "null" ] }, "appliedMountPath": { "type": [ "string", "null" ] }, "pending": { "type": "boolean" } }, "required": [ "sizeGib", "mountPath" ] }, "cap": { "type": "object", "properties": { "volumeGib": { "description": "this plan's maximum volume size (whole Gi)", "type": "integer" } }, "required": [ "volumeGib" ] } }, "required": [ "volume", "cap" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nA compute or managed-database service's data volume (size + mount path — configurable on attachment for compute, the image's data directory for a managed DB; null when none is attached) plus this plan's volume cap.", "x-mint": { "metadata": { "title": "Get service volume", "sidebarTitle": "Get service volume" } } }, "put": { "operationId": "setServiceVolume", "summary": "Set service volume", "tags": [ "Services" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mountPath": { "description": "Compute only: container mount path chosen on attachment; defaults to /data. Omit to preserve an existing path; path changes apply on the next deploy.", "type": "string" }, "sizeGib": { "minimum": 1, "description": "volume size in whole Gi — when a volume exists, must be ≥ its current size; omit to attach at the plan volume cap of the calling org (10Gi free / 50Gi paid by default, env-overridable per deployment) — or, when one exists, read it back unchanged", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "volume": { "type": "object", "properties": { "sizeGib": { "type": "integer" }, "mountPath": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "appliedMountPath": { "type": [ "string", "null" ] }, "pending": { "type": "boolean" } }, "required": [ "sizeGib", "mountPath" ] }, "cap": { "type": "object", "properties": { "volumeGib": { "type": "integer" } }, "required": [ "volumeGib" ] }, "changed": { "type": "boolean" }, "attached": { "description": "true when this call attached a NEW volume (it mounts at mountPath on the next deploy); false/absent when it grew an existing one", "type": "boolean" } }, "required": [ "volume", "cap" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nAttach or grow a compute service's persistent volume, or grow a managed database's data volume (always present). No volume yet: attaches one (sizeGib omitted = the org's OWN plan volume cap — 10Gi free, 50Gi paid by default, env-overridable per deployment; any plan may name a size up to the free cap; larger is paid and capped at the plan cap; machineCount must be 1; the disk is created and mounted on the NEXT deploy). Volume present: grows it (paid plans; grow-only — a provisioned disk cannot shrink; ≤ the plan's volume cap); sizeGib omitted never resizes; mountPath alone stages a path change for the next deploy (restarts the application), otherwise the request is a no-op read-back. Application configuration is not rewritten. Billing is actual data stored, so the size is a cap, not a price.", "x-mint": { "metadata": { "title": "Set service volume", "sidebarTitle": "Set service volume" } } }, "delete": { "operationId": "deleteServiceVolume", "summary": "Delete service volume", "tags": [ "Services" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "serviceId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" }, "volume": { "description": "always null — the service no longer has a volume", "type": [ "object", "null" ], "enum": [ null, null ] }, "cap": { "type": "object", "properties": { "volumeGib": { "type": "integer" } }, "required": [ "volumeGib" ] }, "removed": { "type": "boolean", "enum": [ true ] } }, "required": [ "volume", "cap", "removed" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "service not found, or the service has no volume", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "the provider could not unmount/destroy the disk — nothing was deleted; the volume is still attached and billed, retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDelete a compute service's persistent volume (compute only — a managed database's volume is its data directory and cannot be removed). DESTRUCTIVE and immediate: the disk and ALL its data are destroyed (there is no detach and no undo — download anything you need first). The machines are rebuilt without the mount right away, so billing for the volume stops now, idle wake returns to sub-second (suspend instead of cold stop/start), and the service may scale out again. Any plan; allowed even while the org is billing-suspended (deleting only reduces what bills).", "x-mint": { "metadata": { "title": "Delete service volume", "sidebarTitle": "Delete service volume" } } } }, "/projects/{projectId}/template-deployments": { "post": { "operationId": "createTemplateDeployment", "summary": "Create template deployment", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "templateCode": { "description": "a published registry code (see GET /templates); mutually implied with manifest — one of the two is required", "type": "string" }, "code": { "description": "alias of templateCode", "type": "string" }, "templateVersion": { "description": "optional pin; 404s when the registry serves a different version", "type": "string" }, "manifest": { "description": "inline insta.template.yaml for a local-manifest deploy — the YAML text, or the parsed JSON document" }, "branchId": { "format": "uuid", "type": "string" }, "branch": { "description": "branch NAME (alias of branchId). Omit both for a fresh branch named after the template code", "type": "string" }, "variables": { "description": "deploy-time variable values (required/optional env vars declared by the manifest)", "type": "object", "additionalProperties": { "type": "string" } }, "deploymentId": { "format": "uuid", "description": "idempotent retry: resume THIS deployment (same services, no duplicates) instead of starting a new one", "type": "string" }, "region": { "description": "InstaCloud region slug for EVERY service this deployment creates (see GET /regions). Default: the platform default region. Part of the deployment identity: a retry may omit it or repeat it, a different value is refused with 409.", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "202": { "description": "accepted (deploymentId + deployment to poll) — or approval_required from the governance gate", "content": { "application/json": { "schema": { "description": "accepted (deploymentId + deployment to poll) — or approval_required from the governance gate", "type": "object", "properties": { "deploymentId": { "format": "uuid", "description": "present when the deployment was accepted", "type": "string" }, "deployment": { "$ref": "#/components/schemas/TemplateDeployment" }, "status": { "type": "string", "enum": [ "approval_required" ] }, "approvalId": { "format": "uuid", "type": "string" }, "action": { "description": "the gated action, or a comma-joined compound set — prefer `actions`", "type": "string" }, "actions": { "description": "every capability this approval covers", "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "description": "the console page where a project admin reviews this request", "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "missing": { "description": "error='missing_variables': the required variables that resolved to no value", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "key" ] } } }, "required": [ "error" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the run is still in progress; the branch already holds the maximum number of copies of this template; or a service name is too long to suffix for another copy. Also code template_version_changed: the template was republished since it was read, fetch it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nDeploy a template onto a branch (async — poll GET /template-deployments/:id). Omit branch/branchId for a fresh branch named after the template. Deploying the same template into a branch that already runs it builds an INDEPENDENT copy — its services are named -2, -3 … and the existing copy is untouched — so the names in the response need not match the manifest. Gated — service.add + secrets.write + deploy, plus service.upgrade when the manifest declares a volume and service.setAccess when it declares a public bucket. Idempotent per (deploymentId, manifest): duplicate/mid-run re-invokes answer 202 with the current row.", "x-mint": { "metadata": { "title": "Create template deployment", "sidebarTitle": "Create template deployment" } } } }, "/projects/{projectId}/template-deployments/{deploymentId}/rollback": { "post": { "operationId": "rollbackTemplateDeployment", "summary": "Rollback template deployment", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "description": "values for required variables the older version needs that the instance no longer holds — an upgrade to a version that stopped declaring a variable DELETES its value, and the older manifest still requires it. Everything the services still hold is recovered and need not be resent; a 400 missing_variables names exactly what to send here", "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "deploymentId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "format": "uuid", "type": "string" }, "deployment": { "$ref": "#/components/schemas/TemplateDeployment" }, "status": { "type": "string", "enum": [ "approval_required" ] }, "approvalId": { "format": "uuid", "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "missing": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "key" ] } } }, "required": [ "error" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code template_no_step_back: this instance was not upgraded from anything, or it is itself the result of a rollback and the version it came from is the newer one. code template_version_not_recorded: the manifest for that version is no longer recorded. code template_version_content_changed: that version was republished with different content after this instance ran it, so the recorded manifest is not what it was running. code template_no_services: the deployment owns nothing to roll back. code template_superseded: this instance already moved off this deployment — the message names the one to act on instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nReturn a deployed template instance to the version it was upgraded from — one step, from wherever it is now (async — poll GET /template-deployments/:id). Restores the image, start command, port, always-on, public access, the volume mount path and recorded variables from the older manifest. An existing volume is never resized. Public access on a STORAGE service is lineage-wide: it sets that bucket's access on every branch that has a copy. It does NOT restore data: an app that migrated its own database under the newer version cannot read it back, and a volume only grows.", "x-mint": { "metadata": { "title": "Rollback template deployment", "sidebarTitle": "Rollback template deployment" } } } }, "/projects/{projectId}/template-deployments/{deploymentId}/upgrade": { "post": { "operationId": "upgradeTemplateDeployment", "summary": "Upgrade template deployment", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "description": "values for required variables the new version adds; existing values are recovered and need not be resent", "type": "object", "additionalProperties": { "type": "string" } }, "expectedVersion": { "description": "the version the caller reviewed; a different one in the registry answers 409 template_version_changed", "type": "string" }, "expectedDigest": { "description": "the to_digest from the preview; a different one answers 409 template_version_changed", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "deploymentId", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "format": "uuid", "type": "string" }, "deployment": { "$ref": "#/components/schemas/TemplateDeployment" }, "status": { "type": "string", "enum": [ "approval_required" ] }, "approvalId": { "format": "uuid", "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "missing": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "key" ] } } }, "required": [ "error" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code template_version_changed: republished since the review. code template_up_to_date: already running this content. code template_not_served: off the catalog. code template_no_services: the deployment owns nothing to upgrade. code template_superseded: this instance already moved off this deployment — the message names the one to act on instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).\n\nMove a deployed template instance to the version the registry serves now (async — poll GET /template-deployments/:id). The SAME services are reused: image, port, start command, always-on, public access, the volume mount path and the variables are all rewritten from the new manifest, a service the new version adds is created, and a service it drops is left running. A volume the new version adds to an existing service is attached at this plan's size and mounted by the run's own deploy; an existing volume is never resized, because a manifest cannot declare a size. Public access on a STORAGE service is lineage-wide — it sets that bucket public on every branch that has a copy, not only this one, and the preview's row for the field says so. Send expectedVersion/expectedDigest from the preview so a republish between review and apply is refused rather than run.", "x-mint": { "metadata": { "title": "Upgrade template deployment", "sidebarTitle": "Upgrade template deployment" } } } }, "/projects/{projectId}/template-drafts": { "post": { "operationId": "createTemplateDraft", "summary": "Generate a community template draft from this project's default environment", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The draft's name, trimmed, 1 to 80 characters. The template code is derived from it. Omitted: the project's name.", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "approvalId": { "type": "string" }, "action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "approvalId", "action", "actions", "message", "url" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Generate a community template draft from this project's default environment", "sidebarTitle": "Create template draft" } } } }, "/projects/{projectId}/usage": { "get": { "operationId": "getUsage", "summary": "Get usage", "tags": [ "Billing" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default current cycle start)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default current cycle end)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUsage" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nProject usage across the 5 billing dimensions over a window (default current cycle)", "x-mint": { "metadata": { "title": "Get usage", "sidebarTitle": "Get usage" } } } }, "/projects/{projectId}/usage/daily": { "get": { "operationId": "getUsageDaily", "summary": "Per-UTC-day 5-dimension usage for a project over a window (quantity + cost)", "tags": [ "Billing" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default current cycle start)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default current cycle end)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDailyUsage" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Per-UTC-day 5-dimension usage for a project over a window (quantity + cost)", "sidebarTitle": "Get usage daily" } } } }, "/projects/{projectId}/utilisation": { "get": { "operationId": "getProjectAppUtilisation", "summary": "Get project app utilisation", "tags": [ "Billing" ], "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPer-app actual-vs-allocated compute utilisation over a window (default current cycle)\n\nQuantities, not costs: the actual-consumption meters are collected at $0, so a cost-based ratio would read 0% for every app. `utilisation` is null when nothing was allocated in the window, which is not the same as 0% — the collector may simply not have run.", "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default current cycle start)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default current cycle end)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "projectId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAppUtilisation" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mint": { "metadata": { "title": "Get project app utilisation", "sidebarTitle": "Get project app utilisation" } } } }, "/template-deployments/{deploymentId}": { "get": { "operationId": "getTemplateDeployment", "summary": "Get template deployment", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "deploymentId", "required": true } ], "responses": { "200": { "description": "One server-side template deployment run and its progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDeployment" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nPoll a template deployment: status, current step, per-service URLs, and the failure log tail.", "x-mint": { "metadata": { "title": "Get template deployment", "sidebarTitle": "Get template deployment" } } } }, "/template-deployments/{deploymentId}/upgrade": { "get": { "operationId": "previewTemplateUpgrade", "summary": "Preview template upgrade", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "deploymentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/TemplateUpgradePlan" } }, "required": [ "plan" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code template_not_served: the registry no longer serves this template. code template_up_to_date: the instance already runs the content the registry publishes. code template_superseded: this instance already moved off this deployment — the message names the one to act on instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.\n\nWhat upgrading this deployment to the version the registry serves now would do: per-service field changes, which of them the upgrade writes and which it only reports, required variables with no value yet, and anything that makes the upgrade impossible. Each field row carries the label to show for it — render that label as given, because it is where a change states how far it reaches (public access on a storage service applies to that bucket on every branch). Reads only.", "x-mint": { "metadata": { "title": "Preview template upgrade", "sidebarTitle": "Preview template upgrade" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Session access JWT or an API token (`insta__`)." } }, "schemas": { "AccessImpact": { "description": "What changing a service's public access will break. Advisory: the change is never blocked on it.", "type": "object", "properties": { "warnings": { "description": "human-readable consequences of the change, most specific first; empty when nothing breaks", "type": "array", "items": { "type": "string" } }, "services": { "description": "compute services bound to this database that will lose their connection", "type": "array", "items": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "description": "compute service name", "type": "string" }, "provider": { "$ref": "#/components/schemas/ComputeProvider" }, "envName": { "description": "the env var the compute reads the database from", "type": "string" }, "sourceName": { "description": "the credential it is bound to (DATABASE_URL | DATABASE_PRIVATE_URL)", "type": "string" }, "reason": { "description": "provider-cannot-use-private-lane: the compute runs on the legacy compute plane, which has no path to the private network lane. bound-to-public-url: an insta-compute service still bound to DATABASE_URL — rebind it to DATABASE_PRIVATE_URL and redeploy.", "type": "string", "enum": [ "provider-cannot-use-private-lane", "bound-to-public-url" ] } }, "required": [ "id", "name", "envName", "sourceName", "reason" ] } } }, "required": [ "warnings", "services" ] }, "Approval": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "action": { "type": "string" }, "request_hash": { "type": [ "string", "null" ] }, "request_context": { "type": [ "object", "null" ], "additionalProperties": {} }, "branch_id": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ApprovalStatus" }, "requested_by": { "description": "Better Auth user id (opaque string, not a UUID)", "type": [ "string", "null" ] }, "decided_by": { "description": "Better Auth user id (opaque string, not a UUID)", "type": [ "string", "null" ] }, "requested_at": { "format": "date-time", "type": "string" }, "decided_at": { "format": "date-time", "type": [ "string", "null" ] } } }, "ApprovalRequired": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approval_required" ] }, "approvalId": { "format": "uuid", "type": "string" }, "action": { "description": "the gated action, or a comma-joined compound set — prefer `actions`", "type": "string" }, "actions": { "description": "every capability this approval covers", "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "description": "the console page where a project admin reviews this request", "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } }, "ApprovalStatus": { "type": "string", "enum": [ "pending", "granted", "denied", "consumed" ] }, "AuditEvent": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "branch_id": { "format": "uuid", "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "agent", "resource" ] }, "kind": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "actor_user_id": { "description": "Better Auth user id (opaque string, not a UUID)", "type": [ "string", "null" ] }, "dedup_key": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" } } }, "Branch": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "parent_branch_id": { "format": "uuid", "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "creating", "active", "error", "deleting" ] }, "created_at": { "format": "date-time", "type": "string" } } }, "BuildHistoryEntry": { "description": "A source build and deployment attempt for a compute service.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "type": "string", "enum": [ "github", "archive" ] }, "status": { "type": "string", "enum": [ "queued", "fetching", "building", "deploying", "live", "failed" ] }, "created_at": { "format": "date-time", "type": "string" }, "error": { "type": [ "string", "null" ] }, "commit_sha": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "status", "created_at", "error", "commit_sha" ] }, "BuildLogPage": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "ready", "pending", "unsupported", "unavailable" ] }, "buildState": { "type": "string" }, "error": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "digest": { "type": "string" }, "name": { "type": "string" }, "cached": { "type": "boolean" }, "hasLogs": { "type": "boolean" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "error": { "type": "string" } }, "required": [ "digest", "name", "cached", "hasLogs" ] } }, "entries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string" }, "message": { "type": "string" } }, "required": [ "timestamp", "message" ] } }, "nextCursor": { "description": "Opaque pagination cursor. No cursor means the current page is the tail, not that a running build has finished logging.", "type": "string" } }, "required": [ "state", "buildState", "steps", "entries" ] }, "CodedError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "description": "stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress", "type": "string" } }, "required": [ "error" ] }, "CommunityTemplate": { "type": "object", "properties": { "id": { "format": "uuid", "description": "The draft's stable id. A rename of its code keeps it, and a new draft gets a new one, even under a code a deleted draft had. Routes and editor links address a draft by its code.", "type": "string" }, "code": { "type": "string" }, "orgId": { "format": "uuid", "type": "string" }, "sourceProjectId": { "format": "uuid", "type": [ "string", "null" ] }, "blank": { "description": "Created with POST /orgs/{orgId}/templates, with no project behind it: every service is one the author added, and Regenerate From Project answers 400. A generated draft whose project was deleted is not blank.", "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published", "unpublished" ] }, "publishedVersion": { "type": [ "string", "null" ] }, "hasUnpublishedChanges": { "type": "boolean" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "readme": { "type": [ "string", "null" ] }, "defaultReadme": { "description": "A README skeleton built from the draft as it is now: service names and required variable names only, never a value. The console offers it behind a button; it is not stored.", "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "description": "web with a port, worker without one, or the managed type (postgres, redis, mysql, mongodb or storage). It and the fields below are the values after the author's settings.", "type": "string" }, "image": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ] }, "healthcheck": { "type": [ "string", "null" ] }, "volume": { "type": "boolean" }, "mountPath": { "description": "null with volume true: the volume mounts at the default /data. null with volume false: no volume.", "type": [ "string", "null" ] }, "command": { "type": [ "string", "null" ] }, "alwaysOn": { "type": [ "boolean", "null" ] }, "public": { "description": "Storage only, always present on a bucket: anonymous public-read, after the author's setting.", "type": "boolean" }, "pgVersion": { "description": "Postgres only: the major a deploy creates the database on, after the author's setting. Absent when the project's database recorded none.", "type": "integer" }, "added": { "description": "Present, and true, only on a service the author added: a PATCH deletes it for good. One from the project is removed instead.", "type": "boolean" }, "removed": { "description": "The author left this service out of the template. It stays listed so it can be restored.", "type": "boolean" }, "variables": { "description": "Sorted by the generator's name (originalName when renamed). Empty for a managed database. A removed service lists what restoring it brings back.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableView" } } }, "required": [ "name", "type", "image", "port", "healthcheck", "volume", "mountPath", "command", "alwaysOn", "removed", "variables" ] } }, "referenceOptions": { "description": "What a variable may reference in the template as it is now. A removed service offers nothing.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateReferenceOption" } }, "editableFields": { "$ref": "#/components/schemas/TemplateEditableFields" }, "referenceKeys": { "$ref": "#/components/schemas/TemplateReferenceKeys" }, "publishRequirements": { "description": "Always seven, in this order: has_service, no_blocked, no_conflicts, has_tagline, has_category, has_readme, required_descriptions.", "type": "array", "items": { "$ref": "#/components/schemas/TemplatePublishRequirement" } }, "report": { "$ref": "#/components/schemas/TemplateGenerationReport" }, "updatedAt": { "type": "string" }, "takenDown": { "description": "Staff took this template down. It cannot be republished.", "type": "boolean" }, "deployCount": { "description": "Succeeded deployments of this template.", "type": "integer" }, "totalProjects": { "description": "Distinct projects that deployed this template since its first publish, any outcome: the number the gallery card shows (the catalog's totalProjects).", "type": "integer" } }, "required": [ "id", "code", "orgId", "sourceProjectId", "blank", "status", "publishedVersion", "hasUnpublishedChanges", "name", "tagline", "category", "readme", "defaultReadme", "logoUrl", "services", "referenceOptions", "editableFields", "referenceKeys", "publishRequirements", "report", "updatedAt", "takenDown", "deployCount", "totalProjects" ] }, "ComputeProvider": { "description": "Compute plane actually backing a compute resource, derived from its provider_ref rather than its kind. Absent when it cannot be determined from the row — clients must then assert no provider rather than assume one from `kind`.", "type": "string", "enum": [ "fly", "insta-compute" ] }, "DbActivity": { "type": "object", "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/DbActivityRow" } } } }, "DbActivityRow": { "type": "object", "properties": { "pid": { "type": "integer" }, "state": { "type": "string" }, "waitEvent": { "type": "string" }, "durationMs": { "type": "number" }, "query": { "type": "string" }, "application": { "type": "string" }, "client": { "type": "string" }, "queryStart": { "type": "string" } } }, "DbConnections": { "type": "object", "properties": { "active": { "type": "integer" }, "idle": { "type": "integer" }, "total": { "type": "integer" }, "max": { "type": "integer" } } }, "DbCredentials": { "type": "object", "properties": { "connString": { "type": "string" }, "password": { "type": "string" }, "privateConnString": { "description": "the private network lane twin of connString (with the password). Present only while the instance has private access.", "type": "string" }, "credentialsStored": { "description": "password rotation only (insta-db) — true: the new connection strings were stored in the project secrets (DATABASE_URL, and DATABASE_PRIVATE_URL while private access is on). false: the password rotated but storing them failed, so the project secrets still carry the retired password and this response holds the only copy of the new credentials — rotate again to re-store them. Absent on a provider path that stores no credentials. Branch on this, not on `warnings` text: a warning can accompany a successful store.", "type": "boolean" }, "warnings": { "description": "password rotation only — what to act on: compute services bound to this database that must be redeployed to pick up the new password, or (the rotation still succeeded) that re-storing DATABASE_URL / DATABASE_PRIVATE_URL failed, in which case this response holds the only copy of the new credentials.", "type": "array", "items": { "type": "string" } } } }, "DbDatabase": { "type": "object", "properties": { "name": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "connString": { "type": "string" }, "privateConnString": { "description": "the private network lane twin of connString — it CONTAINS the password, exactly like connString. Present only while the instance has private access.", "type": "string" } } }, "DbDatabaseList": { "type": "object", "properties": { "databases": { "type": "array", "items": { "$ref": "#/components/schemas/DbDatabase" } } } }, "DbExtensionSpec": { "type": "object", "properties": { "name": { "type": "string" }, "extension": { "type": "string" }, "required": { "description": "Installed by the platform and cannot be disabled", "type": "boolean" } } }, "DbExtensionsView": { "type": "object", "properties": { "available": { "type": "array", "items": { "$ref": "#/components/schemas/DbExtensionSpec" } }, "enabled": { "type": "array", "items": { "type": "string" } } } }, "DbInsight": { "type": "object", "properties": { "collected": { "description": "false = suspended instance or provider without the capability; sections are structural zeros", "type": "boolean" }, "sizes": { "type": "object", "properties": { "databaseBytes": { "type": "number" }, "tablesBytes": { "type": "number" }, "indexesBytes": { "type": "number" }, "walBytes": { "type": "number" } }, "required": [ "databaseBytes", "tablesBytes", "indexesBytes", "walBytes" ] }, "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "liveRows": { "type": "number" }, "dataBytes": { "type": "number" }, "indexBytes": { "type": "number" }, "seqScans": { "type": "number" }, "idxScans": { "type": "number" } }, "required": [ "name", "liveRows", "dataBytes", "indexBytes", "seqScans", "idxScans" ] } }, "vacuum": { "type": "object", "properties": { "totalDeadRows": { "type": "number" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "deadRows": { "type": "number" }, "deadPct": { "description": "dead / (dead + live), 0..100", "type": "number" }, "lastVacuum": { "description": "last manual or auto vacuum (UTC); omitted = never", "type": "string" }, "xidAge": { "type": "number" } }, "required": [ "name", "deadRows", "deadPct", "xidAge" ] } } }, "required": [ "totalDeadRows", "tables" ] }, "unusedIndexes": { "description": "never-scanned indexes, excluding constraint-backing ones", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "table": { "type": "string" }, "sizeBytes": { "type": "number" }, "scans": { "type": "number" } }, "required": [ "name", "table", "sizeBytes", "scans" ] } }, "note": { "description": "present when the provider serves no insight at all", "type": "string" } }, "required": [ "collected", "sizes", "tables", "vacuum", "unusedIndexes" ] }, "DbInstanceInfo": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "routeKey": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "connectionPooling": { "type": "boolean" }, "deletionProtection": { "type": "boolean" }, "scaleToZero": { "type": "boolean" }, "idleTimeoutSecs": { "type": "integer" }, "volumeSize": { "example": "10Gi", "description": "the service's volume (block disk) size", "type": "string" }, "volumeGib": { "type": "number" }, "storageSize": { "deprecated": true, "description": "DEPRECATED alias of volumeSize — dropped next release", "type": "string" }, "storageGiB": { "deprecated": true, "description": "DEPRECATED alias of volumeGib — dropped next release", "type": "number" }, "enabledExtensions": { "type": "array", "items": { "type": "string" } }, "cpuMilli": { "description": "current cpu ceiling in millicores (2000 = 2 vCPU)", "type": "integer" }, "memoryMib": { "description": "current memory ceiling in MiB", "type": "integer" }, "cap": { "description": "this plan's maximum for the ceilings — render sliders with their plan-limit markers. These are the caller's own tier caps and they move with the plan (and with env overrides per deployment), so read them from THIS field rather than assuming a tier's numbers; the parenthetical example that used to live here said 'pro 4 vCPU/4Gi/10Gi' and was stale on all three by the time anyone noticed.", "type": "object", "properties": { "cpuMilli": { "type": "integer" }, "memoryMib": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpuMilli", "memoryMib", "volumeGib" ] }, "pending": { "description": "true when the provider accepted the change asynchronously and it has not been applied yet — the ceiling/volume fields are then the PRE-change values. Re-read (GET) to see the applied state. Absent when the change was applied synchronously.", "type": "boolean" }, "publicAccess": { "description": "postgres (insta-db) — false: the public endpoint refuses every connection (SQLSTATE 28000) and the database is not reachable from the internet; only the private network lane connects. Change it with PUT .../services/{serviceId}/access. Absent when the provider does not report it.", "type": "boolean" }, "privateAccess": { "description": "postgres (insta-db) — true: the database has a private network connection string (privateConnString, and DATABASE_PRIVATE_URL in the service credentials) for compute services on the insta-compute provider. Change it with PATCH .../database/settings {privateAccess}. Absent when the provider does not report it.", "type": "boolean" }, "privateConnString": { "description": "the connection string over the private network lane, WITHOUT the password (the full URL is DATABASE_PRIVATE_URL in the service credentials). Present only while privateAccess is on.", "type": "string" }, "privateLane": { "description": "GET .../database/instance only — this deployment's private-lane switches, so a UI can render the toggles without a probing write", "type": "object", "properties": { "enabled": { "description": "the private network access toggle and closing public access are available on this deployment; false: both answer 409 {code: private_lane_disabled}", "type": "boolean" }, "console": { "description": "the platform console reaches databases over the private network lane; false: it uses the public endpoint, so it cannot browse a database whose public access is closed", "type": "boolean" } }, "required": [ "enabled", "console" ] }, "warnings": { "description": "what this change will break and how to fix it (e.g. compute services bound to DATABASE_PRIVATE_URL when private access is turned off). Advisory: the change was applied.", "type": "array", "items": { "type": "string" } } } }, "DbMetricsSnapshot": { "type": "object", "properties": { "connections": { "$ref": "#/components/schemas/DbConnections" }, "dbSizeBytes": { "type": "number" }, "deadlocks": { "type": "number" }, "tuples": { "$ref": "#/components/schemas/DbTuples" }, "cacheHitRatio": { "description": "0..1; blks_hit/(blks_hit+blks_read). Omitted when unmeasurable (suspended instance or no cache traffic yet)", "type": "number" }, "state": { "description": "provider instance state (e.g. running/suspended) when known", "type": "string" }, "serverVersion": { "description": "postgres server version, e.g. \"16.14\", when measured", "type": "string" } } }, "DbOperation": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "example": "start_compute", "type": "string" }, "status": { "example": "finished", "type": "string" }, "endpointId": { "type": "string" }, "durationMs": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "DbOperationsPage": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/DbOperation" } }, "nextCursor": { "type": "string" } } }, "DbQueryStatRow": { "type": "object", "properties": { "queryId": { "type": "string" }, "query": { "type": "string" }, "calls": { "type": "number" }, "meanMs": { "type": "number" }, "totalMs": { "type": "number" }, "rows": { "type": "number" } } }, "DbQueryStats": { "type": "object", "properties": { "stats": { "type": "array", "items": { "$ref": "#/components/schemas/DbQueryStatRow" } }, "extensionReady": { "type": "boolean" } } }, "DbRestoreResult": { "type": "object", "properties": { "snapshotId": { "type": "string" }, "activeBranchId": { "description": "the project default branch id AFTER restore (changes on finalize_restore)", "type": "string" }, "backupBranchName": { "type": "string" }, "finalized": { "type": "boolean" } } }, "DbSnapshot": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "description": "provider backup type, such as full or incr", "type": "string" }, "tags": { "description": "provider backup tags; tags.type=manual marks user-created manual backups", "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string" }, "timestamp": { "type": "string" }, "sizeBytes": { "type": "number" } } }, "DbSnapshotList": { "type": "object", "properties": { "backups": { "type": "array", "items": { "$ref": "#/components/schemas/DbSnapshot" } } } }, "DbTuples": { "type": "object", "properties": { "inserted": { "type": "integer" }, "updated": { "type": "integer" }, "deleted": { "type": "integer" } } }, "DeployEvent": { "type": "object", "properties": { "ts": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "origin": { "description": "event source as the compute plane reports it", "type": "string" }, "instance": { "description": "machine id", "type": "string" } } }, "DeployEventsResult": { "type": "object", "properties": { "source": { "example": "insta-compute", "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/DeployEvent" } }, "note": { "type": "string" } } }, "DeployResult": { "type": "object", "properties": { "sourceCleared": { "description": "the service deployed from a repo before this call; that connection is removed and the source is now `image`", "type": "boolean" }, "machineId": { "type": "string" }, "url": { "format": "uri", "type": "string" }, "endpointHost": { "description": "endpoint tcp only — the host to connect to on the service port (IPv6-only); such a service has no `url`", "type": "string" }, "branch": { "type": "string" }, "group": { "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } }, "DimensionUsage": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "ram", "cpu", "volume", "storage", "egress" ] }, "quantity": { "type": "number" }, "unit": { "example": "GB·min", "type": "string" }, "costUsd": { "description": "quantity × unit price for this dimension in the window", "type": "number" } } }, "DomainHostnameState": { "type": "object", "properties": { "hostname": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "attached", "active", "failed" ] }, "reason": { "type": "string" }, "service": { "description": "the compute service this hostname serves; each hostname of a domain can serve a different one", "type": [ "string", "null" ] } }, "required": [ "hostname", "state", "service" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "LogLine": { "type": "object", "properties": { "ts": { "type": "string" }, "level": { "type": "string" }, "instance": { "type": "string" }, "region": { "type": "string" }, "message": { "type": "string" } } }, "LogsResult": { "type": "object", "properties": { "source": { "example": "insta-compute", "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/LogLine" } }, "nextToken": { "type": "string" }, "note": { "type": "string" } } }, "MetricSeries": { "type": "object", "properties": { "name": { "type": "string" }, "unit": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "sampleIntervalSeconds": { "exclusiveMinimum": 0, "description": "Source sampling interval in seconds, independent of the requested chart step.", "type": "number" }, "points": { "type": "array", "description": "[unixSeconds, value] pairs", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "MetricsResult": { "type": "object", "properties": { "source": { "example": "insta-compute", "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } }, "note": { "description": "present when a provider can't serve the request (e.g. DB metrics)", "type": "string" } } }, "NextAction": { "type": "object", "properties": { "op": { "description": "Neutral logical action id, e.g. \"service.add\" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface.", "type": "string" }, "reason": { "description": "Natural-language, human/LLM-facing \"why do this now\".", "type": "string" }, "args": { "description": "Suggested, flat named arguments; \"\"s where a value is unknown.", "type": "object", "additionalProperties": true }, "gated": { "description": "True if the action passes a governance gate.", "type": "boolean" } }, "required": [ "op", "reason" ] }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "Project": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "owner_user_id": { "description": "Better Auth user id (opaque string, not a UUID)", "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "error", "deleting", "deleted" ] }, "created_at": { "format": "date-time", "type": "string" } } }, "ProjectAppUtilisation": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "example": "insta-myapp-ab12", "type": "string" }, "resourceId": { "type": "string" }, "cpu": { "$ref": "#/components/schemas/ResourceUtilisation" }, "ram": { "$ref": "#/components/schemas/ResourceUtilisation" } } } }, "total": { "type": "object", "properties": { "cpu": { "$ref": "#/components/schemas/ResourceUtilisation" }, "ram": { "$ref": "#/components/schemas/ResourceUtilisation" }, "cpuUnmeasuredApps": { "description": "apps excluded from the cpu ratio for lack of a reading", "type": "integer" }, "ramUnmeasuredApps": { "description": "apps excluded from the ram ratio for lack of a reading", "type": "integer" }, "cpuSuspectApps": { "description": "apps excluded because actual exceeded allocation — impossible, so the stored rows are wrong", "type": "integer" }, "ramSuspectApps": { "description": "apps excluded because actual exceeded allocation — impossible, so the stored rows are wrong", "type": "integer" }, "cpuUnmeteredApps": { "description": "apps with no cpu metering rows at all — the ratio was computed over a smaller fleet than the real one", "type": "integer" }, "ramUnmeteredApps": { "description": "apps with no ram metering rows at all — the ratio was computed over a smaller fleet than the real one", "type": "integer" } } } } }, "ProjectDailyUsage": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "example": "2026-06-15", "description": "UTC calendar day", "type": "string" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } } } } } } }, "ProjectUsage": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } }, "totalCostUsd": { "type": "number" }, "byService": { "description": "the same window and the same money split by service — deleted services included, plus one unattributed bucket where the service is unrecoverable. Sums to totalCostUsd. A postgres lineage ROOT is attributed to its origin service, so a forked environment’s database cost lands on the service it was forked from.", "type": "array", "items": { "$ref": "#/components/schemas/ServiceUsage" } } } }, "PurchasedDomain": { "type": "object", "properties": { "domainName": { "type": "string" }, "status": { "type": "string", "enum": [ "registered", "attaching", "active", "attach_failed", "detached" ], "description": "detached: every service its hostnames named is gone — attach it again" }, "hostnames": { "type": "array", "items": { "$ref": "#/components/schemas/DomainHostnameState" } }, "registeredAt": { "format": "date-time", "type": [ "string", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "privacy": { "type": "boolean" }, "locked": { "description": "the registrar transfer lock: while it is on, no other registrar can pull the domain away. Turn it off to move the domain out. What the last write reported, or what registration asked for — nothing reads it back", "type": "boolean" }, "nameservers": { "description": "what the registrar holds. Empty means never written — only a nameserver write fills it in", "type": "array", "items": { "type": "string" } }, "delegated": { "description": "the zone is answered by nameservers InstaCloud cannot write to (custody `foreign`), so nothing published resolves and an attach is refused. A MANAGED delegation reads false: the platform still publishes there", "type": "boolean" }, "custody": { "type": "string", "enum": [ "registrar", "managed", "foreign" ], "description": "who answers the domain's zone: the registrar's own nameservers, a managed InstaCloud zone (delegated, still platform-published), or somewhere the platform cannot write" }, "transferLockExpiresAt": { "description": "ICANN 60-day lock after registration: no transfer out before this, whatever `locked` says", "format": "date-time", "type": [ "string", "null" ] }, "orderId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "domainName", "status", "hostnames", "registeredAt", "expiresAt", "autorenew", "privacy", "locked", "nameservers", "delegated", "custody", "transferLockExpiresAt", "orderId" ] }, "Resource": { "description": "Public view of a provisioned resource (no credential material).", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "$ref": "#/components/schemas/ResourceKind" }, "provider": { "$ref": "#/components/schemas/ComputeProvider" }, "name": { "description": "compute group label for a compute resource (kind=fly | insta-compute)", "type": [ "string", "null" ] }, "branchId": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "type": "string" }, "ref": { "description": "Non-credential identifiers (e.g. service url, bucket name, database project id)", "type": "object", "additionalProperties": true } } }, "ResourceKind": { "type": "string", "enum": [ "neon", "insta-db", "s3", "fly", "insta-compute" ] }, "ResourceUtilisation": { "type": "object", "properties": { "allocated": { "description": "the ceiling that was billed, in `unit`. NULL means no allocation was recorded in this window — not that nothing was allocated.", "type": [ "number", "null" ] }, "actual": { "description": "what the app actually consumed, same unit. NULL means not measured in this window — not zero.", "type": [ "number", "null" ] }, "unit": { "example": "vCPU·min", "type": "string" }, "utilisation": { "description": "actual / allocated; null when either side is unknown", "type": [ "number", "null" ] }, "suspect": { "description": "actual exceeds allocation, which is physically impossible — the stored rows are wrong. Excluded from totals.", "type": "boolean" }, "unmetered": { "description": "the app exists but the collector produced no rows at all for it in this window — neither allocation nor reading. Worse than an absent reading: nothing bounds how much of the fleet is missing.", "type": "boolean" } } }, "SecretBinding": { "type": "object", "properties": { "envName": { "type": "string" }, "sourceName": { "type": "string" }, "target": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ] }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ] } }, "required": [ "envName", "sourceName", "target", "source" ] }, "SecretBindings": { "type": "object", "properties": { "bindings": { "type": "array", "items": { "$ref": "#/components/schemas/SecretBinding" } } }, "required": [ "bindings" ] }, "SecretCollision": { "type": "object", "properties": { "name": { "description": "env-var name more than one service defines, so a flat bundle cannot attribute a value to it", "type": "string" }, "services": { "description": "\"/\" of every service that defines it; a since-removed holder appears as its service id", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "services" ] }, "SecretSource": { "type": "object", "properties": { "service": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "type", "name" ] }, "secrets": { "type": "array", "items": { "type": "string" } } }, "required": [ "service", "secrets" ] }, "SecretSources": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SecretSource" } } }, "required": [ "sources" ] }, "SecretTree": { "type": "object", "properties": { "projectWide": { "type": "array", "items": { "type": "string" } }, "branches": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "secrets": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "secrets" ] } }, "unbound": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "isDefault", "services", "unbound" ] } } }, "required": [ "projectWide", "branches" ] }, "SecretsBundle": { "description": "env-var name → decrypted value (e.g. DATABASE_URL, AWS_ACCESS_KEY_ID, ...)", "type": "object", "additionalProperties": { "type": "string" } }, "Service": { "description": "A project-level service (postgres | storage | compute | redis | mysql | mongodb).", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "type": { "type": "string", "enum": [ "postgres", "storage", "compute", "redis", "mysql", "mongodb" ] }, "name": { "type": "string" }, "spec": { "description": "compute: {cpu_kind,cpus,memory_mb}; postgres: sized by its instance ceiling (cpuMilli/memoryMib)", "type": "object", "additionalProperties": true }, "machine_count": { "description": "compute only", "type": "integer" }, "desired_state": { "description": "compute only — developer-set lifecycle intent", "type": "string", "enum": [ "running", "stopped", "suspended" ] }, "always_on": { "description": "compute and managed databases (redis, mysql, mongodb) — true: machines never scale to zero; false: idle machines suspend and wake on request. A new compute service is born false (scale-to-zero, except a worker); a new managed database is born from INSTA_DB_ALWAYS_ON_DEFAULT (true on InstaCloud). Postgres is not recorded here: its idle mode lives on the database instance (GET /projects/{projectId}/database/instance, scaleToZero). Billing is actual usage either way.", "type": "boolean" }, "websocket": { "description": "compute only — the app speaks WebSocket, so its machines carry connections-based concurrency and a 512 MB guest floor. Re-asserted by any redeploy given no flag, including restart. null: never recorded.", "type": [ "boolean", "null" ] }, "endpoint": { "description": "compute only — how the service is reached. http: Host-routed HTTPS at `domain`. tcp: raw TCP at `endpoint_host`:`port` on the service’s own public IPv6 address (IPv6 clients only; no TLS from the platform, no custom domain, no WebSocket flag). Chosen at create, and changed by a deploy that passes `endpoint`. null: never chosen, which is http.", "type": [ "string", "null" ], "enum": [ "http", "tcp", null ] }, "endpoint_host": { "description": "compute, endpoint tcp only — the host to connect to on `port` (an IPv6-only name), set once a deploy has confirmed it; null otherwise", "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "domain": { "description": "default access domain (postgres/compute)", "type": [ "string", "null" ] }, "public": { "description": "storage — bucket(s) served with anonymous public-read; managed databases — the database port is exposed on a public address; postgres — the public endpoint accepts connections (true by default; false = not reachable from the internet, private network lane only)", "type": "boolean" }, "image": { "description": "compute only — container image currently run", "type": [ "string", "null" ] }, "port": { "description": "compute/managed database — compute image port, or the private database TCP port", "type": [ "integer", "null" ] }, "start_command": { "description": "Runtime startup override via sh -c; null uses the built image default. Stored as readable service settings.", "type": [ "string", "null" ] }, "volume_applied_mount_path": { "description": "Last successfully confirmed Compute mount path; null means unknown, not proof of a changed path.", "type": [ "string", "null" ] }, "volume_mount_path": { "description": "Compute volume mount path; null or omitted means /data for legacy volumes. Changes apply on deployment.", "type": [ "string", "null" ] }, "volume_gib": { "description": "compute/managed database — size (whole Gi) of the persistent data volume; null = no volume. Compute can attach/grow via PUT .../volume; managed databases are platform-managed in v1", "type": [ "integer", "null" ] }, "pg_version": { "description": "postgres only — the Postgres MAJOR version the service runs (e.g. 16), known before the instance is ever connected to or woken. Pick client tooling (pg_dump/pg_restore/psql) of the same major. null: never recorded (a legacy row). The exact server_version of a RUNNING instance is on GET .../database/metrics", "type": [ "integer", "null" ] }, "template_deployment_id": { "format": "uuid", "description": "the template deployment that created this service (survives branch clones); null for services created directly", "type": [ "string", "null" ] }, "template_modified": { "description": "true once the service was reconfigured away from its template-deployed spec", "type": "boolean" }, "template_code": { "description": "the template this service was deployed from; null for services created directly, and for one whose deployment record has been pruned", "type": [ "string", "null" ] }, "template_logo_url": { "description": "the template's mark; null when the template is not in the registry (or carries no logo). Official templates: a commit-pinned jsDelivr URL (TEMPLATE_LOGO_HOST). Community templates: any https:// link the author set. Joined live rather than stored, because a republish moves it", "type": [ "string", "null" ] }, "template_name": { "description": "the template's name as the registry spells it, for a surface people read; null when the template is not in the registry, or its manifest omits a name. Read from the manifest the registry serves NOW, beside the logo, because a republish can rename it", "type": [ "string", "null" ] }, "template_version": { "description": "the template version this instance was deployed from; null for a service created directly. Read from the deployment record, so it does not move when the registry is republished", "type": [ "string", "null" ] }, "template_latest_version": { "description": "the version the registry serves for this template now; null when the registry does not serve it — absent, unpublished or taken down. The row still reports template_code and template_name in those cases, because attribution of a resource its owner deployed is not catalog visibility. For display beside template_version, never for deciding whether an update exists", "type": [ "string", "null" ] }, "template_update_available": { "description": "true when upgrading this service's template deployment to the version the registry serves now would actually change something about the services it runs: a setting the new manifest would write, an environment variable it would write differently, a service it would add, or a variable it now requires that this instance holds no value for. A republish that only moved presentation is not an update, because applying it would change nothing, and neither is a new version string on identical content, which is what every community republish produces. False whenever the answer cannot be determined: a template absent from the registry, unpublished, taken down, a manifest this version of the platform cannot parse, or a registry read that failed. False too while the deployment's own run has not succeeded, because what an unfinished deploy needs is a retry, not an upgrade", "type": "boolean" }, "source": { "$ref": "#/components/schemas/ServiceSourceSummary" }, "status": { "type": "string", "enum": [ "creating", "active", "error", "deleting", "deleted" ] }, "created_at": { "format": "date-time", "type": "string" } } }, "ServiceBuild": { "description": "One build → image → deploy attempt of a service source (one per commit per source).", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "source_id": { "format": "uuid", "description": "the service source that queued it; null once that source was disconnected", "type": [ "string", "null" ] }, "project_id": { "format": "uuid", "type": "string" }, "service_id": { "format": "uuid", "type": [ "string", "null" ] }, "branch_id": { "format": "uuid", "type": [ "string", "null" ] }, "commit_sha": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "fetching", "building", "deploying", "live", "failed" ] }, "image_ref": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "ServiceSecrets": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "string" } } }, "required": [ "secrets" ] }, "ServiceSource": { "description": "Where a compute service’s running image comes from: an image somebody deployed (type=image, the absence of a connected source) or a connected repository (type=github).", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "github" ] }, "image": { "description": "type=image — the image the service runs; null when nothing has been deployed yet", "type": [ "string", "null" ] }, "id": { "format": "uuid", "type": "string" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "branch": { "description": "the repo branch this service tracks; defaults to the repo’s default branch", "type": "string" }, "root_dir": { "description": "subdirectory to build from (monorepo); null = repo root. Also decides which pushes deploy this service: the build context is this directory, so a push that changed nothing under it is skipped", "type": [ "string", "null" ] }, "watch_paths": { "description": "include list of gitignore patterns, matched against paths relative to the repository root (not to root_dir); a push deploys this service only when it changed a matching path. null/absent falls back to the root-directory rule: a service with root_dir deploys when a push changed something under it, one building from the repo root deploys on every push", "type": [ "array", "null" ], "items": { "type": "string" } }, "auto_deploy": { "description": "a push to `branch` rebuilds and redeploys; always false for a public repo (no App, no webhooks)", "type": "boolean" }, "public": { "description": "connected as a public repo, without a GitHub App installation", "type": "boolean" }, "installation_id": { "format": "uuid", "type": [ "string", "null" ] }, "repo_id": { "description": "GitHub repository id (bigint as string)", "type": [ "string", "null" ] }, "build_command": { "description": "custom build command for source builds without a Dockerfile; null uses automatic detection", "type": [ "string", "null" ] }, "start_command": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "last_build": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ServiceBuild" } ] }, { "type": "null" } ], "description": "the newest build of this service (null before the first)" } }, "required": [ "type" ] }, "ServiceSourceSummary": { "description": "compute only — where the running image comes from: an image somebody deployed (type=image) or a connected repository (type=github). Full resource: GET /projects/{id}/services/{serviceId}/source", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "github" ] }, "owner": { "type": "string" }, "repo": { "type": "string" }, "branch": { "description": "the repo branch this service tracks", "type": "string" }, "auto_deploy": { "description": "a push to `branch` rebuilds and redeploys the service", "type": "boolean" } }, "required": [ "type" ] }, "ServiceUsage": { "type": "object", "properties": { "serviceId": { "format": "uuid", "description": "null for the unattributed bucket: spend with no live service to name — its environment was deleted, or the resource predates service attribution (pre-0010, never backfilled). NOT spend of zero", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "description": "postgres | storage | compute | redis | mysql | mongodb", "type": [ "string", "null" ] }, "status": { "description": "'deleted' for a service that is gone but still owns history", "type": [ "string", "null" ] }, "branch": { "description": "the environment it belonged to; null for the unattributed bucket", "type": [ "string", "null" ] }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } }, "totalCostUsd": { "type": "number" } } }, "TeardownSummary": { "type": "object", "properties": { "destroyed": { "type": "integer" }, "failed": { "type": "integer" } } }, "TemplateDeployment": { "description": "One server-side template deployment run and its progress.", "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "description": "partial = some services came up healthy, others failed — created resources are kept either way", "type": "string", "enum": [ "running", "succeeded", "failed", "partial" ] }, "step": { "description": "the pipeline step the run is currently on (or stopped at)", "type": "string", "enum": [ "create_services", "write_variables", "deploy", "health_check" ] }, "templateCode": { "type": "string" }, "templateVersion": { "type": "string" }, "projectId": { "format": "uuid", "type": "string" }, "branchId": { "format": "uuid", "type": "string" }, "region": { "description": "InstaCloud region slug every service of this deployment was created in. Deployments recorded before regions were recorded read as the platform default.", "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "the service's actual name on the branch, which is the manifest's name only for the first copy — a second deployment of the same template into the same branch names its services -2 and leaves the first copy alone", "type": "string" }, "serviceId": { "format": "uuid", "type": "string" }, "url": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "created", "deployed", "healthy", "failed" ] }, "skipped": { "description": "an upgrade stepped over this service because the user had deleted it — the run never touched it, serviceId points at the deleted row, and state stays pending however the deployment ends. Not \"still in progress\"", "type": "boolean" } } } }, "error": { "type": "string" }, "logsTail": { "description": "container log tail captured when a service never became healthy", "type": "string" }, "rollbackTo": { "description": "the version one step back, present only when this deployment was produced by an upgrade: what POST .../rollback would return the instance to. Absent on a first deploy, once the predecessor is gone, and on a deployment a ROLLBACK produced — that row's step back is the newer version it just left, which is offered as the update, not as a way back. Present is not a promise it will succeed — a version whose manifest is no longer recorded, or was republished with different content, still refuses at click time", "type": "object", "properties": { "version": { "type": "string" } }, "required": [ "version" ] }, "createdAt": { "format": "date-time", "type": "string" } } }, "TemplateEditableFields": { "description": "Per service type, the TemplateServiceSettings keys a template service of that type takes. A PATCH answers 400 for any other.", "type": "object", "properties": { "web": { "type": "array", "items": { "type": "string", "enum": [ "image", "port", "healthcheck", "command", "mountPath", "alwaysOn" ] } }, "worker": { "type": "array", "items": { "type": "string", "enum": [ "image", "port", "healthcheck", "command", "mountPath", "alwaysOn" ] } }, "postgres": { "type": "array", "items": { "type": "string", "enum": [ "pgVersion" ] } }, "redis": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "mysql": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "mongodb": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "storage": { "type": "array", "items": { "type": "string", "enum": [ "public" ] } } }, "required": [ "web", "worker", "postgres", "redis", "mysql", "mongodb", "storage" ] }, "TemplateGenerationReport": { "description": "What generation skipped, what blocks publishing (each with a fix), and notices.", "type": "object", "properties": { "skipped": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } }, "notices": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } } }, "required": [ "skipped", "blocked", "notices" ] }, "TemplatePublishRequirement": { "description": "One condition publish checks. Publish answers 400 template_not_ready while any is not ok.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "has_service", "no_blocked", "no_conflicts", "has_tagline", "has_category", "has_readme", "required_descriptions" ] }, "ok": { "type": "boolean" }, "items": { "description": "no_blocked: each blocked reason. no_conflicts: one sentence with its fix for each name the author added that the project now has too, services first. required_descriptions: each . still without a description. Otherwise empty.", "type": "array", "items": { "type": "string" } } }, "required": [ "code", "ok", "items" ] }, "TemplateReferenceKeys": { "description": "Per managed service type, the credential keys a variable may reference on a service of that type, one the author has not applied yet included (secretNames.ts CANONICAL_KEYS). A web service's url and host are not listed.", "type": "object", "properties": { "postgres": { "type": "array", "items": { "type": "string" } }, "redis": { "type": "array", "items": { "type": "string" } }, "mysql": { "type": "array", "items": { "type": "string" } }, "mongodb": { "type": "array", "items": { "type": "string" } }, "storage": { "type": "array", "items": { "type": "string" } } }, "required": [ "postgres", "redis", "mysql", "mongodb", "storage" ] }, "TemplateReferenceOption": { "description": "What a variable may reference: a database connection key, a bucket key, or a web service address including the service itself.", "type": "object", "properties": { "token": { "description": "Exactly what a reference choice sends and the manifest stores.", "type": "string" }, "service": { "type": "string" }, "key": { "description": "A credential key of a managed database or a storage bucket, or url or host of a web service.", "type": "string" } }, "required": [ "token", "service", "key" ] }, "TemplateUpgradePlan": { "type": "object", "properties": { "from_version": { "description": "the version this instance was deployed from", "type": "string" }, "to_version": { "description": "the version the registry serves now", "type": "string" }, "to_digest": { "description": "content digest of the manifest this plan was computed from, send it back as expected_digest so the apply cannot run a version nobody reviewed", "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "key": { "description": "the manifest key; stable across copies, where the platform name may be -2", "type": "string" }, "service_id": { "type": [ "string", "null" ] }, "service_name": { "type": [ "string", "null" ] }, "gone": { "description": "the deployment created it and the branch no longer has it: the user deleted it. Reported, never recreated", "type": "boolean" }, "added": { "description": "the new version introduces it; the upgrade creates it", "type": "boolean" }, "fields": { "description": "what the upgrade will write on this service. On an `added` service these are the values it will be CREATED with, so `deployed` and `live` are null and `drifted` is false; a field the manifest does not declare gets no row and takes the platform default", "type": "array", "items": { "type": "object", "properties": { "field": { "description": "the `services` column this concerns — image, port, start_command, always_on, public, volume_gib (the new version adds a volume; it is attached at this plan's size) or volume_mount_path — so a client can deep-link to the setting", "type": "string" }, "label": { "description": "what to show for this row. Render it as given: it is where a field states how far its change reaches, e.g. public access on a storage bucket applies to that bucket on every branch", "type": "string" }, "deployed": { "type": [ "string", "null" ] }, "live": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] }, "drifted": { "description": "the live value differs from what the deployment recorded: the user changed it after deploying", "type": "boolean" }, "verdict": { "type": "string", "enum": [ "applied", "refused" ], "description": "applied: the upgrade writes it, which covers everything a manifest can declare for a service it keeps and for one it creates. refused: it cannot be changed in place at all, and refuses the whole upgrade" } }, "required": [ "field", "label", "drifted", "verdict" ] } }, "missing_variables": { "type": "array", "items": { "description": "required variables the new version needs that this instance has no value for", "type": "string" } } }, "required": [ "key", "gone", "added", "fields", "missing_variables" ] } }, "removed": { "type": "array", "items": { "description": "manifest keys the deployment created that the new version no longer declares. Left running", "type": "string" } }, "refusals": { "type": "array", "items": { "description": "non-empty means the upgrade cannot run at all", "type": "string" } } }, "required": [ "from_version", "to_version", "to_digest", "services", "removed", "refusals" ] }, "TemplateVariableView": { "description": "One variable of a template service as its author sees it.", "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "required", "optional", "default", "reference", "generated", "fixed", "removed" ] }, "value": { "description": "default: the default text. reference: the token. fixed: the literal or the address reference.", "type": "string" }, "description": { "description": "What whoever deploys reads. Omitted while it is the default sentence, which the console shows as an empty box.", "type": "string" }, "brokenReference": { "description": "The token this variable referenced before its service was removed from the template or left the project. The variable is then required.", "type": "string" }, "originalName": { "description": "Present only when the author renamed the variable: the generator's name, which a PATCH variables entry sends as name. name is then the new one.", "type": "string" }, "added": { "description": "Present, and true, only on a variable the author added: a PATCH deletes it for good. One from the project is removed with choice removed instead.", "type": "boolean" } }, "required": [ "name", "kind" ] } } } }