{ "openapi": "3.1.0", "info": { "title": "Hiraiship API", "version": "v1", "description": "Manage a Hiraiship workspace with an API key. Guides: https://docs.hiraiship.com/api" }, "servers": [ { "url": "https://api.hiraiship.com" } ], "paths": { "/api/v1/api-key/me": { "get": { "summary": "Get the current API key", "description": "The key making the request: its name, role, expiry and workspace. Handy to check a key before using it.", "tags": [ "workspace" ], "operationId": "get-api-key", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The key and its workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "developer", "viewer" ] }, "expiresAt": { "type": [ "string", "null" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "slug", "name" ] } }, "required": [ "id", "name", "prefix", "role", "expiresAt", "workspace" ] }, "example": { "id": "8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "name": "Production CI", "prefix": "hsk_a1b2", "role": "developer", "expiresAt": "2027-01-01T00:00:00.000Z", "workspace": { "id": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "slug": "acme", "name": "Acme Labs" } } } } }, "404": { "description": "The request was not made with an API key." } }, "x-hiraiship-role": "viewer" } }, "/api/v1/deployments": { "get": { "summary": "List deployments", "description": "Every deployment in the workspace, most recent first, each with its project's and environment's names.", "tags": [ "deployments" ], "operationId": "list-deployments", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The deployments.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "projectSlug": { "type": "string" }, "environmentName": { "type": "string" } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason", "projectId", "projectName", "projectSlug", "environmentName" ] } }, "example": [ { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": "sha256:5f1c9e0b7a2d4c6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e", "assetsManifestRef": "sha256:0a2c4e6f8b1d3f5a7c9e1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a", "status": "success", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": "https://acme-site.hiraiship.app", "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:41:19.000Z", "dispatchStatus": "live", "dispatchError": null, "publishStartedAt": "2026-10-03T16:41:12.000Z", "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null, "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "projectName": "Acme site", "projectSlug": "acme-site", "environmentName": "production" } ] } } }, "401": { "description": "No valid API key." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/deployments/{deploymentId}": { "get": { "summary": "Get a deployment", "description": "`status` is the build's (`queued`, `pending`, `success`, `failed`, with `error` set on failure); `dispatchStatus` is the publish's: `live` once the deployment serves traffic at `deployedUrl`.", "tags": [ "deployments" ], "operationId": "get-deployment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "deploymentId", "in": "path" } ], "responses": { "200": { "description": "The deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] }, "example": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": "sha256:5f1c9e0b7a2d4c6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e", "assetsManifestRef": "sha256:0a2c4e6f8b1d3f5a7c9e1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a", "status": "success", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": "https://acme-site.hiraiship.app", "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:41:19.000Z", "dispatchStatus": "live", "dispatchError": null, "publishStartedAt": "2026-10-03T16:41:12.000Z", "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null } } } }, "404": { "description": "No such deployment in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/deployments/{deploymentId}/cancel": { "post": { "summary": "Cancel a queued deployment", "description": "Only a deployment still `queued` can be cancelled: it becomes `failed` with `error: \"canceled\"`. A build that has started runs to its end.", "tags": [ "deployments" ], "operationId": "cancel-deployment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "deploymentId", "in": "path" } ], "responses": { "200": { "description": "The cancelled deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] }, "example": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": null, "assetsManifestRef": null, "status": "failed", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": null, "error": "canceled", "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:40:30.000Z", "dispatchStatus": "not_applicable", "dispatchError": null, "publishStartedAt": null, "publishPlanned": true, "buildMachine": "standard-1", "startedAt": null, "queuePosition": null, "queueReason": null } } } }, "404": { "description": "No such deployment in this workspace." }, "409": { "description": "The deployment is no longer queued: its build started or finished." } }, "x-hiraiship-permission": "deployment.create", "x-hiraiship-role": "developer" } }, "/api/v1/deployments/{deploymentId}/redeploy": { "post": { "summary": "Redeploy", "description": "Builds a GitHub-sourced deployment again, as a new deployment in the same environment, from the same commit (`gitSha`), whatever its branch points to now. To build the branch's latest commit, create a deployment with that `ref` instead. A deployment from a tarball has no stored source: deploy it again instead.", "tags": [ "deployments" ], "operationId": "redeploy", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "deploymentId", "in": "path" } ], "responses": { "202": { "description": "The new deployment, `pending` or `queued`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] }, "example": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": null, "assetsManifestRef": null, "status": "pending", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": null, "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": null, "dispatchStatus": "not_applicable", "dispatchError": null, "publishStartedAt": null, "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null } } } }, "400": { "description": "The deployment predates pinned commits and its `ref` no longer exists (`code: unknown_ref`)." }, "402": { "description": "A plan limit refused the build (see Create a deployment).", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] } } } }, "404": { "description": "No such deployment in this workspace." }, "409": { "description": "The deployment has no GitHub source to build from." }, "501": { "description": "GitHub builds are not configured on this Hiraiship instance." } }, "x-hiraiship-permission": "deployment.create", "x-hiraiship-role": "developer" } }, "/api/v1/deployments/{deploymentId}/steps": { "get": { "summary": "Get a deployment's build steps", "description": "The four build steps (`preparing`, `installing`, `building`, `packaging`) with their status and timing: the same data the stream sends, for a client that polls instead.", "tags": [ "deployments" ], "operationId": "list-deployment-steps", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "deploymentId", "in": "path" } ], "responses": { "200": { "description": "The steps, in order.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "deploymentId": { "type": "string" }, "step": { "type": "string", "enum": [ "preparing", "installing", "building", "packaging" ] }, "status": { "type": "string", "enum": [ "pending", "running", "success", "failed" ] }, "startedAt": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "deploymentId", "step", "status", "startedAt", "finishedAt" ] } }, "example": [ { "id": "0d1e2f3a-4b5c-4d6e-8f7a-000000000000", "deploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "step": "preparing", "status": "success", "startedAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:40:16.000Z" }, { "id": "0d1e2f3a-4b5c-4d6e-8f7a-000000000001", "deploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "step": "installing", "status": "success", "startedAt": "2026-10-03T16:40:17.000Z", "finishedAt": "2026-10-03T16:40:31.000Z" }, { "id": "0d1e2f3a-4b5c-4d6e-8f7a-000000000002", "deploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "step": "building", "status": "success", "startedAt": "2026-10-03T16:40:32.000Z", "finishedAt": "2026-10-03T16:40:46.000Z" }, { "id": "0d1e2f3a-4b5c-4d6e-8f7a-000000000003", "deploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "step": "packaging", "status": "success", "startedAt": "2026-10-03T16:40:47.000Z", "finishedAt": "2026-10-03T16:40:61.000Z" } ] } } }, "404": { "description": "No such deployment in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/deployments/{deploymentId}/stream": { "get": { "summary": "Stream a deployment's build", "description": "A Server-Sent Events stream (`text/event-stream`). While the deployment is queued it sends `status` events with its `queuePosition` and `queueReason` (`plan_limit`: your plan's concurrent builds are all running; `capacity`: no build machine is free yet). It replays every build step (`step`) and log line (`log`) recorded so far, then sends new ones as they happen, and closes after `done` once the deployment succeeds or fails. Each `log` event has an `id`: a connection that sends `Last-Event-ID` (as `EventSource` does when it reconnects) gets the steps again but only the log lines after that id. While nothing happens, the stream sends a `: keepalive` comment every 15 seconds.", "tags": [ "deployments" ], "operationId": "stream-deployment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "deploymentId", "in": "path" } ], "responses": { "200": { "description": "The event stream." }, "404": { "description": "No such deployment in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/environments/{environmentId}": { "get": { "summary": "Get an environment", "description": "The environment, its current deployment (`activeDeploymentId`) and its variables. A secret variable never carries its `value`. `suspendedReason` is `inactive` or `hibernated` when the environment was paused for inactivity.", "tags": [ "environments" ], "operationId": "get-environment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "responses": { "200": { "description": "The environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] }, "example": { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "production", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-production", "activeDeploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [ { "key": "PUBLIC_API_URL", "secret": false, "value": "https://api.acme.dev", "note": null, "updatedAt": "2026-10-01T09:20:00.000Z" }, { "key": "STRIPE_SECRET_KEY", "secret": true, "note": "Live key", "updatedAt": "2026-10-01T09:20:00.000Z" } ], "createdAt": "2026-10-01T09:12:44.000Z" } } } }, "404": { "description": "No such environment in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "patch": { "summary": "Rename an environment", "description": "Changes the name only: the environment keeps its id, deployments, domains and variables.", "tags": [ "environments" ], "operationId": "rename-environment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 19, "pattern": "^[a-z0-9-]+$" } }, "required": [ "name" ] }, "example": { "name": "preview" } } } }, "responses": { "200": { "description": "The updated environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] }, "example": { "id": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "preview", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-staging", "activeDeploymentId": null, "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [], "createdAt": "2026-10-02T14:03:10.000Z" } } } }, "404": { "description": "No such environment in this workspace." }, "409": { "description": "The project already has an environment with that name." } }, "x-hiraiship-permission": "project.update", "x-hiraiship-role": "developer" }, "delete": { "summary": "Delete an environment", "description": "Takes the environment offline and deletes its domains, environment variables and queued builds. A project's production environment can't be deleted: delete the project instead.", "tags": [ "environments" ], "operationId": "delete-environment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "responses": { "204": { "description": "Deleted." }, "404": { "description": "No such environment in this workspace." }, "409": { "description": "It's the project's production environment (`code: production_environment`)." } }, "x-hiraiship-permission": "project.update", "x-hiraiship-role": "developer" } }, "/api/v1/environments/{environmentId}/active-deployment": { "patch": { "summary": "Roll back", "description": "Makes an earlier successful deployment of the environment its current one again, without a build. The next deployment that succeeds becomes current as usual. Your plan keeps a limited number of recent successful deployments available for rollback.", "tags": [ "deployments" ], "operationId": "rollback", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deploymentId": { "type": "string", "format": "uuid" } }, "required": [ "deploymentId" ] }, "example": { "deploymentId": "b1c3e5a7-9d2f-4b6a-8c4e-1f3a5b7d9c64" } } } }, "responses": { "200": { "description": "The environment, with its new `activeDeploymentId`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] }, "example": { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "production", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-production", "activeDeploymentId": "b1c3e5a7-9d2f-4b6a-8c4e-1f3a5b7d9c64", "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [ { "key": "PUBLIC_API_URL", "secret": false, "value": "https://api.acme.dev", "note": null, "updatedAt": "2026-10-01T09:20:00.000Z" }, { "key": "STRIPE_SECRET_KEY", "secret": true, "note": "Live key", "updatedAt": "2026-10-01T09:20:00.000Z" } ], "createdAt": "2026-10-01T09:12:44.000Z" } } } }, "402": { "description": "The environment is paused and every live environment your plan includes is in use (`quota: active_environments`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] } } } }, "404": { "description": "No such environment in this workspace, or the deployment is not one of its own." }, "409": { "description": "The deployment did not succeed, or is older than what your plan keeps for rollback." } }, "x-hiraiship-permission": "deployment.create", "x-hiraiship-role": "developer" } }, "/api/v1/environments/{environmentId}/deployments": { "get": { "summary": "List an environment's deployments", "description": "Most recent first.", "tags": [ "deployments" ], "operationId": "list-environment-deployments", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "responses": { "200": { "description": "The environment's deployments.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] } }, "example": [ { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": "sha256:5f1c9e0b7a2d4c6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e", "assetsManifestRef": "sha256:0a2c4e6f8b1d3f5a7c9e1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a", "status": "success", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": "https://acme-site.hiraiship.app", "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:41:19.000Z", "dispatchStatus": "live", "dispatchError": null, "publishStartedAt": "2026-10-03T16:41:12.000Z", "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null } ] } } }, "404": { "description": "No such environment in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "post": { "summary": "Create a deployment", "description": "Builds and deploys your source to the environment. Send the source as `sourceTarballBase64`, a gzipped tar of the project directory, base64-encoded (a single top-level directory is unwrapped); this is what `hiraiship deploy` does. Or send `installationId`/`owner`/`repo`/`ref` to build a GitHub repository the workspace's GitHub App can read: `ref` (a branch, tag or commit) is resolved to its commit when you call, and that commit is what gets built, recorded as `gitSha` with its message and author. `installCommand`, `buildCommand`, `outputDir` and `machine` override the project's build settings for this deployment only. The build runs asynchronously: follow it with the stream or the steps route. `status` is `pending` while it builds, `queued` while it waits for a free build slot or a free build machine (`queueReason` says which), then `success` or `failed`; on success it becomes the environment's current deployment. The body is at most 40 MB.", "tags": [ "deployments" ], "operationId": "create-deployment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "environmentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "sourceTarballBase64": { "type": "string", "minLength": 1 }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "gitSha": { "type": "string", "minLength": 1 }, "commitMessage": { "type": "string", "minLength": 1 }, "repoUrl": { "type": "string", "minLength": 1 }, "installCommand": { "type": "string", "minLength": 1 }, "buildCommand": { "type": "string", "minLength": 1 }, "outputDir": { "type": "string", "minLength": 1, "maxLength": 500 }, "machine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "required": [ "sourceTarballBase64", "triggerSource" ], "additionalProperties": false }, { "type": "object", "properties": { "installationId": { "type": "string", "minLength": 1 }, "owner": { "type": "string", "minLength": 1 }, "repo": { "type": "string", "minLength": 1 }, "ref": { "type": "string", "minLength": 1 }, "triggerSource": { "type": "string", "enum": [ "cli" ] }, "installCommand": { "type": "string", "minLength": 1 }, "buildCommand": { "type": "string", "minLength": 1 }, "outputDir": { "type": "string", "minLength": 1, "maxLength": 500 }, "machine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "required": [ "installationId", "owner", "repo", "ref", "triggerSource" ], "additionalProperties": false } ] }, "example": { "sourceTarballBase64": "H4sIAAAAAAAAA+3OMQ6CQBCF4a…", "triggerSource": "cli", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "commitMessage": "Fix the pricing table" } } } }, "responses": { "202": { "description": "The build was accepted. The deployment is `pending`, or `queued` with its `queuePosition` and `queueReason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] }, "example": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": null, "assetsManifestRef": null, "status": "pending", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": null, "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": null, "dispatchStatus": "not_applicable", "dispatchError": null, "publishStartedAt": null, "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null } } } }, "400": { "description": "The body matches none of the shapes, or mixes fields from several; or (GitHub source) the repository has no such `ref` (`code: unknown_ref`)." }, "402": { "description": "A plan limit refused the build: build minutes, live environments, a full build queue (`queued_builds`), a build machine your plan doesn't allow (`build_machine`), or the spend limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] }, "example": { "outcome": "quota_exceeded", "code": "quota_exceeded", "quota": "queued_builds", "limit": 10, "used": 10, "planId": "standard", "error": "Your Standard plan runs 2 builds at a time and lets 10 wait — 10 already are. Wait for one to finish, or upgrade your plan." } } } }, "403": { "description": "The project was disabled by Hiraiship (`code: project_disabled`)." }, "404": { "description": "No such environment in this workspace, or (GitHub source) no such installation." }, "413": { "description": "The body is larger than 40 MB (`code: payload_too_large`)." }, "501": { "description": "(GitHub source) GitHub builds are not configured on this Hiraiship instance." } }, "x-hiraiship-permission": "deployment.create", "x-hiraiship-role": "developer" } }, "/api/v1/projects": { "get": { "summary": "List projects", "description": "The workspace's projects, most recently created first, each with its default domain and its latest deployment (`null` for a project never deployed). `search` matches the name or the slug. `limit` is 20 by default, 50 at most; pass `nextCursor` back as `cursor` for the next page, until it is `null`.", "tags": [ "projects" ], "operationId": "list-projects", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of projects.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" }, "defaultDomain": { "type": [ "string", "null" ] }, "latestDeployment": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "workerScriptRef": { "type": [ "string", "null" ] }, "assetsManifestRef": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "pending", "success", "failed" ] }, "triggerSource": { "type": "string", "enum": [ "cli", "upload" ] }, "triggeredByUserId": { "type": "string" }, "gitSha": { "type": [ "string", "null" ] }, "gitRef": { "type": [ "string", "null" ] }, "framework": { "type": [ "string", "null" ], "enum": [ "rasengan", "futon", "hono", "vite", "static" ] }, "commitMessage": { "type": [ "string", "null" ] }, "commitAuthor": { "type": [ "string", "null" ] }, "repoUrl": { "type": [ "string", "null" ] }, "deployedUrl": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "dispatchStatus": { "type": "string", "enum": [ "not_applicable", "pending", "live", "error" ] }, "dispatchError": { "type": [ "string", "null" ] }, "publishStartedAt": { "type": [ "string", "null" ] }, "publishPlanned": { "type": "boolean" }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "startedAt": { "type": [ "string", "null" ] }, "queuePosition": { "type": [ "integer", "null" ] }, "queueReason": { "type": [ "string", "null" ], "enum": [ "plan_limit", "capacity" ] } }, "required": [ "id", "environmentId", "workerScriptRef", "assetsManifestRef", "status", "triggerSource", "triggeredByUserId", "gitSha", "gitRef", "framework", "commitMessage", "commitAuthor", "repoUrl", "deployedUrl", "error", "createdAt", "finishedAt", "dispatchStatus", "dispatchError", "publishStartedAt", "buildMachine", "startedAt", "queueReason" ] } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt", "defaultDomain", "latestDeployment" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ] }, "example": { "items": [ { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": null, "outputDir": null, "rootDirectory": null, "buildMachine": null, "createdAt": "2026-10-01T09:12:44.000Z", "defaultDomain": "acme-site.hiraiship.app", "latestDeployment": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "workerScriptRef": "sha256:5f1c9e0b7a2d4c6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e", "assetsManifestRef": "sha256:0a2c4e6f8b1d3f5a7c9e1b3d5f7a9c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a", "status": "success", "triggerSource": "cli", "triggeredByUserId": "apikey:8f9a1b2c-3d4e-4f5a-b6c7-d8e9f0a1b297", "gitSha": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", "gitRef": "main", "framework": "vite", "commitMessage": "Fix the pricing table", "commitAuthor": "acme-dev", "repoUrl": "https://github.com/acme/site", "deployedUrl": "https://acme-site.hiraiship.app", "error": null, "createdAt": "2026-10-03T16:40:02.000Z", "finishedAt": "2026-10-03T16:41:19.000Z", "dispatchStatus": "live", "dispatchError": null, "publishStartedAt": "2026-10-03T16:41:12.000Z", "publishPlanned": true, "buildMachine": "standard-1", "startedAt": "2026-10-03T16:40:02.000Z", "queuePosition": null, "queueReason": null } } ], "nextCursor": null } } } }, "400": { "description": "The `cursor` is not one this route returned." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "post": { "summary": "Create a project", "description": "Creates the project with its `production` environment and its default domain, `.hiraiship.app`. Nothing is deployed yet: start a deployment on the returned environment. The slug is unique across Hiraiship and can never change.", "tags": [ "projects" ], "operationId": "create-project", "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" }, "rootDirectory": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "name", "slug" ] }, "example": { "name": "Acme site", "slug": "acme-site" } } } }, "responses": { "201": { "description": "The project, its production environment and its default domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt" ] }, "environment": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] }, "domain": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "hostname": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "cloudflareHostnameId": { "type": [ "string", "null" ] }, "cloudflareVerification": { "type": [ "object", "null" ], "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "ALIAS", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "ownership", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "records", "errors" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "redirectToDomainId": { "type": [ "string", "null" ] }, "redirectStatusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "environmentId", "hostname", "isDefault", "status", "cloudflareHostnameId", "cloudflareVerification", "lastCheckedAt", "redirectToDomainId", "redirectStatusCode", "createdAt" ] } }, "required": [ "project", "environment", "domain" ] }, "example": { "project": { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": null, "outputDir": null, "rootDirectory": null, "buildMachine": null, "createdAt": "2026-10-01T09:12:44.000Z" }, "environment": { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "production", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-production", "activeDeploymentId": null, "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [], "createdAt": "2026-10-01T09:12:44.000Z" }, "domain": { "id": "5d7f9b1c-3e5a-4c7d-9f1b-2a4c6e8d0f75", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "hostname": "acme-site.hiraiship.app", "isDefault": true, "status": "active", "cloudflareHostnameId": null, "cloudflareVerification": null, "lastCheckedAt": null, "redirectToDomainId": null, "redirectStatusCode": null, "createdAt": "2026-10-01T09:12:44.000Z" } } } } }, "400": { "description": "The name is empty; the slug has characters other than lowercase letters, digits and hyphens, is longer than 63 characters, starts or ends with a hyphen, or is reserved (`www`, `api`, `app`, `admin`, …); or `rootDirectory` could leave the repository." }, "409": { "description": "That slug is taken: by a project, or by one deleted less than 30 days ago in another workspace." }, "429": { "description": "Too many projects created in the last hour for your plan. Retry after the `Retry-After` header's seconds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "rate_limited" ] }, "code": { "type": "string", "enum": [ "rate_limited" ] }, "limit": { "type": "number" }, "windowSeconds": { "type": "number" }, "retryAfterSeconds": { "type": "number" }, "error": { "type": "string" } }, "required": [ "outcome", "code", "limit", "windowSeconds", "retryAfterSeconds", "error" ] }, "example": { "outcome": "rate_limited", "code": "rate_limited", "limit": 30, "windowSeconds": 3600, "retryAfterSeconds": 412, "error": "You've created 30 projects in the last hour. Try again in 7 minutes." } } } } }, "x-hiraiship-permission": "project.create", "x-hiraiship-role": "developer" } }, "/api/v1/projects/by-slug/{slug}": { "get": { "summary": "Get a project by slug", "description": "The project and its `production` environment, found by slug instead of id.", "tags": [ "projects" ], "operationId": "get-project-by-slug", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "The project and its production environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt" ] }, "environment": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] } }, "required": [ "project", "environment" ] }, "example": { "project": { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": null, "outputDir": null, "rootDirectory": null, "buildMachine": null, "createdAt": "2026-10-01T09:12:44.000Z" }, "environment": { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "production", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-production", "activeDeploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [ { "key": "PUBLIC_API_URL", "secret": false, "value": "https://api.acme.dev", "note": null, "updatedAt": "2026-10-01T09:20:00.000Z" }, { "key": "STRIPE_SECRET_KEY", "secret": true, "note": "Live key", "updatedAt": "2026-10-01T09:20:00.000Z" } ], "createdAt": "2026-10-01T09:12:44.000Z" } } } } }, "404": { "description": "No project with that slug in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/projects/{projectId}": { "get": { "summary": "Get a project", "tags": [ "projects" ], "operationId": "get-project", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt" ] }, "example": { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": null, "outputDir": null, "rootDirectory": null, "buildMachine": null, "createdAt": "2026-10-01T09:12:44.000Z" } } } }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "patch": { "summary": "Rename a project", "description": "Changes the project's display name. The slug, and with it the default hostname, never changes.", "tags": [ "projects" ], "operationId": "rename-project", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Acme marketing site" } } } }, "responses": { "200": { "description": "The renamed project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt" ] }, "example": { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme marketing site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": null, "outputDir": null, "rootDirectory": null, "buildMachine": null, "createdAt": "2026-10-01T09:12:44.000Z" } } } }, "400": { "description": "An empty name, one over 64 characters, or a body with any other field (the slug can't be changed)." }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "project.update", "x-hiraiship-role": "developer" }, "delete": { "summary": "Delete a project", "description": "Takes every environment of the project offline and deletes its domains, environment variables and queued builds. `confirm` must be the project's slug. This can't be undone; the slug can be used by a new project afterwards. Usage already recorded this month stays on the workspace's bill.", "tags": [ "projects" ], "operationId": "delete-project", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true, "name": "confirm", "in": "query" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "`confirm` isn't the project's slug (`code: confirmation_mismatch`)." }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "project.delete", "x-hiraiship-role": "admin" } }, "/api/v1/projects/{projectId}/build-settings": { "patch": { "summary": "Update build settings", "description": "The install command, build command, output directory and build machine every future deployment of the project uses, unless the deployment sets its own. An omitted field is left unchanged; `null` goes back to the framework's default (the plan's default machine for `buildMachine`). `rootDirectory` is the app's directory in its GitHub repository, for a monorepo (`apps/web`; `null` or `.` for the root): the framework, the build command and the output directory are relative to it, and dependencies are installed where the nearest lockfile is. A deployment from the CLI builds the directory it was run in instead. Deployments already made are not rebuilt.", "tags": [ "projects" ], "operationId": "update-build-settings", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "installCommand": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "buildCommand": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "outputDir": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "rootDirectory": { "type": [ "string", "null" ], "maxLength": 1000 }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } } }, "example": { "buildCommand": "pnpm build", "outputDir": "dist", "rootDirectory": "apps/web", "buildMachine": "standard-2" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productionEnvironmentId": { "type": "string" }, "installCommand": { "type": [ "string", "null" ] }, "buildCommand": { "type": [ "string", "null" ] }, "outputDir": { "type": [ "string", "null" ] }, "rootDirectory": { "type": [ "string", "null" ] }, "buildMachine": { "type": [ "string", "null" ], "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "slug", "productionEnvironmentId", "installCommand", "buildCommand", "outputDir", "rootDirectory", "buildMachine", "createdAt" ] }, "example": { "id": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "workspaceId": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme site", "slug": "acme-site", "productionEnvironmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "installCommand": null, "buildCommand": "pnpm build", "outputDir": "dist", "rootDirectory": "apps/web", "buildMachine": "standard-2", "createdAt": "2026-10-01T09:12:44.000Z" } } } }, "400": { "description": "`rootDirectory` is absolute, contains `..` or a backslash, or is over 255 characters." }, "402": { "description": "Your plan does not allow that build machine (`quota: build_machine`), or a spend limit of $0 allows only the default one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] } } } }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "project.update", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/domains": { "get": { "summary": "List domains", "description": "Every domain of the project, default ones included, with the environment it serves or the domain it redirects to. A custom domain that is not `active` yet carries the DNS records to create (`dnsRecords`) and what is still wrong (`verificationErrors`).", "tags": [ "domains" ], "operationId": "list-domains", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "The project's environments and domains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "hostname": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "cloudflareHostnameId": { "type": [ "string", "null" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "environmentName": { "type": "string" }, "redirect": { "type": [ "object", "null" ], "properties": { "toDomainId": { "type": "string" }, "toHostname": { "type": "string" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "toDomainId", "toHostname", "statusCode" ] }, "dnsRecords": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "ALIAS", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "ownership", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "verificationErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "environmentId", "hostname", "isDefault", "status", "cloudflareHostnameId", "lastCheckedAt", "createdAt", "environmentName", "redirect", "dnsRecords", "verificationErrors" ] } } }, "required": [ "environments", "domains" ] }, "example": { "environments": [ { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "name": "production" } ], "domains": [ { "id": "5d7f9b1c-3e5a-4c7d-9f1b-2a4c6e8d0f75", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "hostname": "acme-site.hiraiship.app", "isDefault": true, "status": "active", "lastCheckedAt": null, "createdAt": "2026-10-01T09:12:44.000Z", "cloudflareHostnameId": null, "environmentName": "production", "redirect": null, "dnsRecords": null, "verificationErrors": [] }, { "id": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "environmentName": "production", "hostname": "www.acme.dev", "isDefault": false, "status": "pending", "cloudflareHostnameId": "0b9f6a1e-2c3d-4e5f-8a7b-6c5d4e3f2a1b", "lastCheckedAt": "2026-10-03T10:02:11.000Z", "createdAt": "2026-10-03T10:02:10.000Z", "redirect": null, "dnsRecords": [ { "type": "CNAME", "name": "www.acme.dev", "value": "acme-site.hiraiship.app", "purpose": "routing" }, { "type": "TXT", "name": "_cf-custom-hostname.www.acme.dev", "value": "6f0c2b1a-9e8d-4c7b-a6f5-e4d3c2b1a090", "purpose": "ownership" } ], "verificationErrors": [] } ] } } } }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "post": { "summary": "Add a domain", "description": "Adds a custom domain that serves an environment (`target.kind: environment`) or redirects to another domain of the project (`target.kind: redirect`, with a 301, 302, 307 or 308). It starts `pending`: create the records in `dnsRecords` at your DNS provider, then call Refresh until it is `active`. HTTPS certificates are issued automatically.", "tags": [ "domains" ], "operationId": "create-domain", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "maxLength": 253, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "environment" ] }, "environmentId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "environmentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "redirect" ] }, "toDomainId": { "type": "string", "format": "uuid" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "kind", "toDomainId", "statusCode" ], "additionalProperties": false } ] } }, "required": [ "hostname", "target" ], "additionalProperties": false }, "example": { "hostname": "www.acme.dev", "target": { "kind": "environment", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31" } } } } }, "responses": { "201": { "description": "The created domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "hostname": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "cloudflareHostnameId": { "type": [ "string", "null" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "environmentName": { "type": "string" }, "redirect": { "type": [ "object", "null" ], "properties": { "toDomainId": { "type": "string" }, "toHostname": { "type": "string" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "toDomainId", "toHostname", "statusCode" ] }, "dnsRecords": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "ALIAS", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "ownership", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "verificationErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "environmentId", "hostname", "isDefault", "status", "cloudflareHostnameId", "lastCheckedAt", "createdAt", "environmentName", "redirect", "dnsRecords", "verificationErrors" ] }, "example": { "id": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "environmentName": "production", "hostname": "www.acme.dev", "isDefault": false, "status": "pending", "cloudflareHostnameId": "0b9f6a1e-2c3d-4e5f-8a7b-6c5d4e3f2a1b", "lastCheckedAt": "2026-10-03T10:02:11.000Z", "createdAt": "2026-10-03T10:02:10.000Z", "redirect": null, "dnsRecords": [ { "type": "CNAME", "name": "www.acme.dev", "value": "acme-site.hiraiship.app", "purpose": "routing" }, { "type": "TXT", "name": "_cf-custom-hostname.www.acme.dev", "value": "6f0c2b1a-9e8d-4c7b-a6f5-e4d3c2b1a090", "purpose": "ownership" } ], "verificationErrors": [] } } } }, "402": { "description": "Every custom domain your plan includes is in use (`quota: custom_domains`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] } } } }, "404": { "description": "No such project in this workspace." }, "409": { "description": "That hostname is already in use." }, "422": { "description": "The target is an environment or a domain of another project, or a redirect to a domain that itself redirects." } }, "x-hiraiship-permission": "domains.write", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/domains/{domainId}": { "patch": { "summary": "Update a domain", "description": "Changes its hostname, its target, or both. A new hostname goes back to `pending` and needs its DNS records; the old one keeps serving until the new one is registered. Domains redirecting to this one follow it to its new environment.", "tags": [ "domains" ], "operationId": "update-domain", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "domainId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "maxLength": 253, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "environment" ] }, "environmentId": { "type": "string", "format": "uuid" } }, "required": [ "kind", "environmentId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "redirect" ] }, "toDomainId": { "type": "string", "format": "uuid" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "kind", "toDomainId", "statusCode" ], "additionalProperties": false } ] } }, "additionalProperties": false }, "example": { "target": { "kind": "redirect", "toDomainId": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86", "statusCode": 308 } } } } }, "responses": { "200": { "description": "The updated domain.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "hostname": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "cloudflareHostnameId": { "type": [ "string", "null" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "environmentName": { "type": "string" }, "redirect": { "type": [ "object", "null" ], "properties": { "toDomainId": { "type": "string" }, "toHostname": { "type": "string" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "toDomainId", "toHostname", "statusCode" ] }, "dnsRecords": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "ALIAS", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "ownership", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "verificationErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "environmentId", "hostname", "isDefault", "status", "cloudflareHostnameId", "lastCheckedAt", "createdAt", "environmentName", "redirect", "dnsRecords", "verificationErrors" ] }, "example": { "id": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "environmentName": "production", "hostname": "www.acme.dev", "isDefault": false, "status": "pending", "cloudflareHostnameId": "0b9f6a1e-2c3d-4e5f-8a7b-6c5d4e3f2a1b", "lastCheckedAt": "2026-10-03T10:02:11.000Z", "createdAt": "2026-10-03T10:02:10.000Z", "redirect": null, "dnsRecords": [ { "type": "CNAME", "name": "www.acme.dev", "value": "acme-site.hiraiship.app", "purpose": "routing" }, { "type": "TXT", "name": "_cf-custom-hostname.www.acme.dev", "value": "6f0c2b1a-9e8d-4c7b-a6f5-e4d3c2b1a090", "purpose": "ownership" } ], "verificationErrors": [] } } } }, "400": { "description": "An environment's default domain can't be renamed, moved or redirected." }, "404": { "description": "No such project or domain in this workspace." }, "409": { "description": "That hostname is already in use." }, "422": { "description": "The target breaks a rule (see Add a domain)." }, "502": { "description": "The new hostname was refused; the domain keeps its old one." } }, "x-hiraiship-permission": "domains.write", "x-hiraiship-role": "developer" }, "delete": { "summary": "Delete a domain", "description": "The domain stops serving at once.", "tags": [ "domains" ], "operationId": "delete-domain", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Cannot delete an environment's default domain." }, "404": { "description": "Project or domain not found." }, "409": { "description": "Other domains redirect to this one." } }, "x-hiraiship-permission": "domains.write", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/domains/{domainId}/refresh": { "post": { "summary": "Refresh a domain", "description": "Checks the domain's DNS and certificate again and returns its new `status`. Calls closer than 10 seconds apart for the same domain return the last result without checking again.", "tags": [ "domains" ], "operationId": "refresh-domain", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "domainId", "in": "path" } ], "responses": { "200": { "description": "The domain, as of the check.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environmentId": { "type": "string" }, "hostname": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "active", "error" ] }, "cloudflareHostnameId": { "type": [ "string", "null" ] }, "lastCheckedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "environmentName": { "type": "string" }, "redirect": { "type": [ "object", "null" ], "properties": { "toDomainId": { "type": "string" }, "toHostname": { "type": "string" }, "statusCode": { "anyOf": [ { "type": "number", "enum": [ 301 ] }, { "type": "number", "enum": [ 302 ] }, { "type": "number", "enum": [ 307 ] }, { "type": "number", "enum": [ 308 ] } ] } }, "required": [ "toDomainId", "toHostname", "statusCode" ] }, "dnsRecords": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CNAME", "ALIAS", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "routing", "ownership", "certificate" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "verificationErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "environmentId", "hostname", "isDefault", "status", "cloudflareHostnameId", "lastCheckedAt", "createdAt", "environmentName", "redirect", "dnsRecords", "verificationErrors" ] }, "example": { "id": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86", "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "environmentName": "production", "hostname": "www.acme.dev", "isDefault": false, "status": "pending", "cloudflareHostnameId": "0b9f6a1e-2c3d-4e5f-8a7b-6c5d4e3f2a1b", "lastCheckedAt": "2026-10-03T10:02:11.000Z", "createdAt": "2026-10-03T10:02:10.000Z", "redirect": null, "dnsRecords": [ { "type": "CNAME", "name": "www.acme.dev", "value": "acme-site.hiraiship.app", "purpose": "routing" }, { "type": "TXT", "name": "_cf-custom-hostname.www.acme.dev", "value": "6f0c2b1a-9e8d-4c7b-a6f5-e4d3c2b1a090", "purpose": "ownership" } ], "verificationErrors": [] } } } }, "404": { "description": "No such project or domain in this workspace." } }, "x-hiraiship-permission": "domains.write", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/environments": { "get": { "summary": "List a project's environments", "description": "Oldest first, so the production environment (the project's `productionEnvironmentId`) comes first. Variables aren't included: get an environment for them.", "tags": [ "environments" ], "operationId": "list-environments", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "The environments.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "createdAt" ] } }, "example": [ { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "production", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-production", "activeDeploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53", "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "createdAt": "2026-10-01T09:12:44.000Z" }, { "id": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "staging", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-staging", "activeDeploymentId": null, "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "createdAt": "2026-10-02T14:03:10.000Z" } ] } } }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "post": { "summary": "Create an environment", "description": "Adds an environment, such as `staging`, next to the project's `production` one. It has no deployment and no domain until you deploy to it.", "tags": [ "environments" ], "operationId": "create-environment", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 19, "pattern": "^[a-z0-9-]+$" } }, "required": [ "name" ] }, "example": { "name": "staging" } } } }, "responses": { "201": { "description": "The created environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "workerName": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "inactive", "hibernated" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "neverHibernate": { "type": "boolean" }, "variables": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ false ] }, "value": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "value", "note", "updatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean", "enum": [ true ] }, "note": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "key", "secret", "note", "updatedAt" ], "additionalProperties": false } ] } }, "createdAt": { "type": "string" } }, "required": [ "id", "projectId", "name", "workerName", "activeDeploymentId", "suspendedReason", "suspendedAt", "neverHibernate", "variables", "createdAt" ] }, "example": { "id": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "projectId": "3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20", "name": "staging", "workerName": "tenant-3f6d2b8a-1c4e-4f7a-8b2d-9e5c1a7f3b20-staging", "activeDeploymentId": null, "suspendedReason": null, "suspendedAt": null, "neverHibernate": false, "variables": [], "createdAt": "2026-10-02T14:03:10.000Z" } } } }, "402": { "description": "The project already has as many environments as your plan allows (`quota: environments`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "quota_exceeded" ] }, "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "quota": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "limit": { "type": "number" }, "used": { "type": "number" }, "planId": { "type": "string" }, "buildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "allowedBuildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "error": { "type": "string" } }, "required": [ "outcome", "code", "quota", "limit", "used", "planId", "error" ] } } } }, "404": { "description": "No such project in this workspace." }, "409": { "description": "The project already has an environment with that name." } }, "x-hiraiship-permission": "project.update", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/variables": { "get": { "summary": "List variables", "description": "One entry per key, with its value in each of the project's environments. A secret's value is never returned, by this route or any other; `sameValue` says whether every environment holds the same one. `value` at the top level is set when `sameValue` is true and the variable is not secret.", "tags": [ "variables" ], "operationId": "list-variables", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "responses": { "200": { "description": "The project's environments and variables.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "activeDeploymentId": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "activeDeploymentId" ] } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "sameValue": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string" }, "secret": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "environmentId", "secret", "updatedAt" ] } } }, "required": [ "key", "secret", "note", "sameValue", "updatedAt", "environments" ] } } }, "required": [ "environments", "variables" ] }, "example": { "environments": [ { "id": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "name": "production", "activeDeploymentId": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e53" }, { "id": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "name": "staging", "activeDeploymentId": null } ], "variables": [ { "key": "PUBLIC_API_URL", "secret": false, "note": null, "sameValue": false, "updatedAt": "2026-10-02T14:05:00.000Z", "environments": [ { "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "secret": false, "value": "https://api.acme.dev", "updatedAt": "2026-10-01T09:20:00.000Z" }, { "environmentId": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "secret": false, "value": "https://staging-api.acme.dev", "updatedAt": "2026-10-02T14:05:00.000Z" } ] }, { "key": "STRIPE_SECRET_KEY", "secret": true, "note": "Live key", "sameValue": true, "updatedAt": "2026-10-01T09:20:00.000Z", "environments": [ { "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "secret": true, "updatedAt": "2026-10-01T09:20:00.000Z" } ] } ] } } } }, "404": { "description": "No such project in this workspace." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" }, "post": { "summary": "Create variables", "description": "Sets up to 100 variables, with the same values, in each of `environmentIds`. Values are encrypted at rest. All or nothing: if a key already exists in one of the environments, nothing is written and the 409 lists every conflict. A running deployment reads new values only once redeployed.", "tags": [ "variables" ], "operationId": "create-variables", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "boolean" }, "environmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "value": { "type": "string", "maxLength": 4096 }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "key", "value" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "secret", "environmentIds", "variables" ], "additionalProperties": false }, "example": { "secret": true, "environmentIds": [ "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31" ], "variables": [ { "key": "STRIPE_SECRET_KEY", "value": "sk_live_…", "note": "Live key" } ] } } } }, "responses": { "201": { "description": "The created variables.", "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "sameValue": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string" }, "secret": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "environmentId", "secret", "updatedAt" ] } } }, "required": [ "key", "secret", "note", "sameValue", "updatedAt", "environments" ] } } }, "required": [ "variables" ] }, "example": { "variables": [ { "key": "STRIPE_SECRET_KEY", "secret": true, "note": "Live key", "sameValue": true, "updatedAt": "2026-10-01T09:20:00.000Z", "environments": [ { "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "secret": true, "updatedAt": "2026-10-01T09:20:00.000Z" } ] } ] } } } }, "404": { "description": "No such project in this workspace." }, "409": { "description": "Some keys already exist in the chosen environments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "environments" ] } } }, "required": [ "error", "conflicts" ] } } } }, "422": { "description": "An environment of another project, the same key twice, or more than an environment's 100 variables." } }, "x-hiraiship-permission": "variables.write", "x-hiraiship-role": "developer" } }, "/api/v1/projects/{projectId}/variables/{key}": { "patch": { "summary": "Update a variable", "description": "Every field is optional. `key` renames it, `secret: true` hides its values from now on, and `environments` is the full set of environments the variable is kept in: one left out loses it, one with no `value` keeps its own, and an added one with no `value` takes the value the others share (when they differ, it needs one). A secret can never become a plain variable again.", "tags": [ "variables" ], "operationId": "update-variable", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "required": true, "name": "key", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "secret": { "type": "boolean" }, "note": { "type": [ "string", "null" ], "maxLength": 500 }, "environments": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string", "format": "uuid" }, "value": { "type": "string", "maxLength": 4096 } }, "required": [ "environmentId" ], "additionalProperties": false }, "minItems": 1 } }, "additionalProperties": false }, "example": { "environments": [ { "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "value": "https://api.acme.dev" }, { "environmentId": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "value": "https://staging-api.acme.dev" } ] } } } }, "responses": { "200": { "description": "The variable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "secret": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "sameValue": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string" }, "secret": { "type": "boolean" }, "value": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "environmentId", "secret", "updatedAt" ] } } }, "required": [ "key", "secret", "note", "sameValue", "updatedAt", "environments" ] }, "example": { "key": "PUBLIC_API_URL", "secret": false, "note": null, "sameValue": false, "updatedAt": "2026-10-02T14:05:00.000Z", "environments": [ { "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31", "secret": false, "value": "https://api.acme.dev", "updatedAt": "2026-10-01T09:20:00.000Z" }, { "environmentId": "4e8c2a6f-7b1d-4c9e-a3f5-6b2d8e1c7a42", "secret": false, "value": "https://staging-api.acme.dev", "updatedAt": "2026-10-02T14:05:00.000Z" } ] } } } }, "404": { "description": "No such project in this workspace, or no variable with that key." }, "409": { "description": "The new key already exists in one of the environments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "environments" ] } } }, "required": [ "error", "conflicts" ] } } } }, "422": { "description": "A secret turned back into a plain variable, an environment of another project, an added environment with no `value` while the others differ, or more than 100 variables in one environment." } }, "x-hiraiship-permission": "variables.write", "x-hiraiship-role": "developer" }, "delete": { "summary": "Delete a variable", "description": "Removes the key from every environment of the project.", "tags": [ "variables" ], "operationId": "delete-variable", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "required": true, "name": "key", "in": "path" } ], "responses": { "204": { "description": "Deleted." }, "404": { "description": "Project not found, or no variable with that key." } }, "x-hiraiship-permission": "variables.write", "x-hiraiship-role": "developer" } }, "/api/v1/workspace/me": { "get": { "summary": "Get the workspace", "description": "The API key's workspace: its name, slug, plan, spend limit, and `suspendedReason` when a quota or the spend limit suspended it.", "tags": [ "workspace" ], "operationId": "get-workspace", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "ownerUserId": { "type": "string" }, "planId": { "type": "string" }, "spendLimitUsd": { "type": [ "number", "null" ] }, "suspendedReason": { "type": [ "string", "null" ], "enum": [ "request_quota", "spend_limit" ] }, "suspendedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "slug", "ownerUserId", "planId", "spendLimitUsd", "suspendedReason", "suspendedAt", "createdAt" ] }, "example": { "id": "7c0e5a9e-2f4b-4d6a-9b1e-3a8f2c6d1e40", "name": "Acme Labs", "slug": "acme", "ownerUserId": "Xc2kP9vQm4LrT7wZ", "planId": "standard", "spendLimitUsd": 50, "suspendedReason": null, "suspendedAt": null, "createdAt": "2026-09-12T08:00:00.000Z" } } } }, "401": { "description": "No valid API key." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } }, "/api/v1/workspace/usage": { "get": { "summary": "Get usage", "description": "The workspace's plan and this billing period's usage: `quotas` lists every included amount with what is used, and on a paid plan `overageUsd` is what that metric adds to the bill. `requestsThisPeriod` and `cpuTimeMsThisPeriod` are `null` until usage has been measured once, which is not the same as zero.", "tags": [ "workspace" ], "operationId": "get-usage", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The plan and this period's usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "priceUsdMonthly": { "type": "number" }, "activeEnvironmentsIncluded": { "type": "number" }, "environmentsPerProject": { "type": "number" }, "buildMinutesIncluded": { "type": "number" }, "defaultBuildMachine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "buildMachines": { "type": "array", "items": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] } }, "buildMachinePricesUsd": { "type": "object", "properties": { "standard-1": { "type": "number" }, "standard-2": { "type": "number" }, "standard-3": { "type": "number" }, "standard-4": { "type": "number" } } }, "requestsIncluded": { "type": "number" }, "cpuTimeIncludedMs": { "type": [ "number", "null" ] }, "customDomainsIncluded": { "type": "number" }, "seatsIncluded": { "type": "number" }, "seatsMax": { "type": [ "number", "null" ] }, "deploymentsPerDay": { "type": [ "number", "null" ] }, "projectsCreatedPerHour": { "type": "number" }, "maxConcurrentBuilds": { "type": "number" }, "maxQueuedBuilds": { "type": "number" }, "buildTimeoutMs": { "type": "number" }, "cpuMsPerRequest": { "type": "number" }, "subRequestsPerRequest": { "type": "number" }, "retainedDeployments": { "type": "number" }, "billsAssetRequests": { "type": "boolean" }, "pauseAfterInactiveDays": { "type": [ "number", "null" ] }, "hibernateAfterInactiveDays": { "type": [ "number", "null" ] }, "overage": { "type": [ "object", "null" ], "properties": { "requestsPerMillionUsd": { "type": "number" }, "cpuPerMillionMsUsd": { "type": "number" }, "customDomainMonthlyUsd": { "type": "number" }, "activeEnvironmentMonthlyUsd": { "type": "number" }, "seatMonthlyUsd": { "type": [ "number", "null" ] } }, "required": [ "requestsPerMillionUsd", "cpuPerMillionMsUsd", "customDomainMonthlyUsd", "activeEnvironmentMonthlyUsd", "seatMonthlyUsd" ] }, "defaultSpendLimitUsd": { "type": [ "number", "null" ] }, "maxSpendLimitUsd": { "type": [ "number", "null" ] }, "features": { "type": "array", "items": { "type": "string", "enum": [ "sso", "audit_log", "sla", "priority_support" ] } }, "platformDomainsIncluded": { "type": "number" } }, "required": [ "id", "name", "priceUsdMonthly", "activeEnvironmentsIncluded", "environmentsPerProject", "buildMinutesIncluded", "defaultBuildMachine", "buildMachines", "buildMachinePricesUsd", "requestsIncluded", "cpuTimeIncludedMs", "customDomainsIncluded", "seatsIncluded", "seatsMax", "deploymentsPerDay", "projectsCreatedPerHour", "maxConcurrentBuilds", "maxQueuedBuilds", "buildTimeoutMs", "cpuMsPerRequest", "subRequestsPerRequest", "retainedDeployments", "billsAssetRequests", "pauseAfterInactiveDays", "hibernateAfterInactiveDays", "overage", "defaultSpendLimitUsd", "maxSpendLimitUsd", "features", "platformDomainsIncluded" ] }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, "projectCount": { "type": "number" }, "environmentCount": { "type": "number" }, "activeEnvironmentCount": { "type": "number" }, "deploymentCounts": { "type": "object", "properties": { "queued": { "type": "number" }, "pending": { "type": "number" }, "success": { "type": "number" }, "failed": { "type": "number" } }, "required": [ "queued", "pending", "success", "failed" ] }, "deploymentsThisPeriod": { "type": "number" }, "customDomainCount": { "type": "number" }, "buildMinutesThisPeriod": { "type": "number" }, "buildMinutesByMachine": { "type": "array", "items": { "type": "object", "properties": { "machine": { "type": "string", "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ] }, "minutes": { "type": "number" }, "included": { "type": "number" }, "priceUsdPerMinute": { "type": "number" }, "overageUsd": { "type": [ "number", "null" ] } }, "required": [ "machine", "minutes", "included", "priceUsdPerMinute", "overageUsd" ] } }, "requestsThisPeriod": { "type": [ "number", "null" ] }, "assetRequestsThisPeriod": { "type": [ "number", "null" ] }, "cpuTimeMsThisPeriod": { "type": [ "number", "null" ] }, "quotas": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "used": { "type": "number" }, "included": { "type": "number" }, "state": { "type": "string", "enum": [ "ok", "warning", "exceeded" ] }, "overageUsd": { "type": [ "number", "null" ] } }, "required": [ "key", "used", "included", "state", "overageUsd" ] } }, "estimatedBill": { "type": [ "object", "null" ], "properties": { "planUsd": { "type": "number" }, "overageUsd": { "type": "number" }, "totalUsd": { "type": "number" } }, "required": [ "planUsd", "overageUsd", "totalUsd" ] }, "spendLimit": { "type": [ "object", "null" ], "properties": { "limitUsd": { "type": "number" }, "usedUsd": { "type": "number" }, "maxUsd": { "type": "number" }, "isDefault": { "type": "boolean" }, "projectedReachAt": { "type": [ "string", "null" ] } }, "required": [ "limitUsd", "usedUsd", "maxUsd", "isDefault", "projectedReachAt" ] }, "cheaperPlan": { "type": [ "object", "null" ], "properties": { "planId": { "type": "string" }, "name": { "type": "string" }, "estimatedBillUsd": { "type": "number" } }, "required": [ "planId", "name", "estimatedBillUsd" ] }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "active_environments", "environments", "custom_domains", "build_minutes", "concurrent_builds", "queued_builds", "deployments_per_day", "requests", "cpu_time", "spend_limit", "free_tier_capacity", "seats", "build_machine" ] }, "threshold": { "anyOf": [ { "type": "number", "enum": [ 50 ] }, { "type": "number", "enum": [ 80 ] }, { "type": "number", "enum": [ 100 ] } ] }, "since": { "type": "string" } }, "required": [ "key", "threshold", "since" ] } }, "suspended": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "request_quota", "spend_limit", "inactive", "plan_limit", "hibernated" ] }, "since": { "type": "string" } }, "required": [ "reason", "since" ] } }, "required": [ "plan", "period", "projectCount", "environmentCount", "activeEnvironmentCount", "deploymentCounts", "deploymentsThisPeriod", "customDomainCount", "buildMinutesThisPeriod", "buildMinutesByMachine", "requestsThisPeriod", "assetRequestsThisPeriod", "cpuTimeMsThisPeriod", "quotas", "estimatedBill", "spendLimit", "cheaperPlan", "alerts", "suspended" ] } } } }, "401": { "description": "No valid API key." } }, "x-hiraiship-permission": "workspace.read", "x-hiraiship-role": "viewer" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hsk_…" } } } }