{ "openapi": "3.1.0", "info": { "title": "InstaCloud API — Organization level", "version": "0.1.0", "description": "Endpoints under `/orgs/{orgId}`: members, projects, billing, domains. Callable with an account-wide token or a token bound to that organization.\n\nGenerated from the platform's own OpenAPI document (https://api.instacloud.com/openapi.json); see the [API overview](/reference/api/overview) for authentication and token scopes." }, "servers": [ { "url": "https://api.instacloud.com", "description": "InstaCloud" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Organization", "description": "The organization itself: name, members, invitations." }, { "name": "Projects", "description": "Projects inside an organization." }, { "name": "Audit", "description": "The project's event timeline, including agent-ingested events." }, { "name": "Domains", "description": "Domains bought through InstaCloud, bring-your-own zones and their DNS records." }, { "name": "Billing", "description": "Usage, cycles, invoices and credits." }, { "name": "Templates", "description": "Deploy a template into a project." } ], "paths": { "/orgs/{orgId}": { "get": { "operationId": "getOrg", "summary": "Org detail + caller's role", "tags": [ "Organization" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "org": { "$ref": "#/components/schemas/Org" }, "role": { "$ref": "#/components/schemas/Role" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Org detail + caller's role", "sidebarTitle": "Get org" } } }, "patch": { "operationId": "renameOrg", "summary": "Rename org", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 100, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "org": { "$ref": "#/components/schemas/Org" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nRename an org (display name only; slug is frozen). Requires admin.", "x-mint": { "metadata": { "title": "Rename org", "sidebarTitle": "Rename org" } } } }, "/orgs/{orgId}/billing": { "get": { "operationId": "getBilling", "summary": "Current billing cycle summary (tier, included credit, used, overage, status)", "tags": [ "Billing" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummary" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "Current billing cycle summary (tier, included credit, used, overage, status)", "sidebarTitle": "Get billing" } } } }, "/orgs/{orgId}/billing/checkout": { "post": { "operationId": "createCheckout", "summary": "Create checkout", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tier" ], "type": "object", "properties": { "tier": { "type": "string", "enum": [ "pro", "team" ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "format": "uri", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing (Stripe) not configured" } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nOrg owner/admin only: start legacy subscription Checkout; UTC-managed tier changes require billing/plan-change", "x-mint": { "metadata": { "title": "Create checkout", "sidebarTitle": "Create checkout" } } } }, "/orgs/{orgId}/billing/credits/transactions": { "get": { "operationId": "listCreditTransactions", "summary": "List credit transactions", "tags": [ "Billing" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "before", "required": false, "description": "opaque cursor from a previous page's nextBefore" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditTransactions" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nCredit transaction history for an org — grants, spends and reversals, newest first (pure read)", "x-mint": { "metadata": { "title": "List credit transactions", "sidebarTitle": "List credit transactions" } } } }, "/orgs/{orgId}/billing/cycle": { "get": { "operationId": "getBillingCycle", "summary": "Get billing cycle", "tags": [ "Billing" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCycle" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nCurrent billing-cycle window (frontend uses it to compute from/to for overview/daily)", "x-mint": { "metadata": { "title": "Get billing cycle", "sidebarTitle": "Get billing cycle" } } } }, "/orgs/{orgId}/billing/invoices": { "get": { "operationId": "listBillingInvoices", "summary": "List the org's Stripe invoices (receipts) with links to their PDFs", "tags": [ "Billing" ], "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "before", "required": false, "description": "opaque cursor from a previous page's nextBefore" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInvoiceList" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing (Stripe) not configured" } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List the org's Stripe invoices (receipts) with links to their PDFs", "sidebarTitle": "List billing invoices" } } } }, "/orgs/{orgId}/billing/overview": { "get": { "operationId": "getBillingOverview", "summary": "Get billing overview", "tags": [ "Billing" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default current cycle start)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default current cycle end)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOverview" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nBilling overview for a window — totals, credits, forecast, per-dimension + per-project breakdown; applies due plan changes without accruing or charging usage", "x-mint": { "metadata": { "title": "Get billing overview", "sidebarTitle": "Get billing overview" } } } }, "/orgs/{orgId}/billing/plan-change": { "get": { "operationId": "getPlanChangeOptions", "summary": "Get plan change options", "tags": [ "Billing" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "canManage": { "type": "boolean" }, "pending": { "type": [ "object", "null" ], "properties": { "id": { "format": "uuid", "type": "string" }, "fromTier": { "type": "string" }, "toTier": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "awaiting_payment" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "applied" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "effectiveAt": { "format": "date-time", "type": "string" }, "includedUsd": { "type": "number" }, "changeKind": { "anyOf": [ { "type": "string", "enum": [ "upgrade" ] }, { "type": "string", "enum": [ "downgrade" ] } ] }, "renewalAt": { "format": "date-time", "type": "string" }, "cancellable": { "type": "boolean" }, "paymentUrl": { "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "fromTier", "toTier", "status", "effectiveAt", "includedUsd" ] }, "retryKey": { "type": [ "string", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "tier": { "anyOf": [ { "type": "string", "enum": [ "free" ] }, { "type": "string", "enum": [ "pro" ] }, { "type": "string", "enum": [ "team" ] } ] }, "feeCents": { "minimum": 0, "type": "integer" }, "currency": { "type": "string", "enum": [ "usd" ] }, "includedUsd": { "minimum": 0, "type": "number" }, "effectiveAt": { "format": "date-time", "type": "string" }, "renewalAt": { "format": "date-time", "type": "string" }, "renewalFeeCents": { "minimum": 0, "type": "integer" }, "changeKind": { "anyOf": [ { "type": "string", "enum": [ "upgrade" ] }, { "type": "string", "enum": [ "downgrade" ] } ] } }, "required": [ "tier", "feeCents", "currency", "includedUsd" ] } } }, "required": [ "enabled", "canManage", "pending", "retryKey", "options" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nRead paid-plan change availability, current subscription prices and an authorized pending retry", "x-mint": { "metadata": { "title": "Get plan change options", "sidebarTitle": "Get plan change options" } } }, "post": { "operationId": "requestPaidPlanChange", "summary": "Request paid plan change", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "anyOf": [ { "type": "string", "enum": [ "free" ] }, { "type": "string", "enum": [ "pro" ] }, { "type": "string", "enum": [ "team" ] } ] }, "idempotencyKey": { "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "expectedFeeCents": { "minimum": 0, "maximum": 9007199254740991, "description": "Required for Pro/Team: amount due now accepted from the options response, excluding tax; zero for a scheduled downgrade. Omit for Free.", "type": "integer" } }, "required": [ "tier", "idempotencyKey" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "fromTier": { "type": "string" }, "toTier": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "awaiting_payment" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "applied" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "effectiveAt": { "format": "date-time", "type": "string" }, "includedUsd": { "type": "number" }, "changeKind": { "anyOf": [ { "type": "string", "enum": [ "upgrade" ] }, { "type": "string", "enum": [ "downgrade" ] } ] }, "renewalAt": { "format": "date-time", "type": "string" }, "cancellable": { "type": "boolean" }, "paymentUrl": { "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "fromTier", "toTier", "status", "effectiveAt", "includedUsd" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nFree → paid takes effect once paid; Pro → Team next UTC day after payment; downgrade at the current paid period end (owner/admin)", "x-mint": { "metadata": { "title": "Request paid plan change", "sidebarTitle": "Request paid plan change" } } } }, "/orgs/{orgId}/billing/plan-change/{transitionId}/cancel": { "post": { "operationId": "cancelScheduledDowngrade", "summary": "Withdraw a scheduled downgrade before the paid period ends (owner/admin)", "tags": [ "Billing" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "transitionId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "fromTier": { "type": "string" }, "toTier": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "awaiting_payment" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "applied" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "cancelled" ] } ] }, "effectiveAt": { "format": "date-time", "type": "string" }, "includedUsd": { "type": "number" }, "changeKind": { "anyOf": [ { "type": "string", "enum": [ "upgrade" ] }, { "type": "string", "enum": [ "downgrade" ] } ] }, "renewalAt": { "format": "date-time", "type": "string" }, "cancellable": { "type": "boolean" }, "paymentUrl": { "format": "uri", "type": [ "string", "null" ] } }, "required": [ "id", "fromTier", "toTier", "status", "effectiveAt", "includedUsd" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Withdraw a scheduled downgrade before the paid period ends (owner/admin)", "sidebarTitle": "Cancel scheduled downgrade" } } } }, "/orgs/{orgId}/billing/portal": { "post": { "operationId": "createBillingPortal", "summary": "Create billing portal", "tags": [ "Billing" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "format": "uri", "type": "string" } } } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Billing (Stripe) not configured" } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nOrg owner/admin only: open the Stripe Customer Portal; UTC-managed plans allow payment management only", "x-mint": { "metadata": { "title": "Create billing portal", "sidebarTitle": "Create billing portal" } } } }, "/orgs/{orgId}/billing/redeem": { "post": { "operationId": "redeemCreditCode", "summary": "Redeem a credit code into this org", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code" ], "type": "object", "properties": { "code": { "minLength": 1, "maxLength": 128, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "amountMicros": { "type": "integer" }, "creditsExpireAt": { "type": [ "string", "null" ] }, "orgId": { "type": "string" }, "orgName": { "type": "string" } }, "required": [ "amountMicros", "creditsExpireAt", "orgId", "orgName" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Redeem a credit code into this org", "sidebarTitle": "Redeem credit code" } } } }, "/orgs/{orgId}/domains": { "get": { "operationId": "listOrgDomains", "summary": "List org domains", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchasedDomain" } } }, "required": [ "items" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nEvery domain the org bought through InstaCloud, including detached ones whose project or service is gone", "x-mint": { "metadata": { "title": "List org domains", "sidebarTitle": "List org domains" } } } }, "/orgs/{orgId}/domains/orders": { "get": { "operationId": "listOrgDomainOrders", "summary": "List org domain orders", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DomainOrder" } } }, "required": [ "items" ] } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nThe org's domain purchases, including those still awaiting payment and those bought without a service", "x-mint": { "metadata": { "title": "List org domain orders", "sidebarTitle": "List org domain orders" } } } }, "/orgs/{orgId}/domains/{domainName}": { "patch": { "operationId": "updatePurchasedDomain", "summary": "Update purchased domain", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "minProperties": 1, "type": "object", "properties": { "autorenew": { "description": "renew the domain each year before it expires", "type": "boolean" }, "locked": { "description": "the registrar transfer lock. Turn it off to move the domain to another registrar; the ICANN lock in `transferLockExpiresAt` still refuses a transfer until it passes", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasedDomain" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nTurn renewal or the transfer lock on or off for a domain this org bought. A field left out keeps its value. (admin+ for the lock)", "x-mint": { "metadata": { "title": "Update purchased domain", "sidebarTitle": "Update purchased domain" } } } }, "/orgs/{orgId}/domains/{domainName}/auth-code": { "post": { "operationId": "getDomainAuthCode", "summary": "Get domain auth code", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "authCode": { "description": "the EPP/authorization code the gaining registrar asks for", "type": "string" } }, "required": [ "authCode" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nThe transfer authorization code another registrar needs to pull this domain away. Unlocking is the separate PATCH; the code alone moves nothing. (admin+)", "x-mint": { "metadata": { "title": "Get domain auth code", "sidebarTitle": "Get domain auth code" } } } }, "/orgs/{orgId}/domains/{domainName}/delegate": { "post": { "operationId": "delegatePurchasedDomain", "summary": "Delegate purchased domain", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasedDomain" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "managed DNS delegation is not enabled on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nManaged delegation: host this domain's zone on an InstaCloud-managed Cloudflare zone and keep publishing its DNS there. Nothing goes dark — the zone carries every published record before the nameservers move — and attach keeps working, apexes included. Gated — domain.delegate. (admin+)", "x-mint": { "metadata": { "title": "Delegate purchased domain", "sidebarTitle": "Delegate purchased domain" } } } }, "/orgs/{orgId}/domains/{domainName}/nameservers": { "put": { "operationId": "setDomainNameservers", "summary": "Set domain nameservers", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nameservers": { "maxItems": 13, "description": "hostnames, in order; at least one", "type": "array", "items": { "type": "string" } } }, "required": [ "nameservers" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasedDomain" } } } }, "400": { "description": "the registrar refused them — with its own sentence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nDelegate the domain to other nameservers (Cloudflare, Route 53, your own). They must already host the zone — some registries check before accepting the change. EVERY hostname this domain serves goes down with the move, because the records an attach published live in the registrar's zone: the answer marks them `failed` and names why. While the domain is delegated, attaching a hostname is refused for the same reason. (admin+)", "x-mint": { "metadata": { "title": "Set domain nameservers", "sidebarTitle": "Set domain nameservers" } } }, "delete": { "operationId": "resetDomainNameservers", "summary": "Reset domain nameservers", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasedDomain" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nPoint the domain back at the registrar's own nameservers, which is where an attach publishes. Never refused for a hostname in the way: this is the repair. (admin+)", "x-mint": { "metadata": { "title": "Reset domain nameservers", "sidebarTitle": "Reset domain nameservers" } } } }, "/orgs/{orgId}/domains/{domainName}/records": { "get": { "operationId": "listDomainRecords", "summary": "List domain records", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } }, "required": [ "items" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nThe DNS records in a bought domain's zone, as the registrar holds them. A record InstaCloud published is `managed`: read-only while the attached hostname in `hostname` claims it; with no `hostname`, a leftover that may be deleted.", "x-mint": { "metadata": { "title": "List domain records", "sidebarTitle": "List domain records" } } }, "post": { "operationId": "createDomainRecord", "summary": "Create domain record", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "answer" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/DnsRecordType" }, "host": { "description": "relative to the domain: \"@\" for the domain itself, \"api\" for api.; the full hostname is accepted too", "type": "string" }, "answer": { "description": "an IPv4 (A) or IPv6 (AAAA) address; a hostname (CNAME, ANAME, NS, MX); \" \" (SRV); text (TXT). \".\" is the null MX and the no-service SRV target", "type": "string" }, "ttl": { "minimum": 300, "maximum": 604800, "description": "seconds", "type": "integer" }, "priority": { "minimum": 0, "maximum": 65535, "description": "required for MX and SRV, refused for every other type", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecord" } } } }, "400": { "description": "the record does not fit its type, the zone cannot hold it (a CNAME or NS at the domain itself), or the registrar refused it — with its own sentence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the host serves a compute service through InstaCloud, or an NS there would delegate one away", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nAdd a DNS record to a bought domain's zone. Omitted, `host` is the domain itself and `ttl` is 300 seconds. Routing (A, AAAA, ANAME, CNAME) and delegation (NS) are refused at a hostname an attach serves — those are the platform's — and an NS above one, which would delegate it away; attaching a hostname later replaces the routing records at that host.", "x-mint": { "metadata": { "title": "Create domain record", "sidebarTitle": "Create domain record" } } } }, "/orgs/{orgId}/domains/{domainName}/records/{recordId}": { "patch": { "operationId": "updateDomainRecord", "summary": "Update domain record", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "minProperties": 1, "type": "object", "properties": { "type": { "$ref": "#/components/schemas/DnsRecordType" }, "host": { "description": "relative to the domain: \"@\" for the domain itself, \"api\" for api.; the full hostname is accepted too", "type": "string" }, "answer": { "description": "an IPv4 (A) or IPv6 (AAAA) address; a hostname (CNAME, ANAME, NS, MX); \" \" (SRV); text (TXT). \".\" is the null MX and the no-service SRV target", "type": "string" }, "ttl": { "minimum": 300, "maximum": 604800, "description": "seconds", "type": "integer" }, "priority": { "minimum": 0, "maximum": 65535, "description": "required for MX and SRV, refused for every other type", "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true }, { "schema": { "pattern": "^[0-9]{1,18}$", "type": "string" }, "in": "path", "name": "recordId", "required": true, "description": "the id from the records list" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecord" } } } }, "400": { "description": "the merged record does not fit its type, the zone cannot hold it, or the registrar refused it — with its own sentence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the record is managed, or the host it moves to serves a compute service (for an NS: or has one beneath it)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nChange a DNS record; a field left out keeps its value. A managed record is refused.", "x-mint": { "metadata": { "title": "Update domain record", "sidebarTitle": "Update domain record" } } }, "delete": { "operationId": "deleteDomainRecord", "summary": "Delete domain record", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true }, { "schema": { "pattern": "^[0-9]{1,18}$", "type": "string" }, "in": "path", "name": "recordId", "required": true, "description": "the id from the records list" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "a hostname still claims the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nRemove a DNS record. One a hostname still claims is refused — it leaves the zone with that hostname; a managed record no hostname claims may go.", "x-mint": { "metadata": { "title": "Delete domain record", "sidebarTitle": "Delete domain record" } } } }, "/orgs/{orgId}/events/stream": { "get": { "operationId": "streamOrgEvents", "summary": "Live org progress stream (Server-Sent Events)", "tags": [ "Audit" ], "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nA long-lived `text/event-stream` for progress on org-scoped resources (purchased domains). Each `live` event (orgId, kind; no `id`) says something moved in the background: `domain.order.progress` — an order changed status, refetch the orders and the domain inventory; `domain.progress` — a domain's hostnames or status changed or its zone was published into, refetch the inventory, the orders and an open zone read. Nothing is replayed: after a reconnect, or on a `reset` event, refetch every view. The server ends each stream after a few minutes; reconnect.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Server-Sent Events: `live` and `reset` events", "content": { "text/event-stream": { "schema": { "type": "string" } } } } }, "x-mint": { "metadata": { "title": "Live org progress stream (Server-Sent Events)", "sidebarTitle": "Stream org events" } } } }, "/orgs/{orgId}/invitations": { "post": { "operationId": "createInvitation", "summary": "Invite a member by email (admin+)", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "role" ], "type": "object", "properties": { "email": { "format": "email", "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "admin" ] }, { "type": "string", "enum": [ "member" ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Invite a member by email (admin+)", "sidebarTitle": "Create invitation" } } }, "get": { "operationId": "listInvitations", "summary": "List pending invitations (admin+)", "tags": [ "Organization" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } } }, "required": [ "invitations" ] } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List pending invitations (admin+)", "sidebarTitle": "List invitations" } } } }, "/orgs/{orgId}/invitations/{invitationId}": { "delete": { "operationId": "revokeInvitation", "summary": "Revoke a pending invitation (admin+)", "tags": [ "Organization" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "invitationId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Revoke a pending invitation (admin+)", "sidebarTitle": "Revoke invitation" } } } }, "/orgs/{orgId}/members": { "get": { "operationId": "listMembers", "summary": "List members", "tags": [ "Organization" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "members" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List members", "sidebarTitle": "List members" } } } }, "/orgs/{orgId}/members/{userId}": { "put": { "operationId": "setMemberRole", "summary": "Change a member's role (admin+; only an owner may set/clear owner)", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role" ], "type": "object", "properties": { "role": { "$ref": "#/components/schemas/Role" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "minLength": 1, "maxLength": 128, "type": "string" }, "in": "path", "name": "userId", "required": true, "description": "Better Auth user id (opaque string, not a UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Change a member's role (admin+; only an owner may set/clear owner)", "sidebarTitle": "Set member role" } } }, "delete": { "operationId": "removeMember", "summary": "Remove a member (admin+, or self-leave); the last owner cannot be removed", "tags": [ "Organization" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "minLength": 1, "maxLength": 128, "type": "string" }, "in": "path", "name": "userId", "required": true, "description": "Better Auth user id (opaque string, not a UUID)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Remove a member (admin+, or self-leave); the last owner cannot be removed", "sidebarTitle": "Remove member" } } } }, "/orgs/{orgId}/projects": { "post": { "operationId": "createProject", "summary": "Create an empty project with its default `main` branch — add services afterwards", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionResult" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Create an empty project with its default `main` branch — add services afterwards", "sidebarTitle": "Create project" } } }, "get": { "operationId": "listProjects", "summary": "List projects in an org", "tags": [ "Projects" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } }, "required": [ "projects" ] } } } } }, "description": "**Token scope:** `account` · `org` · `project` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "List projects in an org", "sidebarTitle": "List projects" } } } }, "/orgs/{orgId}/templates": { "get": { "operationId": "listOrgTemplates", "summary": "This org's community templates, drafts and published", "tags": [ "Templates" ], "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nOne summary per template, with no services, variables or publish requirements. getOrgTemplate serves one template in full.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/CommunityTemplateSummary" } } }, "required": [ "templates" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "This user listed the templates too many times in the last minute. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mint": { "metadata": { "title": "This org's community templates, drafts and published", "sidebarTitle": "List org templates" } } }, "post": { "operationId": "createOrgTemplate", "summary": "Create org template", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The draft's name, trimmed, 1 to 80 characters. The template code is derived from it. Omitted: New template, with a random suffix on its code.", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The organization is billing-suspended, or the caller holds a project-scoped token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nCreate a blank community template draft, with no project behind it. Services are added with PATCH.", "x-mint": { "metadata": { "title": "Create org template", "sidebarTitle": "Create org template" } } } }, "/orgs/{orgId}/templates/{code}": { "get": { "operationId": "getOrgTemplate", "summary": "One community template of this org", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.", "x-mint": { "metadata": { "title": "One community template of this org", "sidebarTitle": "Get org template" } } }, "patch": { "operationId": "updateOrgTemplate", "summary": "Edit a community template draft", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Rename. Only before the first publish.", "type": "string" }, "name": { "minLength": 1, "maxLength": 80, "type": "string" }, "tagline": { "maxLength": 160, "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "readme": { "type": [ "string", "null" ] }, "logoUrl": { "description": "An https:// image link. The link and its percent-encoded form are each at most 2048 characters. null clears it.", "type": [ "string", "null" ] }, "variables": { "maxItems": 600, "description": "Only the variables that changed, at most 600, the cap a project apply has. A name deleted in this PATCH can be added again only in a later PATCH. One invalid entry answers 400 and nothing is saved.", "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "name": { "description": "The generator's name for the variable: the view's originalName when it is renamed, else its name. On an add, the new variable's name.", "type": "string" }, "choice": { "description": "null clears the choice, back to what the generator chose. Omitted leaves the choice as it is.", "anyOf": [ { "$ref": "#/components/schemas/TemplateVariableChoice" }, { "type": [ "object", "null" ], "enum": [ null, null ] } ] }, "newName": { "description": "Renames the variable: ^[A-Z][A-Z0-9_]{0,63}$, and no other variable of the service may have that name. null clears the rename. Omitted leaves the name as it is.", "type": [ "string", "null" ] }, "add": { "type": "boolean", "enum": [ true ], "description": "Adds a required variable called name to a web service or worker: ^[A-Z][A-Z0-9_]{0,63}$, a name no variable of the service has or shows, at most 200 variables per service and 1000 per template. The entry carries nothing else. A choice for it rides in its own entry, and adds run before every other entry." }, "delete": { "type": "boolean", "enum": [ true ], "description": "Deletes a variable the author added, with its choice and rename. One from the project answers 400: remove it with choice removed. The entry carries nothing else, and deletes run after every other entry." } }, "required": [ "service", "name" ] } }, "services": { "maxItems": 100, "description": "Only the services that changed, at most 100. An add or a delete entry carries nothing else. Service adds run first and deletes run after every other entry. A template holds at most 50 services. A name deleted in this PATCH can be added again only in a later PATCH. One invalid entry answers 400 and nothing is saved.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The service. On an add, the new service name: lower-kebab, at most 39 characters, a name no service of the template has.", "type": "string" }, "removed": { "description": "true leaves the service out of the published template, false restores it. Omitted leaves it as it is. A service the author added is deleted instead, and true on one answers 400.", "type": "boolean" }, "settings": { "description": "Only the fields that changed: each replaces that field. null clears every setting of the service. Postgres takes only pgVersion and storage only public. Redis, MySQL and MongoDB answer 400, and so does a field the service type does not take.", "anyOf": [ { "$ref": "#/components/schemas/TemplateServiceSettings" }, { "type": [ "object", "null" ], "enum": [ null, null ] } ] }, "add": { "$ref": "#/components/schemas/TemplateAddedService" }, "delete": { "type": "boolean", "enum": [ true ], "description": "Deletes a service the author added, with every setting, choice, rename and added variable kept under its name. One from the project answers 400: remove it with removed true. The entry carries nothing else, and deletes run after every other entry." } }, "required": [ "name" ] } }, "expectedUpdatedAt": { "format": "date-time", "description": "The draft's updatedAt as the client rendered it. A different current value answers 409 template_draft_changed.", "type": "string" } }, "required": [ "expectedUpdatedAt" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code template_draft_changed: the draft changed since the client read it (expectedUpdatedAt), review it and save again. Without a code: the new code is taken, or the template was already published and keeps its code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "429": { "description": "This user saved too many times in the last minute. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Edit a community template draft", "sidebarTitle": "Update org template" } } }, "delete": { "operationId": "deleteOrgTemplate", "summary": "Delete a draft that was never published", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Delete a draft that was never published", "sidebarTitle": "Delete org template" } } } }, "/orgs/{orgId}/templates/{code}/publish": { "post": { "operationId": "publishOrgTemplate", "summary": "Publish the draft to the gallery now, with no review, as the next version", "tags": [ "Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedUpdatedAt": { "format": "date-time", "description": "The draft's updatedAt as the client rendered it. A different current value answers 409 template_draft_changed.", "type": "string" } }, "required": [ "expectedUpdatedAt" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "code template_not_ready: a publish requirement is unmet. The message names the first, publishRequirements in the view lists them all. Without a code: a malformed request, a template that does not pass validation, or a draft generated by an older version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "code template_publish_conflict: the published version changed outside this draft. code template_code_owned: the code belongs to someone else. code template_taken_down: InstaCloud took this template down and it cannot be republished. code template_draft_changed: the draft changed since the client read it (expectedUpdatedAt), review it and publish again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodedError" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Publish the draft to the gallery now, with no review, as the next version", "sidebarTitle": "Publish org template" } } } }, "/orgs/{orgId}/templates/{code}/regenerate": { "post": { "operationId": "regenerateOrgTemplate", "summary": "Rebuild the draft from the source project, keeping what the author edited", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" }, "changes": { "type": "object", "properties": { "addedServices": { "type": "array", "items": { "type": "string" } }, "removedServices": { "type": "array", "items": { "type": "string" } }, "addedVariables": { "type": "array", "items": { "type": "string" } }, "removedVariables": { "type": "array", "items": { "type": "string" } } }, "required": [ "addedServices", "removedServices", "addedVariables", "removedVariables" ] } }, "required": [ "template", "changes" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).", "x-mint": { "metadata": { "title": "Rebuild the draft from the source project, keeping what the author edited", "sidebarTitle": "Regenerate org template" } } } }, "/orgs/{orgId}/templates/{code}/unpublish": { "post": { "operationId": "unpublishOrgTemplate", "summary": "Unpublish org template", "tags": [ "Templates" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "code", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/CommunityTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nTake the template out of the gallery. Deployed services keep running.", "x-mint": { "metadata": { "title": "Unpublish org template", "sidebarTitle": "Unpublish org template" } } } }, "/orgs/{orgId}/usage": { "get": { "operationId": "getOrgUsage", "summary": "Get org usage", "tags": [ "Billing" ], "parameters": [ { "schema": { "type": "integer" }, "in": "query", "name": "from", "required": false, "description": "unix seconds (default current cycle start)" }, { "schema": { "type": "integer" }, "in": "query", "name": "to", "required": false, "description": "unix seconds (default current cycle end)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgUsage" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nOrg usage across the 5 billing dimensions + per-project breakdown over a window (default current cycle)", "x-mint": { "metadata": { "title": "Get org usage", "sidebarTitle": "Get org usage" } } } }, "/orgs/{orgId}/zones": { "get": { "operationId": "listOrgZones", "summary": "List org zones", "tags": [ "Domains" ], "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nThe org's BYO delegated zones, each with its nameservers and the sweeper's last is-it-pointed-yet observation (refreshed about every minute at small fleet sizes; no per-request DNS).\n\nSet limit or cursor to request a page; continue with nextCursor until null. Without either parameter the complete collection is returned for compatibility.", "parameters": [ { "schema": { "minimum": 1, "maximum": 500, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "maxLength": 253, "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrgZone" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-mint": { "metadata": { "title": "List org zones", "sidebarTitle": "List org zones" } } } }, "/orgs/{orgId}/zones/{domainName}": { "delete": { "operationId": "releaseOrgZone", "summary": "Release org zone", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "domainName": { "type": "string" }, "released": { "type": "boolean", "enum": [ true ] } }, "required": [ "domainName", "released" ] } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nRelease a BYO delegated zone: the platform's records are pruned and the zone deleted. Point the domain's nameservers back at your own provider; hostnames then re-verify on the records path. Gated — zone.delegate. (admin+)", "x-mint": { "metadata": { "title": "Release org zone", "sidebarTitle": "Release org zone" } } } }, "/orgs/{orgId}/zones/{domainName}/records": { "post": { "operationId": "createOrgZoneRecord", "summary": "Create org zone record", "tags": [ "Domains" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "answer": { "type": "string" }, "ttl": { "type": "number" }, "priority": { "type": "number" } }, "required": [ "type", "answer" ] } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgZoneRecord" } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequired" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "the zone already serves (the repair window closed at activation), or the provider refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens refused (not a GET).\n\nThe pre-cutover REPAIR door: create a record the provider's scan missed, directly in the delegated zone, BEFORE switching the nameservers (the door closes at activation). Types beyond the registrar model are accepted where the review needs them (CAA). The record is yours, not the platform's — attach-published records are still managed for you. Gated — zone.delegate. (admin+)", "x-mint": { "metadata": { "title": "Create org zone record", "sidebarTitle": "Create org zone record" } } }, "get": { "operationId": "listOrgZoneRecords", "summary": "List org zone records", "tags": [ "Domains" ], "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orgId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "domainName", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrgZoneRecord" } } }, "required": [ "items" ] } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "**Token scope:** `account` · `org` — read-only tokens allowed.\n\nA delegated zone's records, for the pre-switch review: the provider's scan seeds common records but is not exhaustive — check this list against your current DNS and add what is missing before re-pointing the nameservers.", "x-mint": { "metadata": { "title": "List org zone records", "sidebarTitle": "List org zone records" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Session access JWT or an API token (`insta__`)." } }, "schemas": { "ApprovalRequired": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approval_required" ] }, "approvalId": { "format": "uuid", "type": "string" }, "action": { "description": "the gated action, or a comma-joined compound set — prefer `actions`", "type": "string" }, "actions": { "description": "every capability this approval covers", "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "url": { "description": "the console page where a project admin reviews this request", "type": "string" }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } }, "BillingCycle": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "cycleStart": { "format": "date-time", "type": "string" }, "cycleEnd": { "format": "date-time", "type": "string" }, "anchorDay": { "description": "day-of-month the cycle recurs on (org creation date, UTC)", "type": "integer" }, "now": { "format": "date-time", "type": "string" } } }, "BillingInvoice": { "type": "object", "properties": { "id": { "description": "Stripe invoice id", "example": "in_1Ofg…", "type": "string" }, "number": { "description": "the invoice number printed on the PDF; null before Stripe assigns one", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "amountUsd": { "description": "invoice total in USD", "type": "number" }, "currency": { "example": "usd", "type": "string" }, "status": { "description": "Stripe invoice status — paid, open or uncollectible (drafts and voided invoices are never listed)", "example": "paid", "type": "string" }, "description": { "description": "the invoice's description, else its first line item — what was bought", "type": [ "string", "null" ] }, "pdfUrl": { "description": "Stripe-hosted, read-only PDF; null until Stripe has rendered it. The payable hosted invoice link is deliberately never returned.", "type": [ "string", "null" ] } }, "required": [ "id", "number", "createdAt", "amountUsd", "currency", "status", "description", "pdfUrl" ] }, "BillingInvoiceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoice" } }, "nextBefore": { "description": "opaque cursor; pass as ?before= for the next page, null when there are no more", "type": [ "string", "null" ] } }, "required": [ "items" ] }, "BillingOverview": { "type": "object", "properties": { "window": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" } } }, "tier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "pendingPlanChange": { "type": [ "object", "null" ], "properties": { "changeKind": { "type": "string", "enum": [ "upgrade", "downgrade" ] }, "id": { "format": "uuid", "type": "string" }, "fromTier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "toTier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "effectiveAt": { "format": "date-time", "description": "UTC effective timestamp: next-day upgrade or paid-period-end downgrade; the current tier remains effective until cutover. A Free → Pro/Team change cuts over locally once paid (status applied) — this stays the Stripe subscription start.", "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "scheduled" ] }, "includedUsd": { "description": "Full-cycle target allowance. An in-cycle paid upgrade adds only a proportional increase to the existing cycle.", "type": "number" } }, "required": [ "id", "fromTier", "toTier", "effectiveAt", "status", "includedUsd" ] }, "billingStatus": { "type": "string", "enum": [ "active", "suspended" ] }, "subscriptionStatus": { "type": [ "string", "null" ] }, "totals": { "type": "object", "properties": { "usedUsd": { "description": "total usage cost in the window", "type": "number" }, "includedUsd": { "description": "included allowance saved for an exact snapshotted billing cycle; otherwise the configured current-tier allowance. Closed-cycle snapshots do not change when the org changes plan or configuration changes.", "type": "number" }, "overageUsd": { "description": "amount still owed for the window: max(0, used − included − creditsApplied − (live window ? creditBalance : 0))", "type": "number" }, "creditsUsd": { "description": "remaining usable included allowance plus the org credit balance (legacy merged figure; prefer creditBalanceUsd). Unused allowance from a closed snapshotted cycle is excluded.", "type": "number" }, "forecastUsd": { "description": "linear run-rate projection to the full cycle", "type": "number" }, "creditBalanceUsd": { "description": "credits the org holds as of now (every grant kind, unexpired, remaining > 0); not window-scoped; carries over between cycles", "type": "number" }, "creditsAppliedUsd": { "description": "credits taken off this window's billing cycle so far (billing_cycles.credit_applied_micros); 0 when the window is not a billing cycle", "type": "number" } } }, "byDimension": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } }, "byProject": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "deletedAt": { "format": "date-time", "description": "when the project was deleted — its usage history outlives it; null for a live project", "type": [ "string", "null" ] }, "totalCostUsd": { "type": "number" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } } } } } } }, "BillingSummary": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "pendingPlanChange": { "type": [ "object", "null" ], "properties": { "changeKind": { "type": "string", "enum": [ "upgrade", "downgrade" ] }, "id": { "format": "uuid", "type": "string" }, "fromTier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "toTier": { "type": "string", "enum": [ "free", "pro", "team", "enterprise" ] }, "effectiveAt": { "format": "date-time", "description": "UTC effective timestamp: next-day upgrade or paid-period-end downgrade; the current tier remains effective until cutover. A Free → Pro/Team change cuts over locally once paid (status applied) — this stays the Stripe subscription start.", "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_payment", "scheduled" ] }, "includedUsd": { "description": "Full-cycle target allowance. An in-cycle paid upgrade adds only a proportional increase to the existing cycle.", "type": "number" } }, "required": [ "id", "fromTier", "toTier", "effectiveAt", "status", "includedUsd" ] }, "billingStatus": { "type": "string", "enum": [ "active", "suspended" ] }, "cycleStart": { "format": "date-time", "type": "string" }, "cycleEnd": { "format": "date-time", "type": "string" }, "includedUsd": { "description": "tier allowance for the cycle (free $5 / pro $20 / team $0 — the plan fee is flat and usage bills from the first cent / enterprise per deal, $0 default); platform-configurable", "type": "number" }, "usedUsd": { "type": "number" }, "overageUsd": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "subscriptionStatus": { "description": "Stripe subscription status (active/past_due/canceled/…); null if no paid subscription.", "type": [ "string", "null" ] }, "caps": { "description": "this plan's resource ceilings for a compute service (vCPU / MB / volume Gi; managed redis/mysql/mongodb read the compute row) and for a postgres service (millicores / MiB / volume Gi) — the same rows the per-service `cap` fields return. A NEW service is born at them (cpu, memory and, since 2026-09-12, its volume), and an existing one may be raised to them. Read them from here to prefill a create form before any service exists; they move with the plan and with env overrides per deployment, so never hardcode a tier's numbers.", "type": "object", "properties": { "compute": { "type": "object", "properties": { "cpu": { "type": "integer" }, "memoryMb": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpu", "memoryMb", "volumeGib" ] }, "db": { "type": "object", "properties": { "cpuMilli": { "type": "integer" }, "memoryMib": { "type": "integer" }, "volumeGib": { "type": "integer" } }, "required": [ "cpuMilli", "memoryMib", "volumeGib" ] } }, "required": [ "compute", "db" ] } } }, "CodedError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "description": "stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress", "type": "string" } }, "required": [ "error" ] }, "CommunityTemplate": { "type": "object", "properties": { "id": { "format": "uuid", "description": "The draft's stable id. A rename of its code keeps it, and a new draft gets a new one, even under a code a deleted draft had. Routes and editor links address a draft by its code.", "type": "string" }, "code": { "type": "string" }, "orgId": { "format": "uuid", "type": "string" }, "sourceProjectId": { "format": "uuid", "type": [ "string", "null" ] }, "blank": { "description": "Created with POST /orgs/{orgId}/templates, with no project behind it: every service is one the author added, and Regenerate From Project answers 400. A generated draft whose project was deleted is not blank.", "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published", "unpublished" ] }, "publishedVersion": { "type": [ "string", "null" ] }, "hasUnpublishedChanges": { "type": "boolean" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "readme": { "type": [ "string", "null" ] }, "defaultReadme": { "description": "A README skeleton built from the draft as it is now: service names and required variable names only, never a value. The console offers it behind a button; it is not stored.", "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "description": "web with a port, worker without one, or the managed type (postgres, redis, mysql, mongodb or storage). It and the fields below are the values after the author's settings.", "type": "string" }, "image": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ] }, "healthcheck": { "type": [ "string", "null" ] }, "volume": { "type": "boolean" }, "mountPath": { "description": "null with volume true: the volume mounts at the default /data. null with volume false: no volume.", "type": [ "string", "null" ] }, "command": { "type": [ "string", "null" ] }, "alwaysOn": { "type": [ "boolean", "null" ] }, "public": { "description": "Storage only, always present on a bucket: anonymous public-read, after the author's setting.", "type": "boolean" }, "pgVersion": { "description": "Postgres only: the major a deploy creates the database on, after the author's setting. Absent when the project's database recorded none.", "type": "integer" }, "added": { "description": "Present, and true, only on a service the author added: a PATCH deletes it for good. One from the project is removed instead.", "type": "boolean" }, "removed": { "description": "The author left this service out of the template. It stays listed so it can be restored.", "type": "boolean" }, "variables": { "description": "Sorted by the generator's name (originalName when renamed). Empty for a managed database. A removed service lists what restoring it brings back.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariableView" } } }, "required": [ "name", "type", "image", "port", "healthcheck", "volume", "mountPath", "command", "alwaysOn", "removed", "variables" ] } }, "referenceOptions": { "description": "What a variable may reference in the template as it is now. A removed service offers nothing.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateReferenceOption" } }, "editableFields": { "$ref": "#/components/schemas/TemplateEditableFields" }, "referenceKeys": { "$ref": "#/components/schemas/TemplateReferenceKeys" }, "publishRequirements": { "description": "Always seven, in this order: has_service, no_blocked, no_conflicts, has_tagline, has_category, has_readme, required_descriptions.", "type": "array", "items": { "$ref": "#/components/schemas/TemplatePublishRequirement" } }, "report": { "$ref": "#/components/schemas/TemplateGenerationReport" }, "updatedAt": { "type": "string" }, "takenDown": { "description": "Staff took this template down. It cannot be republished.", "type": "boolean" }, "deployCount": { "description": "Succeeded deployments of this template.", "type": "integer" }, "totalProjects": { "description": "Distinct projects that deployed this template since its first publish, any outcome: the number the gallery card shows (the catalog's totalProjects).", "type": "integer" } }, "required": [ "id", "code", "orgId", "sourceProjectId", "blank", "status", "publishedVersion", "hasUnpublishedChanges", "name", "tagline", "category", "readme", "defaultReadme", "logoUrl", "services", "referenceOptions", "editableFields", "referenceKeys", "publishRequirements", "report", "updatedAt", "takenDown", "deployCount", "totalProjects" ] }, "CommunityTemplateSummary": { "type": "object", "properties": { "id": { "format": "uuid", "description": "The draft's stable id. A rename of its code keeps it, and a new draft gets a new one, even under a code a deleted draft had. Routes and editor links address a draft by its code.", "type": "string" }, "code": { "type": "string" }, "orgId": { "format": "uuid", "type": "string" }, "sourceProjectId": { "format": "uuid", "type": [ "string", "null" ] }, "blank": { "description": "Created with POST /orgs/{orgId}/templates, with no project behind it: every service is one the author added, and Regenerate From Project answers 400. A generated draft whose project was deleted is not blank.", "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published", "unpublished" ] }, "publishedVersion": { "type": [ "string", "null" ] }, "hasUnpublishedChanges": { "type": "boolean" }, "takenDown": { "description": "Staff took this template down. It cannot be republished.", "type": "boolean" }, "name": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" }, "deployCount": { "description": "Succeeded deployments of this template.", "type": "integer" }, "totalProjects": { "description": "Distinct projects that deployed this template since its first publish, any outcome: the number the gallery card shows (the catalog's totalProjects).", "type": "integer" } }, "required": [ "id", "code", "orgId", "sourceProjectId", "blank", "status", "publishedVersion", "hasUnpublishedChanges", "takenDown", "name", "tagline", "category", "logoUrl", "updatedAt", "deployCount", "totalProjects" ], "description": "One template of the org as GET /orgs/{orgId}/templates lists it, with no services, variables, reference options, publish requirements or README. GET /orgs/{orgId}/templates/{code} serves one in full." }, "ComputeProvider": { "description": "Compute plane actually backing a compute resource, derived from its provider_ref rather than its kind. Absent when it cannot be determined from the row — clients must then assert no provider rather than assume one from `kind`.", "type": "string", "enum": [ "fly", "insta-compute" ] }, "CreditTransaction": { "additionalProperties": false, "type": "object", "properties": { "id": { "type": "string" }, "amountUsd": { "description": "signed: positive = credit added (grant or reversal), negative = credit spent", "type": "number" }, "reason": { "description": "gift_grant | usage_debit | subscription_debit | adjust | expire | legacy_import", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "expiresAt": { "format": "date-time", "description": "the expiry of the grant this row moved, so a reader can see which bucket it came out of; null = never expires", "type": [ "string", "null" ] }, "ref": { "additionalProperties": false, "description": "what the movement was for", "type": "object", "properties": { "invoiceId": { "type": "string" }, "subscriptionId": { "type": "string" }, "reason": { "type": "string" }, "reversal": { "type": "string" }, "idempotencyKey": { "type": "string" } } } }, "required": [ "id", "amountUsd", "reason", "createdAt" ] }, "CreditTransactions": { "additionalProperties": false, "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTransaction" } }, "nextBefore": { "description": "opaque cursor; pass as ?before= for the next page, null when there are no more", "type": [ "string", "null" ] } }, "required": [ "items" ] }, "DimensionUsage": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "ram", "cpu", "volume", "storage", "egress" ] }, "quantity": { "type": "number" }, "unit": { "example": "GB·min", "type": "string" }, "costUsd": { "description": "quantity × unit price for this dimension in the window", "type": "number" } } }, "DnsRecord": { "type": "object", "properties": { "id": { "description": "the registrar's id for the record; the handle every write takes", "type": "integer" }, "type": { "$ref": "#/components/schemas/DnsRecordType" }, "host": { "description": "relative to the domain: \"@\" is the domain itself, \"api\" is api.", "type": "string" }, "fqdn": { "type": "string" }, "answer": { "type": "string" }, "ttl": { "description": "seconds", "type": "integer" }, "priority": { "description": "MX and SRV only", "type": "integer" }, "managed": { "description": "published by InstaCloud: read-only while `hostname` names the attached hostname it serves; without one, a leftover no hostname claims, which may be deleted", "type": "boolean" }, "hostname": { "description": "the attached hostname a managed record serves", "type": "string" } }, "required": [ "id", "type", "host", "fqdn", "answer", "ttl", "managed" ] }, "DnsRecordType": { "type": "string", "enum": [ "A", "AAAA", "ANAME", "CNAME", "MX", "NS", "SRV", "TXT" ] }, "DomainHostnameState": { "type": "object", "properties": { "hostname": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "attached", "active", "failed" ] }, "reason": { "type": "string" }, "service": { "description": "the compute service this hostname serves; each hostname of a domain can serve a different one", "type": [ "string", "null" ] } }, "required": [ "hostname", "state", "service" ] }, "DomainOrder": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "domainName": { "type": "string" }, "years": { "type": "integer" }, "status": { "$ref": "#/components/schemas/DomainOrderStatus" }, "priceCents": { "type": "integer" }, "renewalPriceCents": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "checkoutUrl": { "format": "uri", "description": "Stripe Checkout — present on create only; the human completes payment here", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "paidAt": { "format": "date-time", "type": [ "string", "null" ] }, "registeredAt": { "format": "date-time", "type": [ "string", "null" ] }, "failedReason": { "type": [ "string", "null" ] } }, "required": [ "id", "domainName", "years", "status", "priceCents", "renewalPriceCents", "currency", "createdAt", "paidAt", "registeredAt", "failedReason" ] }, "DomainOrderStatus": { "type": "string", "enum": [ "pending_payment", "paid", "registering", "registered", "attaching", "active", "failed", "canceled" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Invitation": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "expires_at": { "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } }, "Member": { "type": "object", "properties": { "user_id": { "description": "Better Auth user id (opaque string, not a UUID)", "type": "string" }, "role": { "$ref": "#/components/schemas/Role" }, "created_at": { "format": "date-time", "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "NextAction": { "type": "object", "properties": { "op": { "description": "Neutral logical action id, e.g. \"service.add\" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface.", "type": "string" }, "reason": { "description": "Natural-language, human/LLM-facing \"why do this now\".", "type": "string" }, "args": { "description": "Suggested, flat named arguments; \"\"s where a value is unknown.", "type": "object", "additionalProperties": true }, "gated": { "description": "True if the action passes a governance gate.", "type": "boolean" } }, "required": [ "op", "reason" ] }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "Org": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "is_personal": { "type": "boolean" }, "owner_user_id": { "description": "Better Auth user id (opaque string, not a UUID)", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "checkout_token": { "type": [ "string", "null" ] } } }, "OrgUsage": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "org": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } }, "totalCostUsd": { "type": "number" } } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "deletedAt": { "format": "date-time", "description": "when the project was deleted — its usage history outlives it; null for a live project", "type": [ "string", "null" ] }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionUsage" } }, "totalCostUsd": { "type": "number" } } } } } }, "OrgZone": { "type": "object", "properties": { "domainName": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_ns", "active" ], "description": "awaiting_ns: the zone is built and seeded by the provider's record scan — REVIEW its records (GET .../zones/:domainName/records; the scan finds common records, not necessarily all of them), add anything missing, then set the domain to `nameservers` at your registrar; active: the registry answers from the managed zone" }, "nameservers": { "description": "the managed zone's assigned nameservers — what the customer sets at their registrar", "type": "array", "items": { "type": "string" } }, "delegated": { "description": "whether the domain's public nameservers answer from the managed zone, as of the platform's last periodic observation (about a minute); a domain pointed away after activation reads false again within the same window", "type": "boolean" } }, "required": [ "domainName", "status", "nameservers", "delegated" ] }, "OrgZoneRecord": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "description": "\"@\" is the domain itself", "type": "string" }, "answer": { "type": "string" }, "ttl": { "type": "integer" }, "priority": { "type": "integer" }, "proxied": { "type": "boolean" } }, "required": [ "type", "host", "answer" ] }, "Project": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "org_id": { "format": "uuid", "type": "string" }, "owner_user_id": { "description": "Better Auth user id (opaque string, not a UUID)", "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "error", "deleting", "deleted" ] }, "created_at": { "format": "date-time", "type": "string" } } }, "ProvisionResult": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "defaultBranch": { "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" } } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/ResourceKind" }, "provider": { "$ref": "#/components/schemas/ComputeProvider" }, "status": { "type": "string" } } } }, "nextActions": { "type": "array", "items": { "$ref": "#/components/schemas/NextAction" } } } }, "PurchasedDomain": { "type": "object", "properties": { "domainName": { "type": "string" }, "status": { "type": "string", "enum": [ "registered", "attaching", "active", "attach_failed", "detached" ], "description": "detached: every service its hostnames named is gone — attach it again" }, "hostnames": { "type": "array", "items": { "$ref": "#/components/schemas/DomainHostnameState" } }, "registeredAt": { "format": "date-time", "type": [ "string", "null" ] }, "expiresAt": { "format": "date-time", "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "privacy": { "type": "boolean" }, "locked": { "description": "the registrar transfer lock: while it is on, no other registrar can pull the domain away. Turn it off to move the domain out. What the last write reported, or what registration asked for — nothing reads it back", "type": "boolean" }, "nameservers": { "description": "what the registrar holds. Empty means never written — only a nameserver write fills it in", "type": "array", "items": { "type": "string" } }, "delegated": { "description": "the zone is answered by nameservers InstaCloud cannot write to (custody `foreign`), so nothing published resolves and an attach is refused. A MANAGED delegation reads false: the platform still publishes there", "type": "boolean" }, "custody": { "type": "string", "enum": [ "registrar", "managed", "foreign" ], "description": "who answers the domain's zone: the registrar's own nameservers, a managed InstaCloud zone (delegated, still platform-published), or somewhere the platform cannot write" }, "transferLockExpiresAt": { "description": "ICANN 60-day lock after registration: no transfer out before this, whatever `locked` says", "format": "date-time", "type": [ "string", "null" ] }, "orderId": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "domainName", "status", "hostnames", "registeredAt", "expiresAt", "autorenew", "privacy", "locked", "nameservers", "delegated", "custody", "transferLockExpiresAt", "orderId" ] }, "ResourceKind": { "type": "string", "enum": [ "neon", "insta-db", "s3", "fly", "insta-compute" ] }, "Role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "TemplateAddedService": { "description": "A service the author adds to a template: a compute service from an image, web with a port and a worker without one, or a managed database or bucket by type.", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "compute" ] }, "image": { "description": "A public image reference, published as typed. The Image setting checks it.", "type": "string" }, "port": { "description": "1 to 65535. null: a worker, always on, with no health check.", "type": [ "integer", "null" ] } }, "required": [ "type", "image", "port" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "postgres", "redis", "mysql", "mongodb", "storage" ] } }, "required": [ "type" ] } ] }, "TemplateEditableFields": { "description": "Per service type, the TemplateServiceSettings keys a template service of that type takes. A PATCH answers 400 for any other.", "type": "object", "properties": { "web": { "type": "array", "items": { "type": "string", "enum": [ "image", "port", "healthcheck", "command", "mountPath", "alwaysOn" ] } }, "worker": { "type": "array", "items": { "type": "string", "enum": [ "image", "port", "healthcheck", "command", "mountPath", "alwaysOn" ] } }, "postgres": { "type": "array", "items": { "type": "string", "enum": [ "pgVersion" ] } }, "redis": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "mysql": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "mongodb": { "maxItems": 0, "type": "array", "items": { "type": "string" } }, "storage": { "type": "array", "items": { "type": "string", "enum": [ "public" ] } } }, "required": [ "web", "worker", "postgres", "redis", "mysql", "mongodb", "storage" ] }, "TemplateGenerationReport": { "description": "What generation skipped, what blocks publishing (each with a fix), and notices.", "type": "object", "properties": { "skipped": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } }, "notices": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "variable": { "type": "string" }, "reason": { "type": "string" }, "fix": { "type": "string" } }, "required": [ "reason" ] } } }, "required": [ "skipped", "blocked", "notices" ] }, "TemplatePublishRequirement": { "description": "One condition publish checks. Publish answers 400 template_not_ready while any is not ok.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "has_service", "no_blocked", "no_conflicts", "has_tagline", "has_category", "has_readme", "required_descriptions" ] }, "ok": { "type": "boolean" }, "items": { "description": "no_blocked: each blocked reason. no_conflicts: one sentence with its fix for each name the author added that the project now has too, services first. required_descriptions: each . still without a description. Otherwise empty.", "type": "array", "items": { "type": "string" } } }, "required": [ "code", "ok", "items" ] }, "TemplateReferenceKeys": { "description": "Per managed service type, the credential keys a variable may reference on a service of that type, one the author has not applied yet included (secretNames.ts CANONICAL_KEYS). A web service's url and host are not listed.", "type": "object", "properties": { "postgres": { "type": "array", "items": { "type": "string" } }, "redis": { "type": "array", "items": { "type": "string" } }, "mysql": { "type": "array", "items": { "type": "string" } }, "mongodb": { "type": "array", "items": { "type": "string" } }, "storage": { "type": "array", "items": { "type": "string" } } }, "required": [ "postgres", "redis", "mysql", "mongodb", "storage" ] }, "TemplateReferenceOption": { "description": "What a variable may reference: a database connection key, a bucket key, or a web service address including the service itself.", "type": "object", "properties": { "token": { "description": "Exactly what a reference choice sends and the manifest stores.", "type": "string" }, "service": { "type": "string" }, "key": { "description": "A credential key of a managed database or a storage bucket, or url or host of a web service.", "type": "string" } }, "required": [ "token", "service", "key" ] }, "TemplateServiceSettings": { "description": "What the author changed on one service. CommunityTemplate.editableFields lists the keys each service type takes, and a PATCH answers 400 for any other. A field left out keeps the generator's value.", "type": "object", "properties": { "public": { "description": "Storage only: serve the bucket with anonymous public-read. false makes it private again.", "type": "boolean" }, "image": { "description": "An image reference, published as typed (not pinned to a digest).", "type": "string" }, "port": { "description": "1 to 65535. null: no port, so the service runs as a worker, with no health check and always on.", "type": [ "integer", "null" ] }, "alwaysOn": { "description": "false: the service scales to zero when idle. A worker is always on whatever this says.", "type": "boolean" }, "mountPath": { "description": "Where a volume mounts, a path starting with /. null, or an empty or blank string: no volume.", "type": [ "string", "null" ] }, "pgVersion": { "description": "Postgres only: the major a deploy creates the database on, one of 16, 17, 18.", "type": "integer" }, "healthcheck": { "description": "A path starting with /. null, or an empty or blank string: none.", "type": [ "string", "null" ] }, "command": { "description": "Run through sh -c. null, or an empty or blank string: the image's own.", "type": [ "string", "null" ] } } }, "TemplateVariableChoice": { "description": "The author's choice for one variable: required, optional with or without a default, a reference, a random 32-character secret, or left out.", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "required" ] }, "description": { "description": "At most 200 characters. Blank keeps the default sentence.", "type": "string" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "optional" ] }, "default": { "description": "At most 4096 bytes. Published with the template, so never a secret.", "type": "string" }, "description": { "type": "string" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reference" ] }, "token": { "description": "One of the view referenceOptions tokens, or a key of a service removed from the template: that variable stays required until the service is restored.", "type": "string" } }, "required": [ "kind", "token" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "generated" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "removed" ] } }, "required": [ "kind" ] } ] }, "TemplateVariableView": { "description": "One variable of a template service as its author sees it.", "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "required", "optional", "default", "reference", "generated", "fixed", "removed" ] }, "value": { "description": "default: the default text. reference: the token. fixed: the literal or the address reference.", "type": "string" }, "description": { "description": "What whoever deploys reads. Omitted while it is the default sentence, which the console shows as an empty box.", "type": "string" }, "brokenReference": { "description": "The token this variable referenced before its service was removed from the template or left the project. The variable is then required.", "type": "string" }, "originalName": { "description": "Present only when the author renamed the variable: the generator's name, which a PATCH variables entry sends as name. name is then the new one.", "type": "string" }, "added": { "description": "Present, and true, only on a variable the author added: a PATCH deletes it for good. One from the project is removed with choice removed instead.", "type": "boolean" } }, "required": [ "name", "kind" ] } } } }