{"openapi":"3.0.3","info":{"title":"Gigadrive Network API","description":"The Gigadrive Network API is the programmable control plane for Network applications, deployments, storage, request observability, and AI Gateway access. Use it to automate the same product workflows available in the console: discover organizations and applications, trigger and upload deployments, manage runtime configuration, operate application storage, inspect routed traffic, and exchange API keys for short-lived OAuth access tokens. Customer-facing endpoints require Bearer authentication with scopes that match the operation being performed.","version":"0.1.0"},"tags":[{"name":"Authentication","description":"OIDC discovery, public signing keys, and the OAuth 2.0 client credentials token flow for API-key based machine-to-machine access."},{"name":"Organizations","description":"Organization-level account containers that own Network applications, API keys, product access, and shared configuration. Includes organization CRUD helpers, membership listing, and product entitlement checks. Product subscriptions are read-only through the public API."},{"name":"Applications","description":"Network applications are deployable projects. Application endpoints let automation discover the resources it can operate on."},{"name":"Environment Variables","description":"Runtime configuration injected into deployments. Variables can live at organization or application scope and can be marked sensitive."},{"name":"Domains","description":"Custom domains for applications. Verify a domain once per organization with a TXT record, then attach any hostname below it; Gigadrive checks DNS, issues the certificate and starts serving automatically."},{"name":"Deployments","description":"Deployment records and archive upload flows used to ship application code to Gigadrive Network infrastructure."},{"name":"Storage","description":"Application storage buckets, objects, resumable upload sessions, and signed or public object access URLs. The endpoints documented here also include management of S3 credentials. Storage additionally exposes an **S3-compatible API** on `s3.gigadrive.network` (path-style or virtual-hosted addressing) and at `/s3` on this host (path-style), both with AWS Signature V4: create an S3 credential via `POST /applications/{applicationId}/storage/s3-credentials`, then point any S3 client (aws-cli, AWS SDK v3, boto3, rclone) at the `/s3` endpoint with `forcePathStyle` enabled. The S3 protocol operations are not enumerated in this OpenAPI document because they use query-string operation discrimination, SigV4 auth, and XML/binary payloads rather than the JSON+bearer conventions used elsewhere here."},{"name":"Queues","description":"Durable, environment-scoped message queues. Push queues deliver each message to a path on your deployment (signed with `x-gigadrive-queue-signature`); pull queues are drained with receive and acknowledge. Supports delays and scheduled sends up to a year ahead, cancellation, deduplication keys, ordered groups, concurrency and rate limits, retries with backoff, dead letters with redrive, and cron schedules evaluated in any IANA time zone."},{"name":"MicroVMs","description":"On-demand isolated Linux microVMs for running untrusted or AI-generated code. Create one from a built-in or custom image, run commands (to completion or detached, with streamed output and stdin), read and write files, and expose ports on public preview URLs. A microVM stops by itself after its timeout and is billed for its active CPU time and its memory while it runs."},{"name":"Request Logs","description":"Traffic observability for requests served by Network routing, functions, assets, and storage delivery."},{"name":"MCP","description":"Remote Model Context Protocol server at `/mcp` that exposes Gigadrive Network as tools for AI assistants such as Claude, plus the OAuth 2.0 Protected Resource Metadata MCP clients use to sign users in through the Gigadrive account system."},{"name":"AI Gateway","description":"OpenAI-compatible model routing across configured AI providers, including model discovery, inference endpoints, organization usage analytics, budgets, and model policy controls."}],"paths":{"/mcp":{"get":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"post":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"put":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"delete":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"patch":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"head":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"options":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"},"trace":{"summary":"Model Context Protocol endpoint","description":"Remote MCP server (Streamable HTTP, stateless) exposing Gigadrive Network as tools for AI assistants such as Claude. Authenticate with a Gigadrive user token bound to this resource via OAuth, or with a Network API key token. See the documentation for connection instructions.","tags":["MCP"],"operationId":"allMcp"}},"/oauth2/token":{"post":{"operationId":"createOAuthToken","summary":"Create an OAuth access token","description":"Exchanges a Gigadrive API key for a short-lived bearer token using the OAuth 2.0 client credentials grant. This is the recommended machine-to-machine authentication flow for automation, CI systems, and backend services that call the Network API. Credentials can be sent either with HTTP Basic auth or as `client_id` and `client_secret` body fields. The token inherits the API key actor binding and allowed scopes; it does not create a user session and does not issue refresh tokens.","tags":["Authentication"],"security":[],"parameters":[{"name":"authorization","in":"header","required":false,"schema":{"pattern":"^Basic\\s+\\S+$","description":"Basic authentication header for client credentials","examples":["Basic YWFhYWFhYWEtYWFhYS00YWFhLThhYWEtYWFhYWFhYWFhYWFhYTpzZWNyZXQ="],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"description":"The only OAuth grant supported by the Network API issuer.","examples":["client_credentials"],"const":"client_credentials","type":"string"},"client_id":{"format":"uuid","description":"API key ID. Optional when credentials are sent with HTTP Basic auth.","examples":["0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa"],"type":"string"},"client_secret":{"description":"API key secret. Optional when credentials are sent with HTTP Basic auth.","examples":["gdnet_secret_..."],"type":"string"}},"additionalProperties":false}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"description":"The only OAuth grant supported by the Network API issuer.","examples":["client_credentials"],"const":"client_credentials","type":"string"},"client_id":{"format":"uuid","description":"API key ID. Optional when credentials are sent with HTTP Basic auth.","examples":["0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa"],"type":"string"},"client_secret":{"description":"API key secret. Optional when credentials are sent with HTTP Basic auth.","examples":["gdnet_secret_..."],"type":"string"}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"description":"The only OAuth grant supported by the Network API issuer.","examples":["client_credentials"],"const":"client_credentials","type":"string"},"client_id":{"format":"uuid","description":"API key ID. Optional when credentials are sent with HTTP Basic auth.","examples":["0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa"],"type":"string"},"client_secret":{"description":"API key secret. Optional when credentials are sent with HTTP Basic auth.","examples":["gdnet_secret_..."],"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["token_type","access_token","expires_in","scope"],"properties":{"token_type":{"description":"Token type used in the Authorization header.","const":"Bearer","type":"string"},"access_token":{"description":"Short-lived JWT access token for Gigadrive Network API requests.","examples":["eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."],"type":"string"},"expires_in":{"description":"Token lifetime in seconds. Network tokens currently expire after 5 minutes.","examples":[300],"type":"number"},"scope":{"description":"Space-separated scopes included in the issued token.","examples":["openid network:applications:read network:deployments:trigger"],"type":"string"}},"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","error_description"],"properties":{"error":{"description":"OAuth error code for malformed or unsupported token requests.","const":"invalid_request","type":"string"},"error_description":{"description":"Explanation of which required token request field or format was invalid.","type":"string"}},"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","error_description"],"properties":{"error":{"description":"OAuth error code for missing, expired, or incorrect API key credentials.","const":"invalid_client","type":"string"},"error_description":{"description":"Explanation of why the API key could not be authenticated.","type":"string"}},"additionalProperties":false}}}}}}},"/organizations":{"get":{"operationId":"listOrganizations","summary":"List organizations","description":"Returns the organizations visible to the authenticated actor. Organizations are the top-level containers for Network applications, API keys, product access, and shared configuration. Use this endpoint at the start of automation flows to discover which organization IDs can be used when filtering applications, deployments, and organization-scoped environment variables.","tags":["Organizations"],"parameters":[{"name":"from","in":"query","required":false,"schema":{"description":"Cursor for the next page of list results. Pass the last resource ID returned by the previous page to continue listing from that point within the same filters and authenticated actor scope.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"limit","in":"query","required":true,"schema":{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createOrganization","summary":"Create an organization","description":"While Gigadrive Network is in early access, this endpoint is limited to accounts that have been let off the waitlist; everyone else receives 403. Creates a new organization and makes the authenticated user its owner. Organization creation is limited to user-backed tokens; machine actors such as organization or application API keys cannot create organizations. Creation is also subject to a per-user ownership quota and a short-term rate limit enforced in the platform organization service, and to a budget on organizations without a saved payment method — past that budget this endpoint refuses, because it cannot collect one. Create the organization in the Gigadrive console instead, which asks for a payment method as part of the flow. The returned organization ID can be used immediately with other organization-scoped Network APIs.","tags":["Organizations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":128,"description":"Display name for the new organization.","examples":["Acme Corp"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":128,"description":"Display name for the new organization.","examples":["Acme Corp"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":128,"description":"Display name for the new organization.","examples":["Acme Corp"],"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}":{"get":{"operationId":"getOrganization","summary":"Get an organization","description":"Returns a single organization the authenticated actor can access. Use this endpoint when you already know the organization ID and need its display name, slug, or avatar URL before calling organization-scoped Network APIs.","tags":["Organizations"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization to retrieve.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/members":{"get":{"operationId":"listOrganizationMembers","summary":"List organization members","description":"Returns the users who belong to an organization, including their membership role. Use this endpoint for organization administration and access audits. Application, deployment, and function actors cannot read membership data.","tags":["Organizations"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose members should be listed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["membershipId","organizationId","userId","email","givenName","familyName","imageUrl","role","joinedAt"],"properties":{"membershipId":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","description":"Organization that owns this membership.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"userId":{"format":"uuid","description":"User who belongs to the organization.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},"email":{"format":"email","description":"Email address of the organization member.","examples":["owner@example.com"],"type":"string"},"givenName":{"nullable":true,"anyOf":[{"description":"Given name of the organization member, or null when unset.","examples":["Ada"],"type":"string"},{"type":"null"}]},"familyName":{"nullable":true,"anyOf":[{"description":"Family name of the organization member, or null when unset.","examples":["Lovelace"],"type":"string"},{"type":"null"}]},"imageUrl":{"nullable":true,"anyOf":[{"format":"uri","description":"Avatar URL for the organization member, or null when unset.","examples":["https://cdn.gigadrive.de/users/ada.png"],"type":"string"},{"type":"null"}]},"role":{"default":"OWNER","description":"Organization membership role used for administration privileges.","type":"string","enum":["OWNER","ADMIN","MEMBER"]},"joinedAt":{"format":"date-time","description":"ISO 8601 timestamp when the user joined the organization.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organizationMember"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/products":{"get":{"operationId":"listOrganizationProducts","summary":"List organization product access","description":"Returns effective product access for every organization-scoped product, including whether access comes from an explicit entitlement override or the product registry default, plus any active local subscription. Use this to discover which Gigadrive products an organization can use before calling product-specific APIs.","tags":["Organizations"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose product access should be listed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["product","hasAccess","resolutionSource","explicitEntitlement","subscription"],"properties":{"product":{"type":"object","required":["slug","displayName","accessMode","defaultAccessPolicy","plans"],"properties":{"slug":{"description":"Stable product slug from the code-defined product registry.","examples":["network","office"],"type":"string"},"displayName":{"description":"Human-readable product name.","examples":["Gigadrive Network","Gigadrive Office"],"type":"string"},"accessMode":{"default":"organization","description":"Whether the product is granted to organizations or directly to users.","type":"string","enum":["organization","user"]},"defaultAccessPolicy":{"default":"granted","description":"Fallback access policy when no explicit entitlement override exists for the organization or user.","type":"string","enum":["granted","explicit_entitlement_required"]},"plans":{"description":"Locally activatable plans defined for the product. Empty when the product has no plan catalog.","type":"array","items":{"type":"object","required":["slug","displayName","description"],"properties":{"slug":{"description":"Stable plan slug from the code-defined product registry.","examples":["free","team"],"type":"string"},"displayName":{"description":"Human-readable plan name shown in product surfaces.","examples":["Free","Team"],"type":"string"},"description":{"description":"Short description of what the plan includes.","examples":["Get started with Office for a small team at no cost."],"type":"string"}}}}}},"hasAccess":{"description":"Whether the organization currently has effective access to the product.","examples":[true],"type":"boolean"},"resolutionSource":{"default":"explicit","description":"Whether effective access was resolved from an explicit entitlement override or the product registry default policy.","type":"string","enum":["explicit","default"]},"explicitEntitlement":{"description":"Explicit entitlement override when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","status","grantedByUserId","revokedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this entitlement override applies to.","examples":["office"],"type":"string"},"status":{"default":"ACTIVE","description":"Lifecycle status of the explicit entitlement override.","type":"string","enum":["ACTIVE","SUSPENDED","REVOKED"]},"grantedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who last granted or updated the entitlement override, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the entitlement was revoked, or null when not revoked.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]},"subscription":{"description":"Local product subscription when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","plan","status","activatedByUserId","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this subscription applies to.","examples":["office"],"type":"string"},"plan":{"description":"Currently selected plan slug for the product.","examples":["free","team"],"type":"string"},"status":{"default":"ACTIVE","description":"Local subscription lifecycle status.","type":"string","enum":["ACTIVE","CANCELED"]},"activatedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who activated the current plan, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]}},"$id":"#/components/schemas/organizationProductAccess"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/products/{product}":{"get":{"operationId":"getOrganizationProduct","summary":"Get organization product access","description":"Returns effective access for one organization-scoped product, including explicit entitlement and subscription state when present. Prefer this endpoint when automation only needs to check a single product entitlement before proceeding.","tags":["Organizations"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization to check product access for.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"product","in":"path","required":true,"schema":{"description":"Product slug from the code-defined product registry.","examples":["network","office"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["product","hasAccess","resolutionSource","explicitEntitlement","subscription"],"properties":{"product":{"type":"object","required":["slug","displayName","accessMode","defaultAccessPolicy","plans"],"properties":{"slug":{"description":"Stable product slug from the code-defined product registry.","examples":["network","office"],"type":"string"},"displayName":{"description":"Human-readable product name.","examples":["Gigadrive Network","Gigadrive Office"],"type":"string"},"accessMode":{"default":"organization","description":"Whether the product is granted to organizations or directly to users.","type":"string","enum":["organization","user"]},"defaultAccessPolicy":{"default":"granted","description":"Fallback access policy when no explicit entitlement override exists for the organization or user.","type":"string","enum":["granted","explicit_entitlement_required"]},"plans":{"description":"Locally activatable plans defined for the product. Empty when the product has no plan catalog.","type":"array","items":{"type":"object","required":["slug","displayName","description"],"properties":{"slug":{"description":"Stable plan slug from the code-defined product registry.","examples":["free","team"],"type":"string"},"displayName":{"description":"Human-readable plan name shown in product surfaces.","examples":["Free","Team"],"type":"string"},"description":{"description":"Short description of what the plan includes.","examples":["Get started with Office for a small team at no cost."],"type":"string"}}}}}},"hasAccess":{"description":"Whether the organization currently has effective access to the product.","examples":[true],"type":"boolean"},"resolutionSource":{"default":"explicit","description":"Whether effective access was resolved from an explicit entitlement override or the product registry default policy.","type":"string","enum":["explicit","default"]},"explicitEntitlement":{"description":"Explicit entitlement override when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","status","grantedByUserId","revokedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this entitlement override applies to.","examples":["office"],"type":"string"},"status":{"default":"ACTIVE","description":"Lifecycle status of the explicit entitlement override.","type":"string","enum":["ACTIVE","SUSPENDED","REVOKED"]},"grantedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who last granted or updated the entitlement override, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the entitlement was revoked, or null when not revoked.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]},"subscription":{"description":"Local product subscription when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","plan","status","activatedByUserId","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this subscription applies to.","examples":["office"],"type":"string"},"plan":{"description":"Currently selected plan slug for the product.","examples":["free","team"],"type":"string"},"status":{"default":"ACTIVE","description":"Local subscription lifecycle status.","type":"string","enum":["ACTIVE","CANCELED"]},"activatedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who activated the current plan, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]}},"$id":"#/components/schemas/organizationProductAccess"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/products/{product}/entitlement":{"get":{"operationId":"checkOrganizationProductEntitlement","summary":"Check organization product entitlement","description":"Returns a compact yes/no entitlement check for whether an organization currently has access to a product. This resolves explicit entitlement overrides and product registry defaults without returning full subscription metadata.","tags":["Organizations"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization to check product entitlement for.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"product","in":"path","required":true,"schema":{"description":"Product slug from the code-defined product registry.","examples":["network","office"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["organizationId","product","hasAccess"],"properties":{"organizationId":{"format":"uuid","description":"Organization that was checked.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"product":{"description":"Product slug that was checked.","examples":["network","office"],"type":"string"},"hasAccess":{"description":"Whether the organization currently has effective access to the product.","examples":[true],"type":"boolean"}},"$id":"#/components/schemas/organizationProductEntitlementCheck"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/env-vars":{"get":{"operationId":"listOrganizationEnvVars","summary":"List organization environment variables","description":"Returns environment variables defined at organization scope. Organization variables provide shared runtime configuration for Network applications in the organization. Sensitive variables are returned with a `null` value so clients can show that a secret exists without exposing the secret material.","tags":["Environment Variables"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the variables.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createOrganizationEnvVar","summary":"Create organization environment variable","description":"Creates a new organization-scoped environment variable. Use organization variables for configuration that should be available across multiple applications in the same organization. Keys must be unique within the organization scope and may be marked sensitive to prevent the value from being read back through the API.","tags":["Environment Variables"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that should receive the variable.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/env-vars/{envVarId}":{"patch":{"operationId":"updateOrganizationEnvVar","summary":"Update organization environment variable","description":"Updates an organization-scoped environment variable. You can rename the key, replace the value, or change whether the value is treated as sensitive. Renaming must not conflict with another variable in the same organization scope. The returned resource reflects the stored variable, with sensitive values redacted.","tags":["Environment Variables"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the variable.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"envVarId","in":"path","required":true,"schema":{"format":"uuid","description":"Environment variable to update.","examples":["0197b2f3-4d6f-7e2a-8c4b-444444444444"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"deleteOrganizationEnvVar","summary":"Delete organization environment variable","description":"Deletes an organization-scoped environment variable. Existing deployments keep any configuration already materialized for them; future deployments and runtime resolutions no longer receive the deleted value.","tags":["Environment Variables"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the variable.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"envVarId","in":"path","required":true,"schema":{"format":"uuid","description":"Environment variable to delete.","examples":["0197b2f3-4d6f-7e2a-8c4b-444444444444"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The organization environment variable was removed.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/domains":{"get":{"operationId":"listOrganizationDomains","summary":"List verified domains","description":"Lists the domains the organization claimed or verified. A verified domain lets every application of the organization attach hostnames at or below it without another TXT record.","tags":["Domains"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the domains.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","organizationId","name","unicodeName","status","verificationMethod","record","error","verifiedAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","type":"string"},"name":{"description":"Verified (or claimed) domain in ASCII form.","examples":["example.com"],"type":"string"},"unicodeName":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verificationMethod":{"anyOf":[{"const":"txt","type":"string"},{"const":"nameservers","type":"string"},{"const":"domain_connect","type":"string"},{"const":"legacy_fqdn_txt","type":"string"},{"type":"null"}]},"record":{"description":"TXT record that proves control of the domain. Keep it published after verification.","type":"object","required":["type","name","host","value"],"properties":{"type":{"const":"TXT","type":"string"},"name":{"examples":["_gigadrive-challenge.example.com"],"type":"string"},"host":{"examples":["_gigadrive-challenge"],"type":"string"},"value":{"examples":["gigadrive-verification=4f1c2e8a9b7d6c5e4f3a2b1c0d9e8f7a"],"type":"string"}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"verifiedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/domainOwnership"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}},"post":{"operationId":"addOrganizationDomain","summary":"Add domain for verification","description":"Claims a domain for the organization and returns the TXT record that proves control. Gigadrive checks for the record automatically; call the verify endpoint to check right away. A domain below an already verified one is verified immediately.","tags":["Domains"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the domains.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":300,"description":"Domain to verify, usually the registrable domain such as `example.com`.","examples":["example.com"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":300,"description":"Domain to verify, usually the registrable domain such as `example.com`.","examples":["example.com"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":300,"description":"Domain to verify, usually the registrable domain such as `example.com`.","examples":["example.com"],"type":"string"}}}}}},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","name","unicodeName","status","verificationMethod","record","error","verifiedAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","type":"string"},"name":{"description":"Verified (or claimed) domain in ASCII form.","examples":["example.com"],"type":"string"},"unicodeName":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verificationMethod":{"anyOf":[{"const":"txt","type":"string"},{"const":"nameservers","type":"string"},{"const":"domain_connect","type":"string"},{"const":"legacy_fqdn_txt","type":"string"},{"type":"null"}]},"record":{"description":"TXT record that proves control of the domain. Keep it published after verification.","type":"object","required":["type","name","host","value"],"properties":{"type":{"const":"TXT","type":"string"},"name":{"examples":["_gigadrive-challenge.example.com"],"type":"string"},"host":{"examples":["_gigadrive-challenge"],"type":"string"},"value":{"examples":["gigadrive-verification=4f1c2e8a9b7d6c5e4f3a2b1c0d9e8f7a"],"type":"string"}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"verifiedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/domainOwnership"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/organizations/{organizationId}/domains/{domainId}":{"get":{"operationId":"getOrganizationDomain","summary":"Get verified domain","description":"Returns one domain ownership with its verification record and status.","tags":["Domains"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the domains.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Domain ownership to act on.","examples":["0197b2f6-3c4d-7e5f-8a6b-666666666666"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","name","unicodeName","status","verificationMethod","record","error","verifiedAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","type":"string"},"name":{"description":"Verified (or claimed) domain in ASCII form.","examples":["example.com"],"type":"string"},"unicodeName":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verificationMethod":{"anyOf":[{"const":"txt","type":"string"},{"const":"nameservers","type":"string"},{"const":"domain_connect","type":"string"},{"const":"legacy_fqdn_txt","type":"string"},{"type":"null"}]},"record":{"description":"TXT record that proves control of the domain. Keep it published after verification.","type":"object","required":["type","name","host","value"],"properties":{"type":{"const":"TXT","type":"string"},"name":{"examples":["_gigadrive-challenge.example.com"],"type":"string"},"host":{"examples":["_gigadrive-challenge"],"type":"string"},"value":{"examples":["gigadrive-verification=4f1c2e8a9b7d6c5e4f3a2b1c0d9e8f7a"],"type":"string"}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"verifiedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/domainOwnership"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}},"delete":{"operationId":"removeOrganizationDomain","summary":"Remove verified domain","description":"Removes a domain from the organization. Refused with `ownership_in_use` while custom domains still rely on it, including custom domains still waiting for this domain’s TXT record; remove those first.","tags":["Domains"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the domains.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Domain ownership to act on.","examples":["0197b2f6-3c4d-7e5f-8a6b-666666666666"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The domain was removed from the organization.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/organizations/{organizationId}/domains/{domainId}/verify":{"post":{"operationId":"verifyOrganizationDomain","summary":"Verify domain now","description":"Checks the TXT record right away. Every public resolver Gigadrive uses must see it. On success, pending custom domains below this domain continue to the DNS step. For an already verified domain the check runs again and refreshes `verifiedAt`; a failed re-check is reported in `error` without revoking the verification. Rate limited per domain and organization: a `rate_limited` response carries a `Retry-After` header.","tags":["Domains"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization that owns the domains.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Domain ownership to act on.","examples":["0197b2f6-3c4d-7e5f-8a6b-666666666666"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","name","unicodeName","status","verificationMethod","record","error","verifiedAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","type":"string"},"name":{"description":"Verified (or claimed) domain in ASCII form.","examples":["example.com"],"type":"string"},"unicodeName":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verificationMethod":{"anyOf":[{"const":"txt","type":"string"},{"const":"nameservers","type":"string"},{"const":"domain_connect","type":"string"},{"const":"legacy_fqdn_txt","type":"string"},{"type":"null"}]},"record":{"description":"TXT record that proves control of the domain. Keep it published after verification.","type":"object","required":["type","name","host","value"],"properties":{"type":{"const":"TXT","type":"string"},"name":{"examples":["_gigadrive-challenge.example.com"],"type":"string"},"host":{"examples":["_gigadrive-challenge"],"type":"string"},"value":{"examples":["gigadrive-verification=4f1c2e8a9b7d6c5e4f3a2b1c0d9e8f7a"],"type":"string"}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"verifiedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/domainOwnership"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/organizations/{organizationId}/ai-gateway/usage/summary":{"get":{"operationId":"getOrganizationAiGatewayUsageSummary","summary":"Get organization AI Gateway usage summary","description":"Returns aggregate AI Gateway usage for an organization, including request counts, token totals, billable cost, latency, and breakdowns by model, provider, and user/end-user label. Use this endpoint for dashboards, billing previews, and usage analytics similar to OpenRouter-style activity summaries.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started at or after this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started before or at this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Restrict summary results to requests attributed to this Network application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["summary","byModel","byProvider","byUser"],"properties":{"summary":{"type":"object","required":["requestCount","successCount","errorCount","inputTokens","outputTokens","totalTokens","billableCostMicros","avgLatencyMs"],"properties":{"requestCount":{"description":"Total AI Gateway requests in the selected time range.","type":"number"},"successCount":{"description":"Requests that completed successfully.","type":"number"},"errorCount":{"description":"Requests that failed.","type":"number"},"inputTokens":{"description":"Total input tokens reported or estimated.","type":"number"},"outputTokens":{"description":"Total output tokens reported or estimated.","type":"number"},"totalTokens":{"description":"Total input plus output tokens.","type":"number"},"billableCostMicros":{"description":"Billable cost in micros of EUR.","type":"number"},"avgLatencyMs":{"description":"Average request latency in milliseconds.","type":"number"}}},"byModel":{"type":"array","items":{"type":"object","required":["label","requests","tokens","inputTokens","outputTokens","costMicros"],"properties":{"label":{"description":"Breakdown bucket label, such as a model, provider, or user identifier.","type":"string"},"requests":{"description":"Number of requests in this bucket.","type":"number"},"tokens":{"description":"Total tokens in this bucket.","type":"number"},"inputTokens":{"description":"Input tokens in this bucket.","type":"number"},"outputTokens":{"description":"Output tokens in this bucket.","type":"number"},"costMicros":{"description":"Billable cost in micros of EUR for this bucket.","type":"number"}}}},"byProvider":{"type":"array","items":{"type":"object","required":["label","requests","tokens","inputTokens","outputTokens","costMicros"],"properties":{"label":{"description":"Breakdown bucket label, such as a model, provider, or user identifier.","type":"string"},"requests":{"description":"Number of requests in this bucket.","type":"number"},"tokens":{"description":"Total tokens in this bucket.","type":"number"},"inputTokens":{"description":"Input tokens in this bucket.","type":"number"},"outputTokens":{"description":"Output tokens in this bucket.","type":"number"},"costMicros":{"description":"Billable cost in micros of EUR for this bucket.","type":"number"}}}},"byUser":{"type":"array","items":{"type":"object","required":["label","requests","tokens","inputTokens","outputTokens","costMicros"],"properties":{"label":{"description":"Breakdown bucket label, such as a model, provider, or user identifier.","type":"string"},"requests":{"description":"Number of requests in this bucket.","type":"number"},"tokens":{"description":"Total tokens in this bucket.","type":"number"},"inputTokens":{"description":"Input tokens in this bucket.","type":"number"},"outputTokens":{"description":"Output tokens in this bucket.","type":"number"},"costMicros":{"description":"Billable cost in micros of EUR for this bucket.","type":"number"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/ai-gateway/usage/requests":{"get":{"operationId":"listOrganizationAiGatewayRequests","summary":"List organization AI Gateway requests","description":"Returns request-level AI Gateway events for an organization. Each item includes attribution, authenticated user, optional caller end-user label, model/provider routing, token usage, billable cost, request status, and latency. Filter by time range, app, model, provider, status, request ID, authenticated user, or caller end-user label.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started at or after this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started before or at this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Restrict results to requests attributed to this Network application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"model","in":"query","required":false,"schema":{"description":"Requested model identifier to filter by.","examples":["openai/gpt-4o"],"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"description":"Provider identifier to filter by.","examples":["openai"],"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"default":"pending","description":"Request lifecycle status to filter by.","type":"string","enum":["pending","success","error","cancelled"]}},{"name":"requestId","in":"query","required":false,"schema":{"description":"Gateway request ID returned in `X-Gigadrive-Request-Id`.","examples":["gwreq_123"],"type":"string"}},{"name":"authenticatedUserId","in":"query","required":false,"schema":{"format":"uuid","description":"Authenticated Gigadrive user ID to filter by.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"}},{"name":"callerEndUserId","in":"query","required":false,"schema":{"description":"Application-supplied end-user label from `X-Gigadrive-End-User-Id` or compatible request metadata.","examples":["customer_123"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":500,"description":"Maximum number of request events to return.","anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":500,"description":"Maximum number of request events to return.","type":"number"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","requestId","traceId","billingSubjectType","organizationId","applicationId","actorId","actorType","apiKeyId","authenticatedUserId","callerEndUserId","modelRequested","modelServed","provider","providerAttempts","status","errorCode","errorType","inputTokens","outputTokens","cachedInputTokens","totalTokens","usageSource","providerCostMicros","billableCostMicros","streaming","latencyMs","metadata","startedAt","completedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Stored AI Gateway request event ID.","examples":["0197b2fa-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},"requestId":{"description":"Public Gateway request ID returned to callers.","examples":["gwreq_123"],"type":"string"},"traceId":{"nullable":true,"anyOf":[{"description":"Optional caller-provided trace ID.","type":"string"},{"type":"null"}]},"billingSubjectType":{"default":"organization","description":"Billing subject that owns this request.","type":"string","enum":["organization","application"]},"organizationId":{"format":"uuid","description":"Organization billed for or governing this request.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application billed for this request when application attribution was used.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"actorId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Authenticated actor that made the request.","type":"string"},{"type":"null"}]},"actorType":{"description":"Authenticated actor type, such as user, organization, or application.","type":"string"},"apiKeyId":{"nullable":true,"anyOf":[{"format":"uuid","description":"API key used to obtain the bearer token, if any.","examples":["0197b2fb-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"authenticatedUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Gigadrive user ID when the request used user JWT authentication.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"callerEndUserId":{"nullable":true,"anyOf":[{"description":"Application-supplied end-user label.","type":"string"},{"type":"null"}]},"modelRequested":{"description":"Model requested by the caller.","examples":["openai/gpt-4o"],"type":"string"},"modelServed":{"nullable":true,"anyOf":[{"description":"Model actually served after routing or fallback.","type":"string"},{"type":"null"}]},"provider":{"nullable":true,"anyOf":[{"description":"Provider that served the request.","examples":["openai"],"type":"string"},{"type":"null"}]},"providerAttempts":{"nullable":true,"anyOf":[{"type":"array","items":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"number"},"tag":{"type":"string"}}}},{"type":"null"}]},"status":{"default":"pending","description":"Request lifecycle status.","type":"string","enum":["pending","success","error","cancelled"]},"errorCode":{"nullable":true,"anyOf":[{"description":"Provider or gateway error code for failed requests.","type":"string"},{"type":"null"}]},"errorType":{"nullable":true,"anyOf":[{"description":"Provider or gateway error type for failed requests.","type":"string"},{"type":"null"}]},"inputTokens":{"description":"Input tokens reported or estimated.","type":"number"},"outputTokens":{"description":"Output tokens reported or estimated.","type":"number"},"cachedInputTokens":{"description":"Cached input tokens reported by compatible providers.","type":"number"},"totalTokens":{"description":"Total tokens for this request.","type":"number"},"usageSource":{"default":"provider","description":"Source of token usage data.","type":"string","enum":["provider","estimated","none"]},"providerCostMicros":{"description":"Estimated provider cost in micros of USD (provider list currency; margin analysis only).","type":"number"},"billableCostMicros":{"description":"Billable cost in micros of EUR.","type":"number"},"streaming":{"description":"Whether the request used a streaming response.","type":"boolean"},"latencyMs":{"nullable":true,"anyOf":[{"description":"End-to-end request latency in milliseconds.","type":"number"},{"type":"null"}]},"metadata":{"nullable":true,"anyOf":[{"description":"Non-sensitive request metadata.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},{"type":"null"}]},"startedAt":{"format":"date-time","description":"Timestamp when gateway handling started.","type":"string"},"completedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"Timestamp when gateway handling completed.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"Timestamp when this event row was created.","type":"string"},"updatedAt":{"format":"date-time","description":"Timestamp when this event row was last updated.","type":"string"}}}},"total":{"description":"Number of returned request events.","type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/ai-gateway/usage/export":{"get":{"operationId":"exportOrganizationAiGatewayUsageCsv","summary":"Export organization AI Gateway usage CSV","description":"Exports AI Gateway request events as CSV for offline billing review, finance workflows, or analytics tools. The export uses the same filters as the request log endpoint and defaults to the maximum page size when no limit is supplied.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started at or after this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"format":"date-time","description":"Only include requests that started before or at this timestamp.","examples":["2026-06-03T00:00:00.000Z"],"type":"string"}},{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Restrict results to requests attributed to this Network application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"model","in":"query","required":false,"schema":{"description":"Requested model identifier to filter by.","examples":["openai/gpt-4o"],"type":"string"}},{"name":"provider","in":"query","required":false,"schema":{"description":"Provider identifier to filter by.","examples":["openai"],"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"default":"pending","description":"Request lifecycle status to filter by.","type":"string","enum":["pending","success","error","cancelled"]}},{"name":"requestId","in":"query","required":false,"schema":{"description":"Gateway request ID returned in `X-Gigadrive-Request-Id`.","examples":["gwreq_123"],"type":"string"}},{"name":"authenticatedUserId","in":"query","required":false,"schema":{"format":"uuid","description":"Authenticated Gigadrive user ID to filter by.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"}},{"name":"callerEndUserId","in":"query","required":false,"schema":{"description":"Application-supplied end-user label from `X-Gigadrive-End-User-Id` or compatible request metadata.","examples":["customer_123"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":500,"description":"Maximum number of request events to return.","anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":500,"description":"Maximum number of request events to return.","type":"number"}]}}],"responses":{"200":{"description":"CSV export of AI Gateway request events for the selected filters.","content":{"text/plain":{"schema":{"contentMediaType":"text/csv","description":"CSV export of AI Gateway request events for the selected filters.","type":"string"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/ai-gateway/budgets":{"get":{"operationId":"listOrganizationAiGatewayBudgets","summary":"List organization AI Gateway budgets","description":"Returns AI Gateway budget controls owned by an organization. Budgets can apply organization-wide, to a specific application, to a specific user, or to an app/user combination. Runtime gateway requests are checked against enabled budgets before provider routing.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","organizationId","applicationId","userId","period","maxCostMicros","maxRequests","maxTokens","maxRequestCostMicros","enabled","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Budget ID.","examples":["0197b2fc-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns this budget.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific budget target, or null for organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"userId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User-specific budget target, or null for all users.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"period":{"default":"day","description":"Budget reset period.","type":"string","enum":["day","month"]},"maxCostMicros":{"nullable":true,"anyOf":[{"description":"Maximum spend in micros of EUR.","type":"number"},{"type":"null"}]},"maxRequests":{"nullable":true,"anyOf":[{"description":"Maximum request count.","type":"number"},{"type":"null"}]},"maxTokens":{"nullable":true,"anyOf":[{"description":"Maximum token count.","type":"number"},{"type":"null"}]},"maxRequestCostMicros":{"nullable":true,"anyOf":[{"description":"Maximum cost per request in micros of EUR.","type":"number"},{"type":"null"}]},"enabled":{"description":"Whether this budget is enforced.","type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"put":{"operationId":"replaceOrganizationAiGatewayBudgets","summary":"Replace organization AI Gateway budgets","description":"Replaces all AI Gateway budgets for an organization in one operation. Use this for budget management screens where admins edit organization, app, and per-user limits together. Existing budgets not included in the request are removed.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"description":"Complete replacement set of AI Gateway budgets for this organization. Send an empty array to clear all budgets.","type":"array","items":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific budget target. Null means the budget applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"userId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Optional authenticated user target for per-user budgets. Null means all users in the selected org/app scope.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"period":{"default":"day","description":"Budget reset period.","type":"string","enum":["day","month"]},"maxCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum billable spend in micros of EUR.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum billable spend in micros of EUR.","type":"integer"}]},{"type":"null"}]},"maxRequests":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum request count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum request count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxTokens":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum total token count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum total token count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxRequestCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","type":"integer"}]},{"type":"null"}]},"enabled":{"description":"Whether this budget is enforced.","type":"boolean"}}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"description":"Complete replacement set of AI Gateway budgets for this organization. Send an empty array to clear all budgets.","type":"array","items":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific budget target. Null means the budget applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"userId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Optional authenticated user target for per-user budgets. Null means all users in the selected org/app scope.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"period":{"default":"day","description":"Budget reset period.","type":"string","enum":["day","month"]},"maxCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum billable spend in micros of EUR.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum billable spend in micros of EUR.","type":"integer"}]},{"type":"null"}]},"maxRequests":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum request count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum request count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxTokens":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum total token count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum total token count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxRequestCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","type":"integer"}]},{"type":"null"}]},"enabled":{"description":"Whether this budget is enforced.","type":"boolean"}}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["budgets"],"properties":{"budgets":{"description":"Complete replacement set of AI Gateway budgets for this organization. Send an empty array to clear all budgets.","type":"array","items":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific budget target. Null means the budget applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"userId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Optional authenticated user target for per-user budgets. Null means all users in the selected org/app scope.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"period":{"default":"day","description":"Budget reset period.","type":"string","enum":["day","month"]},"maxCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum billable spend in micros of EUR.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum billable spend in micros of EUR.","type":"integer"}]},{"type":"null"}]},"maxRequests":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum request count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum request count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxTokens":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum total token count allowed in the period.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum total token count allowed in the period.","type":"integer"}]},{"type":"null"}]},"maxRequestCostMicros":{"nullable":true,"anyOf":[{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Maximum estimated or billable cost allowed for a single request.","type":"integer"}]},{"type":"null"}]},"enabled":{"description":"Whether this budget is enforced.","type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","organizationId","applicationId","userId","period","maxCostMicros","maxRequests","maxTokens","maxRequestCostMicros","enabled","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Budget ID.","examples":["0197b2fc-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns this budget.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific budget target, or null for organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"userId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User-specific budget target, or null for all users.","examples":["0197b2f9-7c7d-76f3-a9bd-aaaaaaaaaaaa"],"type":"string"},{"type":"null"}]},"period":{"default":"day","description":"Budget reset period.","type":"string","enum":["day","month"]},"maxCostMicros":{"nullable":true,"anyOf":[{"description":"Maximum spend in micros of EUR.","type":"number"},{"type":"null"}]},"maxRequests":{"nullable":true,"anyOf":[{"description":"Maximum request count.","type":"number"},{"type":"null"}]},"maxTokens":{"nullable":true,"anyOf":[{"description":"Maximum token count.","type":"number"},{"type":"null"}]},"maxRequestCostMicros":{"nullable":true,"anyOf":[{"description":"Maximum cost per request in micros of EUR.","type":"number"},{"type":"null"}]},"enabled":{"description":"Whether this budget is enforced.","type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/organizations/{organizationId}/ai-gateway/policies":{"get":{"operationId":"getOrganizationAiGatewayPolicy","summary":"Get organization AI Gateway policy","description":"Returns the AI Gateway model/provider policy for an organization or a specific application override. Policies define allowed models, allowed providers, fallback behavior, zero-data-retention requirements, and maximum output tokens.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Application-specific policy to load. Omit this value to load the organization-wide default policy.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["policy"],"properties":{"policy":{"nullable":true,"anyOf":[{"type":"object","required":["id","organizationId","applicationId","allowedModels","allowedProviders","requireZdr","allowFallbacks","maxOutputTokens","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Policy ID.","examples":["0197b2fd-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns this policy.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific policy target, or null for organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"allowedModels":{"description":"Allowed model IDs, or null to allow all models.","nullable":true,"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"allowedProviders":{"description":"Allowed provider IDs, or null to allow all providers.","nullable":true,"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"requireZdr":{"description":"Whether zero-data-retention routing is required.","type":"boolean"},"allowFallbacks":{"description":"Whether fallback routing is allowed.","type":"boolean"},"maxOutputTokens":{"nullable":true,"anyOf":[{"description":"Maximum output tokens per request.","type":"number"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"put":{"operationId":"upsertOrganizationAiGatewayPolicy","summary":"Create or update organization AI Gateway policy","description":"Creates or updates the organization-wide AI Gateway policy, or an application-specific policy override when `applicationId` is supplied. Policy changes affect future gateway requests after they are read by the gateway runtime.","tags":["AI Gateway"],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"format":"uuid","description":"Organization whose AI Gateway usage, budgets, or policies should be managed.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific policy target. Null means the policy applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"allowedModels":{"nullable":true,"anyOf":[{"description":"Allowed model IDs. Null allows all models.","type":"array","items":{"examples":["openai/gpt-4o"],"type":"string"}},{"type":"null"}]},"allowedProviders":{"nullable":true,"anyOf":[{"description":"Allowed provider IDs. Null allows all providers.","type":"array","items":{"default":"openrouter","examples":["openai"],"type":"string","enum":["openrouter","deepinfra","togetherai","openai","anthropic","google","google-vertex","amazon-bedrock","xai","alibaba","mistral","deepseek","groq","cerebras","cohere","perplexity","fireworks-ai","huggingface"]}},{"type":"null"}]},"requireZdr":{"description":"Whether requests must use zero-data-retention capable routing.","type":"boolean"},"allowFallbacks":{"description":"Whether the gateway may retry compatible fallback providers.","type":"boolean"},"maxOutputTokens":{"nullable":true,"anyOf":[{"minimum":1,"description":"Maximum output tokens allowed per request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Maximum output tokens allowed per request.","type":"integer"}]},{"type":"null"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific policy target. Null means the policy applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"allowedModels":{"nullable":true,"anyOf":[{"description":"Allowed model IDs. Null allows all models.","type":"array","items":{"examples":["openai/gpt-4o"],"type":"string"}},{"type":"null"}]},"allowedProviders":{"nullable":true,"anyOf":[{"description":"Allowed provider IDs. Null allows all providers.","type":"array","items":{"default":"openrouter","examples":["openai"],"type":"string","enum":["openrouter","deepinfra","togetherai","openai","anthropic","google","google-vertex","amazon-bedrock","xai","alibaba","mistral","deepseek","groq","cerebras","cohere","perplexity","fireworks-ai","huggingface"]}},{"type":"null"}]},"requireZdr":{"description":"Whether requests must use zero-data-retention capable routing.","type":"boolean"},"allowFallbacks":{"description":"Whether the gateway may retry compatible fallback providers.","type":"boolean"},"maxOutputTokens":{"nullable":true,"anyOf":[{"minimum":1,"description":"Maximum output tokens allowed per request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Maximum output tokens allowed per request.","type":"integer"}]},{"type":"null"}]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific policy target. Null means the policy applies organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"allowedModels":{"nullable":true,"anyOf":[{"description":"Allowed model IDs. Null allows all models.","type":"array","items":{"examples":["openai/gpt-4o"],"type":"string"}},{"type":"null"}]},"allowedProviders":{"nullable":true,"anyOf":[{"description":"Allowed provider IDs. Null allows all providers.","type":"array","items":{"default":"openrouter","examples":["openai"],"type":"string","enum":["openrouter","deepinfra","togetherai","openai","anthropic","google","google-vertex","amazon-bedrock","xai","alibaba","mistral","deepseek","groq","cerebras","cohere","perplexity","fireworks-ai","huggingface"]}},{"type":"null"}]},"requireZdr":{"description":"Whether requests must use zero-data-retention capable routing.","type":"boolean"},"allowFallbacks":{"description":"Whether the gateway may retry compatible fallback providers.","type":"boolean"},"maxOutputTokens":{"nullable":true,"anyOf":[{"minimum":1,"description":"Maximum output tokens allowed per request.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Maximum output tokens allowed per request.","type":"integer"}]},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["policy"],"properties":{"policy":{"type":"object","required":["id","organizationId","applicationId","allowedModels","allowedProviders","requireZdr","allowFallbacks","maxOutputTokens","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Policy ID.","examples":["0197b2fd-1111-7000-9000-aaaaaaaaaaaa"],"type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns this policy.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application-specific policy target, or null for organization-wide.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"allowedModels":{"description":"Allowed model IDs, or null to allow all models.","nullable":true,"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"allowedProviders":{"description":"Allowed provider IDs, or null to allow all providers.","nullable":true,"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"requireZdr":{"description":"Whether zero-data-retention routing is required.","type":"boolean"},"allowFallbacks":{"description":"Whether fallback routing is allowed.","type":"boolean"},"maxOutputTokens":{"nullable":true,"anyOf":[{"description":"Maximum output tokens per request.","type":"number"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications":{"post":{"operationId":"createApplication","summary":"Create an application","description":"Creates an application and its default production and preview environments. The generated application ID and default environment slug can be used immediately to create and upload a deployment. User actors must be organization members with Network product access, and while Gigadrive Network is in early access they must also have been let off the waitlist; organization actors may create applications only within their own organization and are not subject to the waitlist.","tags":["Applications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["organizationId","name"],"properties":{"organizationId":{"format":"uuid","description":"Organization that should own the application.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"name":{"minLength":1,"maxLength":255,"description":"Application display name. Surrounding whitespace is removed.","examples":["Website"],"type":"string"},"slug":{"minLength":1,"maxLength":255,"pattern":"^[a-z0-9-]+$","description":"Optional lowercase application slug. Generated from the name when omitted.","examples":["website"],"type":"string"},"rootDirectory":{"maxLength":512,"description":"Optional project directory relative to the repository root.","examples":["apps/web"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["organizationId","name"],"properties":{"organizationId":{"format":"uuid","description":"Organization that should own the application.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"name":{"minLength":1,"maxLength":255,"description":"Application display name. Surrounding whitespace is removed.","examples":["Website"],"type":"string"},"slug":{"minLength":1,"maxLength":255,"pattern":"^[a-z0-9-]+$","description":"Optional lowercase application slug. Generated from the name when omitted.","examples":["website"],"type":"string"},"rootDirectory":{"maxLength":512,"description":"Optional project directory relative to the repository root.","examples":["apps/web"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["organizationId","name"],"properties":{"organizationId":{"format":"uuid","description":"Organization that should own the application.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"name":{"minLength":1,"maxLength":255,"description":"Application display name. Surrounding whitespace is removed.","examples":["Website"],"type":"string"},"slug":{"minLength":1,"maxLength":255,"pattern":"^[a-z0-9-]+$","description":"Optional lowercase application slug. Generated from the name when omitted.","examples":["website"],"type":"string"},"rootDirectory":{"maxLength":512,"description":"Optional project directory relative to the repository root.","examples":["apps/web"],"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","name","slug","imageUrl","rootDirectory","defaultEnvironmentSlug","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Stable UUID for the newly created application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns the application.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"name":{"description":"Application display name.","examples":["Website"],"type":"string"},"slug":{"description":"URL-friendly application identifier, unique within the organization.","examples":["website"],"type":"string"},"imageUrl":{"format":"uri","description":"Application icon URL.","examples":["https://cdn.gigadrivegroup.com/defaultGroup.png"],"type":"string"},"rootDirectory":{"nullable":true,"anyOf":[{"description":"Normalized project directory relative to the repository root, or null for the repository root.","examples":["apps/web"],"type":"string"},{"type":"null"}]},"defaultEnvironmentSlug":{"description":"Environment slug to use for the first production deployment.","examples":["production"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"get":{"operationId":"listApplications","summary":"List applications","description":"Returns Network applications the authenticated actor can access. Applications are deployable projects that own deployments, storage buckets, request logs, and application-scoped environment variables. Pass `organizationId` when a client needs to show or operate on applications inside a specific organization without leaking applications from other organizations.","tags":["Applications"],"parameters":[{"name":"organizationId","in":"query","required":false,"schema":{"description":"Restricts the result to applications owned by this organization.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"description":"Cursor for the next page of list results. Pass the last resource ID returned by the previous page to continue listing from that point within the same filters and authenticated actor scope.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"limit","in":"query","required":true,"schema":{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","organization","name","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organization":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"},"name":{"description":"Application display name shown in the Network console and API clients.","examples":["Website"],"type":"string"},"imageUrl":{"description":"Application icon URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/applications/website.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/application"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}},"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}":{"get":{"operationId":"getApplication","summary":"Get an application","description":"Returns one application with its organization, production hostname label, Git provider, and environments. Use the environment IDs and slugs from this response when creating environment-specific variables, storage buckets, or S3 credentials.","tags":["Applications"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application to read.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","organizationId","name","slug","imageUrl","rootDirectory","productionHostnameLabel","gitProvider","environments","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","description":"Organization that owns the application.","type":"string"},"name":{"type":"string"},"slug":{"description":"URL-safe identifier, unique within the organization.","type":"string"},"imageUrl":{"type":"string"},"rootDirectory":{"description":"Monorepo subdirectory the application is built from, or null for the repository root.","anyOf":[{"type":"string"},{"type":"null"}]},"productionHostnameLabel":{"description":"Production hostname label (`{label}.gigadrive.app`), or null when none is set.","anyOf":[{"type":"string"},{"type":"null"}]},"gitProvider":{"description":"Git provider the application is connected to, or null for upload-only applications.","anyOf":[{"const":"github","type":"string"},{"const":"gitlab","type":"string"},{"type":"null"}]},"environments":{"type":"array","items":{"type":"object","required":["id","name","slug","type","branchPatterns","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Environment UUID, accepted wherever an `environmentId` is expected.","type":"string"},"name":{"description":"Human-readable environment name, such as `Production`.","type":"string"},"slug":{"description":"URL-safe identifier, unique within the application. Accepted as `environment`.","type":"string"},"type":{"description":"`production`, `preview`, `custom`, or `local`.","type":"string"},"branchPatterns":{"description":"Branch names or wildcard patterns whose deployments are routed to this environment.","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/environments":{"get":{"operationId":"listApplicationEnvironments","summary":"List application environments","description":"Returns the environments of an application (production, preview, and any custom or local environments) in creation order. Environment IDs and slugs select the target of environment-specific variables, storage buckets, and S3 credentials.","tags":["Applications"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application to read.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","name","slug","type","branchPatterns","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","description":"Environment UUID, accepted wherever an `environmentId` is expected.","type":"string"},"name":{"description":"Human-readable environment name, such as `Production`.","type":"string"},"slug":{"description":"URL-safe identifier, unique within the application. Accepted as `environment`.","type":"string"},"type":{"description":"`production`, `preview`, `custom`, or `local`.","type":"string"},"branchPatterns":{"description":"Branch names or wildcard patterns whose deployments are routed to this environment.","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/env-vars":{"get":{"operationId":"listApplicationEnvVars","summary":"List application environment variables","description":"Returns environment variables defined directly on an application, including optional environment-specific overrides. Application variables configure one Network application without changing the rest of the organization. Sensitive values are redacted as `null` in API responses.","tags":["Environment Variables"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose variables should be listed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createApplicationEnvVar","summary":"Create application environment variable","description":"Creates an application-scoped environment variable. Use these variables for configuration that belongs to a single Network application, such as application-specific database URLs, feature flags, or provider credentials. Provide `environmentId` to create an environment override; otherwise the variable applies application-wide.","tags":["Environment Variables"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that should receive the variable.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"environmentId":{"format":"uuid","description":"Optional environment override. Omit for an application-wide variable.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"environmentId":{"format":"uuid","description":"Optional environment override. Omit for an application-wide variable.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","required":["key","value"],"properties":{"key":{"minLength":1,"maxLength":255,"description":"Environment variable name, for example `DATABASE_URL`.","examples":["DATABASE_URL"],"type":"string"},"value":{"description":"Environment variable value stored for future deployments and runtime resolution.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"environmentId":{"format":"uuid","description":"Optional environment override. Omit for an application-wide variable.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"sensitive":{"description":"When true, hides the value from future API responses.","examples":[true],"type":"boolean"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/env-vars/pull":{"get":{"operationId":"pullApplicationEnvVars","summary":"Pull resolved application environment variables","description":"Resolves an application’s environment variables for local development by merging organization-wide, application-wide, and (optionally) environment-specific overrides. Only non-sensitive variables are returned — sensitive values are restricted to production/preview environments and are never exposed here — so the result can be written directly to a local `.env` file.","tags":["Environment Variables"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose environment variables should be pulled.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"description":"Optional environment slug to resolve environment-specific overrides on top of the organization and application baseline. Omit for the local development baseline.","examples":["production","preview"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total","omittedSensitive"],"properties":{"items":{"description":"Resolved non-sensitive environment variables, ready to be written to a local `.env` file.","type":"array","items":{"type":"object","required":["key","value","source"],"properties":{"key":{"description":"Environment variable name.","examples":["DATABASE_URL","NEXT_PUBLIC_API_URL"],"type":"string"},"value":{"description":"Resolved variable value. Only non-sensitive variables are returned by the pull endpoint, so this is always the real value.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"source":{"default":"organization","description":"Where the resolved value came from after applying inheritance: an organization-wide variable, an application-wide variable, or an environment-specific override.","type":"string","enum":["organization","application","environment"]}},"$id":"#/components/schemas/resolvedEnvVar"}},"total":{"description":"Number of resolved variables returned.","examples":[12],"type":"number"},"omittedSensitive":{"description":"Number of sensitive variables that were resolved but intentionally omitted (secrets are never returned by this endpoint).","examples":[0],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/env-vars/{envVarId}":{"patch":{"operationId":"updateApplicationEnvVar","summary":"Update application environment variable","description":"Updates an application-scoped environment variable. The variable must belong to the application in the path. Use this to rotate secrets, rename keys, or change whether a value is redacted from API responses. Renames must remain unique within the variable scope.","tags":["Environment Variables"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the variable.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"envVarId","in":"path","required":true,"schema":{"format":"uuid","description":"Environment variable to update.","examples":["0197b2f3-4d6f-7e2a-8c4b-444444444444"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"key":{"minLength":1,"maxLength":255,"description":"New environment variable name.","examples":["REDIS_URL"],"type":"string"},"value":{"description":"New environment variable value.","examples":["redis://redis.example.com:6379"],"type":"string"},"sensitive":{"description":"Whether future API responses should hide the value.","examples":[true],"type":"boolean"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"deleteApplicationEnvVar","summary":"Delete application environment variable","description":"Deletes an application-scoped environment variable. This removes the value from future deployment and runtime configuration resolution for the application, while existing deployed artifacts keep whatever configuration was already applied to them.","tags":["Environment Variables"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the variable.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"envVarId","in":"path","required":true,"schema":{"format":"uuid","description":"Environment variable to delete.","examples":["0197b2f3-4d6f-7e2a-8c4b-444444444444"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The application environment variable was removed.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets":{"get":{"operationId":"listStorageBuckets","summary":"List storage buckets","description":"Returns buckets for one environment when an environment slug or UUID is supplied. Deployment credentials are always restricted to their inferred environment. Omitting the selector for management credentials preserves the legacy application-wide list.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose storage buckets should be listed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","applicationId","name","slug","visibility","cdnHostname","environmentId","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","deprecated":true,"description":"Internal bucket UUID. Accepted by bucket-scoped API routes only as a deprecated compatibility fallback.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Network application that owns this bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical immutable API and IaC identifier. The lowercase URL-safe, non-UUID name is unique within the bucket environment.","examples":["user-uploads"],"type":"string"},"slug":{"description":"Globally unique delivery and S3 identifier used in CDN hostnames and S3-compatible bucket addressing. It is generated by the API for canonical clients.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Bucket access policy. Public buckets can serve objects through the CDN hostname; private buckets require signed access URLs.","type":"string","enum":["public","private"]},"cdnHostname":{"description":"Hostname clients use to read public objects or signed private object URLs.","examples":["website-user-uploads.public.gigadriveuserstorage.com"],"type":"string"},"environmentId":{"format":"uuid","description":"Application environment this bucket belongs to.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageBucket"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createStorageBucket","summary":"Create environment-scoped storage bucket","description":"Creates a bucket with an immutable environment-scoped name. Select the environment by slug or UUID; deployment credentials infer it. The API generates the globally unique delivery/S3 slug unless the deprecated `slug` compatibility field is supplied.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that should own the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"environment":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"environmentId":{"format":"uuid","deprecated":true,"description":"Deprecated environment UUID compatibility field. Use `environment` instead.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Immutable, lowercase, URL-safe, non-UUID bucket identifier. It is unique within the selected environment and is not normalized by the API.","examples":["user-uploads"],"type":"string"},"slug":{"minLength":1,"maxLength":63,"deprecated":true,"description":"Deprecated explicit global delivery/S3 slug. New clients should omit it and let the API generate one.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Whether objects can be served publicly or require signed access.","examples":["private"],"type":"string","enum":["public","private"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name"],"properties":{"environment":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"environmentId":{"format":"uuid","deprecated":true,"description":"Deprecated environment UUID compatibility field. Use `environment` instead.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Immutable, lowercase, URL-safe, non-UUID bucket identifier. It is unique within the selected environment and is not normalized by the API.","examples":["user-uploads"],"type":"string"},"slug":{"minLength":1,"maxLength":63,"deprecated":true,"description":"Deprecated explicit global delivery/S3 slug. New clients should omit it and let the API generate one.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Whether objects can be served publicly or require signed access.","examples":["private"],"type":"string","enum":["public","private"]}}}},"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"environment":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"environmentId":{"format":"uuid","deprecated":true,"description":"Deprecated environment UUID compatibility field. Use `environment` instead.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Immutable, lowercase, URL-safe, non-UUID bucket identifier. It is unique within the selected environment and is not normalized by the API.","examples":["user-uploads"],"type":"string"},"slug":{"minLength":1,"maxLength":63,"deprecated":true,"description":"Deprecated explicit global delivery/S3 slug. New clients should omit it and let the API generate one.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Whether objects can be served publicly or require signed access.","examples":["private"],"type":"string","enum":["public","private"]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","name","slug","visibility","cdnHostname","environmentId","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","deprecated":true,"description":"Internal bucket UUID. Accepted by bucket-scoped API routes only as a deprecated compatibility fallback.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Network application that owns this bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical immutable API and IaC identifier. The lowercase URL-safe, non-UUID name is unique within the bucket environment.","examples":["user-uploads"],"type":"string"},"slug":{"description":"Globally unique delivery and S3 identifier used in CDN hostnames and S3-compatible bucket addressing. It is generated by the API for canonical clients.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Bucket access policy. Public buckets can serve objects through the CDN hostname; private buckets require signed access URLs.","type":"string","enum":["public","private"]},"cdnHostname":{"description":"Hostname clients use to read public objects or signed private object URLs.","examples":["website-user-uploads.public.gigadriveuserstorage.com"],"type":"string"},"environmentId":{"format":"uuid","description":"Application environment this bucket belongs to.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageBucket"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/uploads":{"post":{"operationId":"createStorageUploadSession","summary":"Create storage upload session by bucket name","description":"Creates a resumable upload session in a bucket addressed by its environment-scoped name or deprecated UUID. Deployment credentials infer the environment; management credentials provide the environment slug or UUID. A `contentLength` of 0 writes the empty object during this request: the session is returned `completed`, `upload` is null, `object` holds the stored object and `publicObjectUrl` addresses it.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","contentLength","checksumSha256"],"properties":{"key":{"minLength":1,"maxLength":1024,"description":"Object key/path to create inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"minLength":1,"maxLength":255,"description":"Declared MIME type for the object.","examples":["image/png"],"type":"string"},"contentLength":{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"type":"integer"}]},"checksumSha1":{"minLength":40,"maxLength":40,"pattern":"^[0-9a-f]{40}$","description":"Optional lowercase hex SHA-1 checksum.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},"checksumSha256":{"minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Required lowercase hex SHA-256 checksum. The server hashes the uploaded bytes and rejects a mismatch.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},"checksumMd5":{"minLength":32,"maxLength":32,"pattern":"^[0-9a-f]{32}$","description":"Optional lowercase hex MD5 checksum.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["key","contentLength","checksumSha256"],"properties":{"key":{"minLength":1,"maxLength":1024,"description":"Object key/path to create inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"minLength":1,"maxLength":255,"description":"Declared MIME type for the object.","examples":["image/png"],"type":"string"},"contentLength":{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"type":"integer"}]},"checksumSha1":{"minLength":40,"maxLength":40,"pattern":"^[0-9a-f]{40}$","description":"Optional lowercase hex SHA-1 checksum.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},"checksumSha256":{"minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Required lowercase hex SHA-256 checksum. The server hashes the uploaded bytes and rejects a mismatch.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},"checksumMd5":{"minLength":32,"maxLength":32,"pattern":"^[0-9a-f]{32}$","description":"Optional lowercase hex MD5 checksum.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["key","contentLength","checksumSha256"],"properties":{"key":{"minLength":1,"maxLength":1024,"description":"Object key/path to create inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"minLength":1,"maxLength":255,"description":"Declared MIME type for the object.","examples":["image/png"],"type":"string"},"contentLength":{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"maximum":5497558138880,"description":"Exact object size in bytes, at most 5 TiB. 0 writes an empty object immediately and returns a completed session with no upload instruction.","examples":[5242880],"type":"integer"}]},"checksumSha1":{"minLength":40,"maxLength":40,"pattern":"^[0-9a-f]{40}$","description":"Optional lowercase hex SHA-1 checksum.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},"checksumSha256":{"minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Required lowercase hex SHA-256 checksum. The server hashes the uploaded bytes and rejects a mismatch.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},"checksumMd5":{"minLength":32,"maxLength":32,"pattern":"^[0-9a-f]{32}$","description":"Optional lowercase hex MD5 checksum.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["session","upload","object","publicObjectUrl"],"properties":{"session":{"type":"object","required":["id","bucketId","applicationId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","state","expiresAt","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that will receive the uploaded object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and upload session.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"key":{"description":"Final object key/path inside the bucket once the upload completes.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"MIME type declared by the client for the object, or null if none was supplied.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"nullable":true,"anyOf":[{"description":"Exact upload size in bytes declared when the session was created.","examples":[5242880],"type":"number"},{"type":"null"}]},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum declared for upload validation, or null when not supplied.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum used to validate the uploaded object content.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum declared for compatibility checks, or null when not supplied.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"},{"type":"null"}]},"state":{"default":"pending","description":"Upload lifecycle state. Pending sessions are still accepting bytes, completed sessions produced an object, and expired or failed sessions should not be reused.","type":"string","enum":["pending","ready","completed","failed","expired"]},"expiresAt":{"format":"date-time","description":"ISO 8601 timestamp after which the generated upload URL can no longer be used.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},"uploadedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the object upload completed, or null while pending.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageUploadSession"},"upload":{"nullable":true,"anyOf":[{"description":"Where to send the upload bytes. Null when `contentLength` is 0: the empty object already exists and the session is `completed`.","type":"object","required":["method","url","headers","publicObjectUrl"],"properties":{"method":{"const":"PATCH","type":"string"},"url":{"format":"uri","description":"Pre-authorized resumable upload URL. Send upload bytes to this URL using the returned method and headers.","examples":["https://api.gigadrive.network/files/0197b2f6-7082-712d-9f7e-777777777777?upload_token=..."],"type":"string"},"headers":{"type":"object","required":["Tus-Resumable"],"properties":{"Tus-Resumable":{"description":"TUS protocol version header that must be included when uploading bytes to the generated URL.","examples":["1.0.0"],"type":"string"}}},"publicObjectUrl":{"format":"uri","description":"Canonical object URL that will address the uploaded object after the session completes. Private buckets still require signed access for reads.","examples":["https://website-user-uploads.public.gigadriveuserstorage.com/avatars/user-123.png"],"type":"string"}}},{"type":"null"}]},"object":{"description":"The stored object when the upload finished during this request, which happens only for an empty file. Null while bytes are still expected.","nullable":true,"anyOf":[{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageObject"},{"type":"null"}]},"publicObjectUrl":{"format":"uri","description":"Canonical object URL for the key, present for every size. Same value as `upload.publicObjectUrl` when an upload instruction is returned. Private buckets still require signed access for reads.","examples":["https://website-user-uploads.public.gigadriveuserstorage.com/avatars/user-123.png"],"type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"get":{"operationId":"listStorageUploadSessions","summary":"List storage upload sessions","description":"Returns resumable upload sessions for a bucket addressed by its environment-scoped name. Deployed workloads infer their environment; UUID references remain deprecated.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","bucketId","applicationId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","state","expiresAt","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that will receive the uploaded object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and upload session.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"key":{"description":"Final object key/path inside the bucket once the upload completes.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"MIME type declared by the client for the object, or null if none was supplied.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"nullable":true,"anyOf":[{"description":"Exact upload size in bytes declared when the session was created.","examples":[5242880],"type":"number"},{"type":"null"}]},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum declared for upload validation, or null when not supplied.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum used to validate the uploaded object content.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum declared for compatibility checks, or null when not supplied.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"},{"type":"null"}]},"state":{"default":"pending","description":"Upload lifecycle state. Pending sessions are still accepting bytes, completed sessions produced an object, and expired or failed sessions should not be reused.","type":"string","enum":["pending","ready","completed","failed","expired"]},"expiresAt":{"format":"date-time","description":"ISO 8601 timestamp after which the generated upload URL can no longer be used.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},"uploadedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the object upload completed, or null while pending.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageUploadSession"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}":{"get":{"operationId":"getStorageBucket","summary":"Get storage bucket by name","description":"Returns a bucket addressed by its canonical environment-scoped name or deprecated UUID fallback. Deployment credentials infer the environment; management credentials provide an environment slug or UUID.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","name","slug","visibility","cdnHostname","environmentId","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","deprecated":true,"description":"Internal bucket UUID. Accepted by bucket-scoped API routes only as a deprecated compatibility fallback.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Network application that owns this bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical immutable API and IaC identifier. The lowercase URL-safe, non-UUID name is unique within the bucket environment.","examples":["user-uploads"],"type":"string"},"slug":{"description":"Globally unique delivery and S3 identifier used in CDN hostnames and S3-compatible bucket addressing. It is generated by the API for canonical clients.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Bucket access policy. Public buckets can serve objects through the CDN hostname; private buckets require signed access URLs.","type":"string","enum":["public","private"]},"cdnHostname":{"description":"Hostname clients use to read public objects or signed private object URLs.","examples":["website-user-uploads.public.gigadriveuserstorage.com"],"type":"string"},"environmentId":{"format":"uuid","description":"Application environment this bucket belongs to.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageBucket"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"deleteStorageBucket","summary":"Delete storage bucket","description":"Deletes an empty storage bucket addressed by its environment-scoped name. UUID references remain available as a deprecated compatibility fallback. Buckets that still contain objects return `409`.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The empty storage bucket was deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/objects":{"get":{"operationId":"listStorageObjects","summary":"List storage objects","description":"Lists objects in a bucket addressed by its environment-scoped name. Deployed workloads infer the environment; management callers pass `environment`. UUID references remain as a deprecated fallback.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}},{"name":"prefix","in":"query","required":false,"schema":{"description":"Filter objects by key prefix (e.g. \"images/photos/\")","examples":["avatars/"],"type":"string"}},{"name":"delimiter","in":"query","required":false,"schema":{"minLength":1,"description":"Delimiter for computing common prefixes (default \"/\")","examples":["/"],"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Cursor for pagination (last object key from previous page)","examples":["avatars/user-123.png"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":1000,"description":"Maximum objects to return (default 200)","examples":[100],"type":"number"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","commonPrefixes","nextCursor","total"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageObject"}},"commonPrefixes":{"type":"array","items":{"description":"Virtual folder prefixes at this level","type":"string"}},"nextCursor":{"nullable":true,"anyOf":[{"description":"Cursor for next page, null if no more results","examples":["avatars/user-123.png"],"type":"string"},{"type":"null"}]},"total":{"description":"Total number of objects matching the prefix","examples":[250],"type":"number"}},"additionalProperties":false}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/objects/{objectId}":{"get":{"operationId":"getStorageObject","summary":"Get storage object","description":"Returns object metadata from a bucket addressed by its environment-scoped name. The environment is inferred for deployed workloads or supplied with `environment`; UUID references are deprecated.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"format":"uuid","description":"Stored object to retrieve.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageObject"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"deleteStorageObject","summary":"Delete storage object","description":"Deletes an object from a bucket addressed by its environment-scoped name. Deployed workloads infer and are restricted to their deployment environment.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"format":"uuid","description":"Stored object to delete.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The storage object was deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/objects/{objectId}/access-url":{"get":{"operationId":"createStorageObjectAccessUrl","summary":"Create storage object access URL","description":"Creates an object access URL from a bucket addressed by its environment-scoped name. Deployed workloads infer the environment; management callers pass `environment`. UUID references remain deprecated compatibility fallbacks.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"format":"uuid","description":"Stored object that should be accessed.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}},{"name":"expiresInSeconds","in":"query","required":false,"schema":{"minimum":60,"maximum":86400,"description":"Requested signed URL lifetime in seconds. Values are clamped between 60 seconds and 24 hours.","examples":[900],"type":"number"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["accessType","url","expiresAt"],"properties":{"accessType":{"default":"public","description":"`public` means the URL is a stable CDN URL. `signed` means the URL grants temporary access to a private object.","type":"string","enum":["public","signed"]},"url":{"format":"uri","description":"URL clients can use to download the object according to the bucket visibility policy.","examples":["https://website-user-uploads.public.gigadriveuserstorage.com/avatars/user-123.png"],"type":"string"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"Expiration timestamp for signed private-object URLs. Public URLs return null because they do not expire.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/storageObjectAccess"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/trash":{"get":{"operationId":"listStorageTrash","summary":"List trashed objects by bucket name","description":"Lists soft-deleted objects in a bucket addressed by its environment-scoped name or deprecated UUID. Deployment credentials infer the environment.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}},{"name":"prefix","in":"query","required":false,"schema":{"description":"Filter trashed objects by key prefix (e.g. \"images/photos/\")","examples":["avatars/"],"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Cursor for pagination (from `nextCursor` of the previous page)","examples":["1751360400000|0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":1000,"description":"Maximum trashed objects to return (default 200)","examples":[100],"type":"number"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor","total"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt","deletedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"},"deletedAt":{"format":"date-time","description":"ISO 8601 timestamp when the object was moved to the trash.","examples":["2026-07-01T09:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/trashedStorageObject"}},"nextCursor":{"nullable":true,"anyOf":[{"description":"Cursor for next page, null if no more results","type":"string"},{"type":"null"}]},"total":{"description":"Total number of trashed objects matching the prefix","examples":[12],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"emptyStorageTrash","summary":"Empty storage bucket trash by bucket name","description":"Permanently deletes every soft-deleted object in a bucket addressed by its environment-scoped name or deprecated UUID. Deployment credentials infer the environment.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["purgedCount"],"properties":{"purgedCount":{"description":"Number of trashed objects that were permanently deleted.","type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/trash/{objectId}/restore":{"post":{"operationId":"restoreStorageObject","summary":"Restore trashed object by bucket name","description":"Restores a soft-deleted object in a bucket addressed by its environment-scoped name or deprecated UUID. Deployment credentials infer the environment. Fails with 409 when a live object already exists at the same key.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"format":"uuid","description":"Trashed object to restore.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageObject"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/trash/{objectId}":{"delete":{"operationId":"purgeStorageObject","summary":"Permanently delete trashed object by bucket name","description":"Permanently deletes a soft-deleted object from a bucket addressed by its environment-scoped name or deprecated UUID. Deployment credentials infer the environment.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"format":"uuid","description":"Trashed object to permanently delete.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The trashed object was permanently deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/buckets/{bucketRef}/uploads/{uploadSessionId}":{"get":{"operationId":"getStorageUploadSession","summary":"Get storage upload session","description":"Returns a resumable upload session from a bucket addressed by its environment-scoped name. Environment inference is automatic for deployed workloads.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"bucketRef","in":"path","required":true,"schema":{"minLength":3,"maxLength":63,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Canonical environment-scoped bucket name. A bucket UUID is accepted as a deprecated compatibility fallback.","examples":["user-uploads","0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"uploadSessionId","in":"path","required":true,"schema":{"format":"uuid","description":"Upload session to retrieve.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","bucketId","applicationId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","state","expiresAt","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that will receive the uploaded object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and upload session.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"key":{"description":"Final object key/path inside the bucket once the upload completes.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"MIME type declared by the client for the object, or null if none was supplied.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"nullable":true,"anyOf":[{"description":"Exact upload size in bytes declared when the session was created.","examples":[5242880],"type":"number"},{"type":"null"}]},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum declared for upload validation, or null when not supplied.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum used to validate the uploaded object content.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum declared for compatibility checks, or null when not supplied.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"},{"type":"null"}]},"state":{"default":"pending","description":"Upload lifecycle state. Pending sessions are still accepting bytes, completed sessions produced an object, and expired or failed sessions should not be reused.","type":"string","enum":["pending","ready","completed","failed","expired"]},"expiresAt":{"format":"date-time","description":"ISO 8601 timestamp after which the generated upload URL can no longer be used.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},"uploadedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the object upload completed, or null while pending.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageUploadSession"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/s3-credentials":{"get":{"operationId":"listStorageS3Credentials","summary":"List S3 credentials","description":"Lists S3 access keys for an application. Secret access keys are never returned.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to one environment.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","applicationId","environmentId","description","accessKeyId","createdByUserId","lastUsedAt","revokedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"environmentId":{"format":"uuid","type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"accessKeyId":{"description":"Public S3 access key id used in the SigV4 Credential field.","type":"string"},"createdByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who minted the credential; null for API-key or system-created keys.","type":"string"},{"type":"null"}]},"lastUsedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createStorageS3Credential","summary":"Create S3 credential","description":"Creates an S3-compatible access key (access key id + secret) scoped to one application environment. The secret access key is returned only once. Use these credentials with any S3 client (path-style endpoint, `forcePathStyle`).","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environmentId"],"properties":{"environmentId":{"format":"uuid","description":"Environment whose buckets the credential may access.","type":"string"},"description":{"maxLength":255,"description":"Optional label shown in the console.","type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["environmentId"],"properties":{"environmentId":{"format":"uuid","description":"Environment whose buckets the credential may access.","type":"string"},"description":{"maxLength":255,"description":"Optional label shown in the console.","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["environmentId"],"properties":{"environmentId":{"format":"uuid","description":"Environment whose buckets the credential may access.","type":"string"},"description":{"maxLength":255,"description":"Optional label shown in the console.","type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["credential","accessKeyId","secretAccessKey"],"properties":{"credential":{"type":"object","required":["id","applicationId","environmentId","description","accessKeyId","createdByUserId","lastUsedAt","revokedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"environmentId":{"format":"uuid","type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"accessKeyId":{"description":"Public S3 access key id used in the SigV4 Credential field.","type":"string"},"createdByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who minted the credential; null for API-key or system-created keys.","type":"string"},{"type":"null"}]},"lastUsedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}},"accessKeyId":{"type":"string"},"secretAccessKey":{"description":"Secret access key. Shown ONCE at creation — store it securely; it cannot be retrieved later.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/storage/s3-credentials/{credentialId}":{"delete":{"operationId":"revokeStorageS3Credential","summary":"Revoke S3 credential","description":"Revokes an S3 access key. Revocation is immediate (fails closed) and irreversible; in-flight presigned URLs signed with the key stop working.","tags":["Storage"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}},{"name":"credentialId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","environmentId","description","accessKeyId","createdByUserId","lastUsedAt","revokedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"environmentId":{"format":"uuid","type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"accessKeyId":{"description":"Public S3 access key id used in the SigV4 Credential field.","type":"string"},"createdByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who minted the credential; null for API-key or system-created keys.","type":"string"},{"type":"null"}]},"lastUsedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/queues":{"get":{"operationId":"listQueues","summary":"List queues with live depth","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queues.","type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]},"post":{"operationId":"createQueue","summary":"Create a queue","description":"Creates a push queue (with `consumerPath`) or a pull queue (without). Sending to a name that does not exist also creates a pull queue with defaults.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queues.","type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}":{"get":{"operationId":"getQueue","summary":"Get a queue with live depth","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]},"put":{"operationId":"ensureQueue","summary":"Create or update a queue","description":"Idempotent: creates the queue with these settings, or applies them to the existing queue.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}},"patch":{"operationId":"updateQueue","summary":"Update queue settings","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}},"delete":{"operationId":"deleteQueue","summary":"Delete a queue and its messages","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]}},"/applications/{applicationId}/queues/{queue}/pause":{"post":{"operationId":"pauseQueue","summary":"Pause delivery","description":"Sends are still accepted; nothing is delivered or received until the queue is resumed.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/resume":{"post":{"operationId":"resumeQueue","summary":"Resume delivery","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/purge":{"post":{"operationId":"purgeQueue","summary":"Delete messages","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/redrive":{"post":{"operationId":"redriveQueue","summary":"Retry dead letters","description":"Moves dead letters back to the queue with a fresh attempt budget.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/messages":{"post":{"operationId":"sendQueueMessages","summary":"Send messages","description":"Sends one message (fields at the top level) or up to 100 (`messages`). Supports delays and scheduled delivery up to a year ahead, ordering groups, deduplication keys and deployment pinning.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}},"get":{"operationId":"listQueueMessages","summary":"Browse messages","description":"Lists messages in one state without leasing them. Bodies are cut to a 4 KiB preview.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"default":"ready","type":"string","enum":["ready","scheduled","inflight","dead"]}},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"maximum":1000000,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":0,"maximum":1000000,"type":"number"}]}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":100,"type":"number"}]}}]}},"/applications/{applicationId}/queues/{queue}/messages/receive":{"post":{"operationId":"receiveQueueMessages","summary":"Lease messages (pull)","description":"Leases up to `maxMessages` deliverable messages for `visibilityTimeoutSeconds`. With `waitSeconds` (at most 20) the call long-polls: it waits up to that long and returns as soon as a message is ready. Without it, the call returns at once. A paused queue returns no messages. Acknowledge each message with its receipt before the lease ends, or it is redelivered.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/messages/{messageId}":{"get":{"operationId":"getQueueMessage","summary":"Get a message","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"format":"uuid","description":"Message id returned by a send or a receive.","type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]},"delete":{"operationId":"deleteQueueMessage","summary":"Delete or cancel a message","description":"Cancels a message that has not been delivered yet, such as a scheduled send. A message being delivered or dead-lettered answers 400.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"format":"uuid","description":"Message id returned by a send or a receive.","type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]}},"/applications/{applicationId}/queues/{queue}/messages/ack":{"post":{"operationId":"ackQueueMessages","summary":"Acknowledge a batch of leased messages","description":"Acknowledges up to 100 leased messages in one call, each settling on its own: `results` reports, in order, which were acknowledged and why any were not (`message_not_found`, `receipt_mismatch`). A batch counts one operation per started ten acknowledged messages.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/messages/{messageId}/ack":{"post":{"operationId":"ackQueueMessage","summary":"Acknowledge (delete) a leased message","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"format":"uuid","description":"Message id returned by a send or a receive.","type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/messages/{messageId}/nack":{"post":{"operationId":"nackQueueMessage","summary":"Release a leased message for retry","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"format":"uuid","description":"Message id returned by a send or a receive.","type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/messages/{messageId}/extend":{"post":{"operationId":"extendQueueMessageLease","summary":"Extend a lease","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"messageId","in":"path","required":true,"schema":{"format":"uuid","description":"Message id returned by a send or a receive.","type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/schedules":{"get":{"operationId":"listQueueSchedules","summary":"List recurring sends","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]},"post":{"operationId":"createQueueSchedule","summary":"Create a recurring send","description":"Publishes `body` into the queue on a cron, evaluated in an IANA time zone.","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the queue.","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/queues/{queue}/schedules/{schedule}":{"patch":{"operationId":"updateQueueSchedule","summary":"Update a recurring send","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"schedule","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"type":"string"}}],"requestBody":{"content":{},"required":true}},"delete":{"operationId":"deleteQueueSchedule","summary":"Delete a recurring send","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"schedule","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"pattern":"^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$","description":"Environment slug or UUID. UUID-shaped values are resolved as IDs. Deployed workload credentials infer this automatically; an explicit value must match that inferred environment.","examples":["production","0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"}}]}},"/applications/{applicationId}/queues/{queue}/schedules/{schedule}/trigger":{"post":{"operationId":"triggerQueueSchedule","summary":"Run a recurring send now","tags":["Queues"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","type":"string"}},{"name":"queue","in":"path","required":true,"schema":{"minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_][A-Za-z0-9_.~:@+=-]{0,254}$","description":"Queue name, unique within the environment and case-sensitive: letters, digits and `_ . ~ : @ + = -`, starting with a letter, digit or underscore.","examples":["emails"],"type":"string"}},{"name":"schedule","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"type":"string"}}],"requestBody":{"content":{},"required":true}}},"/applications/{applicationId}/requests":{"get":{"operationId":"listApplicationRequests","summary":"List application request logs","description":"Returns traffic records captured by Gigadrive Network routing for one application. Request logs connect product resources to live traffic: a record can reference a deployment, function, static asset, storage bucket, or storage object. Use filters to build observability views, debug cache behavior, inspect regional routing, or audit which paths were served during a deployment window.","tags":["Request Logs"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose routed request logs should be listed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"deploymentId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to requests served by one deployment.","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}},{"name":"deploymentFunctionId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to requests served by one function route.","examples":["0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa"],"type":"string"}},{"name":"deploymentAssetId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to requests served by one static asset route.","examples":["0197b2fb-c5d7-7672-9ec3-bbbbbbbbbbbb"],"type":"string"}},{"name":"storageBucketId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to storage delivery requests for one bucket.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"}},{"name":"storageObjectId","in":"query","required":false,"schema":{"format":"uuid","description":"Filter to storage delivery requests for one object.","examples":["0197b2f5-6f81-701c-8e6d-666666666666"],"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"format":"date-time","description":"Inclusive lower bound for request start time.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"format":"date-time","description":"Inclusive upper bound for request start time.","examples":["2026-06-03T13:00:00.000Z"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":1000,"description":"Maximum number of request records to return.","examples":[100],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"description":"Maximum number of request records to return.","examples":[100],"type":"integer"}]}},{"name":"cursor","in":"query","required":false,"schema":{"format":"uuid","description":"Cursor from the previous page.","examples":["0197b2f7-8193-723e-8a8f-888888888888"],"type":"string"}},{"name":"method","in":"query","required":false,"schema":{"minLength":1,"maxLength":16,"description":"HTTP method filter, for example `GET` or `POST`.","examples":["GET"],"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"minimum":100,"maximum":599,"description":"Exact HTTP response status filter.","examples":[200],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":100,"maximum":599,"description":"Exact HTTP response status filter.","examples":[200],"type":"integer"}]}},{"name":"statusFamily","in":"query","required":false,"schema":{"minimum":2,"maximum":5,"description":"HTTP status family filter such as `2` for 2xx.","examples":[2],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":2,"maximum":5,"description":"HTTP status family filter such as `2` for 2xx.","examples":[2],"type":"integer"}]}},{"name":"hostname","in":"query","required":false,"schema":{"minLength":1,"maxLength":255,"description":"Request hostname filter.","examples":["www.example.com"],"type":"string"}},{"name":"pathPrefix","in":"query","required":false,"schema":{"minLength":1,"description":"Literal request path prefix filter.","examples":["/api/"],"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code filter.","examples":["DE"],"type":"string"}},{"name":"region","in":"query","required":false,"schema":{"minLength":1,"maxLength":64,"description":"Function or origin region filter.","examples":["eu-central-1"],"type":"string"}},{"name":"edgeLocation","in":"query","required":false,"schema":{"minLength":1,"maxLength":32,"description":"Edge location identifier filter.","examples":["fra1"],"type":"string"}},{"name":"cacheStatus","in":"query","required":false,"schema":{"description":"CDN cache status filter.","examples":["hit"],"type":"string","enum":["hit","miss","bypass","revalidated","stale","updating"]}},{"name":"cacheHit","in":"query","required":false,"schema":{"description":"Filters by whether the response was served from cache.","examples":[true],"type":"boolean"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor","total"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","application","deployment","deploymentFunction","deploymentAsset","storageBucket","storageObject","request","response","metrics","timings","startedAt","completedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"application":{"type":"object","required":["id","name"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Application that received and routed this request.","type":"string"}}},"deployment":{"description":"Deployment associated with the request when traffic matched deployed code or assets.","nullable":true,"anyOf":[{"type":"object","required":["id","status"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"}}},{"type":"null"}]},"deploymentFunction":{"description":"Function route that handled the request, or null when the request did not execute a function.","nullable":true,"anyOf":[{"type":"object","required":["id","name","path","region"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"nullable":true,"anyOf":[{"description":"Function display name configured for the route, or null if unnamed.","type":"string"},{"type":"null"}]},"path":{"description":"Application route path that matched this serverless function.","type":"string"},"region":{"nullable":true,"anyOf":[{"description":"Execution region that handled the function request, or null if not recorded.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"deploymentAsset":{"description":"Static deployment asset that handled the request, or null when the request was not served from an asset.","nullable":true,"anyOf":[{"type":"object","required":["id","path","objectKey"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"path":{"description":"Application route path that matched this static deployment asset.","type":"string"},"objectKey":{"description":"Storage object key backing the served static asset.","type":"string"}}},{"type":"null"}]},"storageBucket":{"description":"Storage bucket involved in the request when traffic was served through Network storage.","nullable":true,"anyOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Storage bucket that served this object request.","type":"string"},"slug":{"description":"Bucket slug used in the storage serving hostname.","type":"string"}}},{"type":"null"}]},"storageObject":{"description":"Storage object involved in the request when a concrete object was served.","nullable":true,"anyOf":[{"type":"object","required":["id","key","contentType"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Object key/path served by this storage request.","type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Stored object MIME type, or null when unknown.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"request":{"type":"object","required":["method","hostname","path","query","protocol","country","userAgent","referer"],"properties":{"method":{"description":"HTTP method sent by the client, such as `GET`, `POST`, or `PATCH`.","type":"string"},"hostname":{"description":"Hostname that received the request, including custom domains and storage hostnames.","type":"string"},"path":{"description":"URL path used for route matching inside Network routing.","type":"string"},"query":{"nullable":true,"anyOf":[{"description":"Sanitized query string without the leading `?`, or null when no query was recorded.","type":"string"},{"type":"null"}]},"protocol":{"nullable":true,"anyOf":[{"description":"Protocol observed by the edge, usually `https`.","type":"string"},{"type":"null"}]},"country":{"nullable":true,"anyOf":[{"description":"ISO 3166-1 alpha-2 country code inferred at the edge, or null if unavailable.","type":"string"},{"type":"null"}]},"userAgent":{"nullable":true,"anyOf":[{"description":"Sanitized client User-Agent header used for debugging traffic sources.","type":"string"},{"type":"null"}]},"referer":{"nullable":true,"anyOf":[{"description":"Sanitized Referer header used for debugging traffic origins.","type":"string"},{"type":"null"}]}}},"response":{"type":"object","required":["status","cacheStatus","cacheHit","region","edgeLocation"],"properties":{"status":{"nullable":true,"anyOf":[{"description":"HTTP status code returned to the client, or null if the request did not complete.","type":"number"},{"type":"null"}]},"cacheStatus":{"nullable":true,"anyOf":[{"default":"hit","description":"CDN cache state recorded for this request when cache metadata was available.","type":"string","enum":["hit","miss","bypass","revalidated","stale","updating"]},{"type":"null"}]},"cacheHit":{"nullable":true,"anyOf":[{"description":"Whether the response body was served from cache instead of the origin/runtime.","type":"boolean"},{"type":"null"}]},"region":{"nullable":true,"anyOf":[{"description":"Function or storage origin region that handled the request.","type":"string"},{"type":"null"}]},"edgeLocation":{"nullable":true,"anyOf":[{"description":"Edge location identifier closest to the client for this request.","type":"string"},{"type":"null"}]}}},"metrics":{"type":"object","required":["requestBodyBytes","responseBodyBytes","bytesSent","durationMs"],"properties":{"requestBodyBytes":{"nullable":true,"anyOf":[{"description":"Client request body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"responseBodyBytes":{"nullable":true,"anyOf":[{"description":"Origin/runtime response body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"bytesSent":{"nullable":true,"anyOf":[{"description":"Total bytes sent from Network edge to the client.","type":"number"},{"type":"null"}]},"durationMs":{"nullable":true,"anyOf":[{"description":"End-to-end request duration observed by Network, in milliseconds.","type":"number"},{"type":"null"}]}}},"timings":{"description":"Phases of `metrics.durationMs`. Each is null when it was not measured or the request did not go through it; when measured, the three add up to `metrics.durationMs`.","type":"object","required":["edgeMs","coldStartMs","functionMs"],"properties":{"edgeMs":{"nullable":true,"anyOf":[{"description":"Edge time: `metrics.durationMs` minus cold start and function time, i.e. routing, admission, asset reads and, for CDN-fronted requests, the CDN hop, in ms.","type":"number"},{"type":"null"}]},"coldStartMs":{"nullable":true,"anyOf":[{"description":"Time waiting for compute (an instance waking, scale-out, a suspend transition or replacement) before the function ran, in ms.","type":"number"},{"type":"null"}]},"functionMs":{"nullable":true,"anyOf":[{"description":"Time from dispatch to the function until its response headers arrived, in ms.","type":"number"},{"type":"null"}]}}},"startedAt":{"format":"date-time","description":"ISO 8601 timestamp when Network started handling the request.","type":"string"},"completedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the request completed, or null if completion was not recorded.","type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/networkRequestSummary"}},"nextCursor":{"nullable":true,"anyOf":[{"description":"Cursor for the next page, or null when there are no more records.","examples":["0197b2f7-8193-723e-8a8f-888888888888"],"type":"string"},{"type":"null"}]},"total":{"description":"Total records matching the current filters.","examples":[142],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/requests/{requestId}":{"get":{"operationId":"getApplicationRequest","summary":"Get application request log","description":"Returns the full details for one routed request, including sanitized request and response headers. Use this endpoint when a summarized log row needs deeper inspection for debugging routing, cache behavior, storage delivery, function execution, or client behavior. Sensitive headers are sanitized before they are persisted and returned.","tags":["Request Logs"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application that owns the request log.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"requestId","in":"path","required":true,"schema":{"format":"uuid","description":"Request log entry to retrieve.","examples":["0197b2f7-8193-723e-8a8f-888888888888"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","allOf":[{"type":"object","required":["id","application","deployment","deploymentFunction","deploymentAsset","storageBucket","storageObject","request","response","metrics","timings","startedAt","completedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"application":{"type":"object","required":["id","name"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Application that received and routed this request.","type":"string"}}},"deployment":{"description":"Deployment associated with the request when traffic matched deployed code or assets.","nullable":true,"anyOf":[{"type":"object","required":["id","status"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"}}},{"type":"null"}]},"deploymentFunction":{"description":"Function route that handled the request, or null when the request did not execute a function.","nullable":true,"anyOf":[{"type":"object","required":["id","name","path","region"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"nullable":true,"anyOf":[{"description":"Function display name configured for the route, or null if unnamed.","type":"string"},{"type":"null"}]},"path":{"description":"Application route path that matched this serverless function.","type":"string"},"region":{"nullable":true,"anyOf":[{"description":"Execution region that handled the function request, or null if not recorded.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"deploymentAsset":{"description":"Static deployment asset that handled the request, or null when the request was not served from an asset.","nullable":true,"anyOf":[{"type":"object","required":["id","path","objectKey"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"path":{"description":"Application route path that matched this static deployment asset.","type":"string"},"objectKey":{"description":"Storage object key backing the served static asset.","type":"string"}}},{"type":"null"}]},"storageBucket":{"description":"Storage bucket involved in the request when traffic was served through Network storage.","nullable":true,"anyOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Storage bucket that served this object request.","type":"string"},"slug":{"description":"Bucket slug used in the storage serving hostname.","type":"string"}}},{"type":"null"}]},"storageObject":{"description":"Storage object involved in the request when a concrete object was served.","nullable":true,"anyOf":[{"type":"object","required":["id","key","contentType"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Object key/path served by this storage request.","type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Stored object MIME type, or null when unknown.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"request":{"type":"object","required":["method","hostname","path","query","protocol","country","userAgent","referer"],"properties":{"method":{"description":"HTTP method sent by the client, such as `GET`, `POST`, or `PATCH`.","type":"string"},"hostname":{"description":"Hostname that received the request, including custom domains and storage hostnames.","type":"string"},"path":{"description":"URL path used for route matching inside Network routing.","type":"string"},"query":{"nullable":true,"anyOf":[{"description":"Sanitized query string without the leading `?`, or null when no query was recorded.","type":"string"},{"type":"null"}]},"protocol":{"nullable":true,"anyOf":[{"description":"Protocol observed by the edge, usually `https`.","type":"string"},{"type":"null"}]},"country":{"nullable":true,"anyOf":[{"description":"ISO 3166-1 alpha-2 country code inferred at the edge, or null if unavailable.","type":"string"},{"type":"null"}]},"userAgent":{"nullable":true,"anyOf":[{"description":"Sanitized client User-Agent header used for debugging traffic sources.","type":"string"},{"type":"null"}]},"referer":{"nullable":true,"anyOf":[{"description":"Sanitized Referer header used for debugging traffic origins.","type":"string"},{"type":"null"}]}}},"response":{"type":"object","required":["status","cacheStatus","cacheHit","region","edgeLocation"],"properties":{"status":{"nullable":true,"anyOf":[{"description":"HTTP status code returned to the client, or null if the request did not complete.","type":"number"},{"type":"null"}]},"cacheStatus":{"nullable":true,"anyOf":[{"default":"hit","description":"CDN cache state recorded for this request when cache metadata was available.","type":"string","enum":["hit","miss","bypass","revalidated","stale","updating"]},{"type":"null"}]},"cacheHit":{"nullable":true,"anyOf":[{"description":"Whether the response body was served from cache instead of the origin/runtime.","type":"boolean"},{"type":"null"}]},"region":{"nullable":true,"anyOf":[{"description":"Function or storage origin region that handled the request.","type":"string"},{"type":"null"}]},"edgeLocation":{"nullable":true,"anyOf":[{"description":"Edge location identifier closest to the client for this request.","type":"string"},{"type":"null"}]}}},"metrics":{"type":"object","required":["requestBodyBytes","responseBodyBytes","bytesSent","durationMs"],"properties":{"requestBodyBytes":{"nullable":true,"anyOf":[{"description":"Client request body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"responseBodyBytes":{"nullable":true,"anyOf":[{"description":"Origin/runtime response body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"bytesSent":{"nullable":true,"anyOf":[{"description":"Total bytes sent from Network edge to the client.","type":"number"},{"type":"null"}]},"durationMs":{"nullable":true,"anyOf":[{"description":"End-to-end request duration observed by Network, in milliseconds.","type":"number"},{"type":"null"}]}}},"timings":{"description":"Phases of `metrics.durationMs`. Each is null when it was not measured or the request did not go through it; when measured, the three add up to `metrics.durationMs`.","type":"object","required":["edgeMs","coldStartMs","functionMs"],"properties":{"edgeMs":{"nullable":true,"anyOf":[{"description":"Edge time: `metrics.durationMs` minus cold start and function time, i.e. routing, admission, asset reads and, for CDN-fronted requests, the CDN hop, in ms.","type":"number"},{"type":"null"}]},"coldStartMs":{"nullable":true,"anyOf":[{"description":"Time waiting for compute (an instance waking, scale-out, a suspend transition or replacement) before the function ran, in ms.","type":"number"},{"type":"null"}]},"functionMs":{"nullable":true,"anyOf":[{"description":"Time from dispatch to the function until its response headers arrived, in ms.","type":"number"},{"type":"null"}]}}},"startedAt":{"format":"date-time","description":"ISO 8601 timestamp when Network started handling the request.","type":"string"},"completedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the request completed, or null if completion was not recorded.","type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/networkRequestSummary"},{"type":"object","required":["requestHeaders","responseHeaders"],"properties":{"requestHeaders":{"description":"Sanitized request headers captured for debugging. Sensitive values are removed before storage.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"responseHeaders":{"description":"Sanitized response headers captured for debugging. Sensitive values are removed before storage.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}],"$id":"#/components/schemas/networkRequest"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/logs":{"get":{"operationId":"listApplicationLogs","summary":"List application activity","description":"Returns a newest-first page of an application's merged activity feed: routed requests with their correlated runtime output, and standalone runtime stdout/stderr lines. Accepts the same filters as the activity stream. Use it to answer what happened recently, for example the latest errors with `kind=runtime&streams=stderr` or failing requests with `statusFamilies=5`.","tags":["Request Logs"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose activity feed should be read.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"maxLength":1024,"description":"Opaque `nextCursor` from a previous page, to read older entries.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":200,"description":"Page size. Defaults to 50.","anyOf":[{"format":"numeric","default":0,"type":"string"},{"minimum":1,"maximum":200,"description":"Page size. Defaults to 50.","type":"number"}]}},{"name":"environmentId","in":"query","required":false,"schema":{"description":"Only entries from this environment UUID.","type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"description":"`all` (default), `request` for routed requests, or `runtime` for stdout/stderr.","type":"string"}},{"name":"search","in":"query","required":false,"schema":{"description":"Case-insensitive substring match on paths and log messages.","type":"string"}},{"name":"streams","in":"query","required":false,"schema":{"description":"Comma-separated runtime streams: `stdout`, `stderr`.","type":"string"}},{"name":"deploymentId","in":"query","required":false,"schema":{"description":"Only entries served by this deployment UUID.","type":"string"}},{"name":"deploymentFunctionId","in":"query","required":false,"schema":{"description":"Only entries from this deployment function UUID.","type":"string"}},{"name":"deploymentAssetId","in":"query","required":false,"schema":{"description":"Only requests for this deployment asset UUID.","type":"string"}},{"name":"storageBucketId","in":"query","required":false,"schema":{"description":"Only requests for this storage bucket UUID.","type":"string"}},{"name":"storageObjectId","in":"query","required":false,"schema":{"description":"Only requests for this storage object UUID.","type":"string"}},{"name":"methods","in":"query","required":false,"schema":{"description":"Comma-separated HTTP methods.","type":"string"}},{"name":"status","in":"query","required":false,"schema":{"description":"Exact HTTP status code.","type":"string"}},{"name":"statusFamilies","in":"query","required":false,"schema":{"description":"Comma-separated status families: 2, 3, 4, 5.","type":"string"}},{"name":"hostname","in":"query","required":false,"schema":{"description":"Exact request hostname.","type":"string"}},{"name":"pathPrefix","in":"query","required":false,"schema":{"description":"Request path prefix.","type":"string"}},{"name":"country","in":"query","required":false,"schema":{"description":"ISO 3166-1 alpha-2 client country.","type":"string"}},{"name":"region","in":"query","required":false,"schema":{"description":"Serving region.","type":"string"}},{"name":"edgeLocation","in":"query","required":false,"schema":{"description":"Serving edge location.","type":"string"}},{"name":"cacheStatuses","in":"query","required":false,"schema":{"description":"Comma-separated cache statuses: hit, miss, bypass, revalidated, stale, updating.","type":"string"}},{"name":"cacheHit","in":"query","required":false,"schema":{"description":"`true` or `false`.","type":"string"}},{"name":"sinceMinutes","in":"query","required":false,"schema":{"description":"Only entries from the last N minutes (1 to 43200). Defaults to the last 24 hours when any filter is set; `search`, `streams` and `kind=runtime` are limited to the last 24 hours.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor"],"properties":{"items":{"description":"Feed entries, newest first: `request` entries summarize a routed request with its correlated runtime output; `runtime` entries are standalone stdout/stderr lines.","type":"array","items":{}},"nextCursor":{"description":"Cursor for the next (older) page, or null.","anyOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/logs/stream":{"get":{"operationId":"streamApplicationLogs","summary":"Stream application activity","description":"Tails the merged request/runtime activity feed over Server-Sent Events, matching the console's live activity view. Events: `item` — an upsert of one feed entry keyed by `kind` and `id`, either a routed request summary (with correlated runtime output counts) or a standalone runtime stdout/stderr line; re-emitted when the underlying row changes, with the SSE `id` field carrying the high-water resume cursor. The stream has no terminal state: after the duration budget expires it emits `end` (`{reason: \"budget\"}`) and the client should reconnect with the `Last-Event-ID` header (sent automatically by EventSource clients) to resume without loss. `error` (`{retryable: true}`) reports a recoverable server failure; comment frames keep idle connections alive. Connections are subject to per-credential and per-organization concurrent-stream limits and a connect-rate limit; rejections return JSON with a `retry-after` header.","tags":["Request Logs"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose activity feed should be streamed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"maxLength":1024,"description":"Resume position: the `id` field of the last received SSE frame. The `Last-Event-ID` request header takes precedence. Invalid cursors are ignored and the stream tails from now.","type":"string"}},{"name":"budgetSeconds","in":"query","required":false,"schema":{"minimum":5,"maximum":600,"description":"Optional cap on how long the server keeps this stream open before ending it.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":5,"maximum":600,"description":"Optional cap on how long the server keeps this stream open before ending it.","type":"integer"}]}},{"name":"environmentId","in":"query","required":false,"schema":{"description":"Filter to one environment (UUID).","type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"description":"Item kind: `all`, `request`, or `runtime`.","type":"string"}},{"name":"search","in":"query","required":false,"schema":{"description":"Substring filter over request paths and runtime messages.","type":"string"}},{"name":"streams","in":"query","required":false,"schema":{"description":"Comma-separated runtime streams: `stdout,stderr`.","type":"string"}},{"name":"sources","in":"query","required":false,"schema":{"description":"Comma-separated runtime log sources: sidecar names, and `_function` for the function's own output.","type":"string"}},{"name":"deploymentId","in":"query","required":false,"schema":{"description":"Filter to requests served by one deployment (UUID).","type":"string"}},{"name":"deploymentFunctionId","in":"query","required":false,"schema":{"description":"Filter to requests served by one function route (UUID).","type":"string"}},{"name":"deploymentAssetId","in":"query","required":false,"schema":{"description":"Filter to requests served by one static asset route (UUID).","type":"string"}},{"name":"storageBucketId","in":"query","required":false,"schema":{"description":"Filter to storage delivery requests for one bucket (UUID).","type":"string"}},{"name":"storageObjectId","in":"query","required":false,"schema":{"description":"Filter to storage delivery requests for one object (UUID).","type":"string"}},{"name":"methods","in":"query","required":false,"schema":{"description":"Comma-separated HTTP methods, e.g. `GET,POST`.","type":"string"}},{"name":"status","in":"query","required":false,"schema":{"description":"Exact response status code (100-599).","type":"string"}},{"name":"statusFamilies","in":"query","required":false,"schema":{"description":"Comma-separated status families out of `2,3,4,5`.","type":"string"}},{"name":"hostname","in":"query","required":false,"schema":{"description":"Filter to one request hostname.","type":"string"}},{"name":"pathPrefix","in":"query","required":false,"schema":{"description":"Filter to request paths under a prefix.","type":"string"}},{"name":"country","in":"query","required":false,"schema":{"description":"Two-letter country code.","type":"string"}},{"name":"region","in":"query","required":false,"schema":{"description":"Serving region identifier.","type":"string"}},{"name":"edgeLocation","in":"query","required":false,"schema":{"description":"Serving edge location identifier.","type":"string"}},{"name":"cacheStatuses","in":"query","required":false,"schema":{"description":"Comma-separated cache statuses out of `hit,miss,bypass,revalidated,stale,updating`.","type":"string"}},{"name":"cacheHit","in":"query","required":false,"schema":{"description":"`true` or `false`.","type":"string"}},{"name":"sinceMinutes","in":"query","required":false,"schema":{"description":"Only include items from the last N minutes.","type":"string"}}],"responses":{"200":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only.","content":{"application/json":{"schema":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only."}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}}}}},"/applications/{applicationId}/hostnames":{"get":{"operationId":"listApplicationHostnames","summary":"List application hostnames","description":"Returns an application’s stable gigadrive.app hostnames: its production alias and per-branch aliases. Immutable per-deployment hostnames are available per deployment via GET /deployments/{deploymentId}/hostnames.","tags":["Hostnames"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose hostnames are managed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total","label"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","hostname","type","active","deploymentId","branchId","source","createdAt"],"properties":{"id":{"type":"string"},"hostname":{"type":"string"},"type":{"description":"DEPLOYMENT, BRANCH, APP, or CUSTOM (an active custom domain).","type":"string"},"active":{"type":"boolean"},"deploymentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"branchId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"system or user.","type":"string"},"createdAt":{"type":"string"}}}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"},"label":{"description":"The application’s production hostname label (`{label}.gigadrive.app`), or null if none is set. Present even before an APP alias row exists so a reserved label is visible without a production deployment.","anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/hostname/availability":{"get":{"operationId":"checkApplicationHostnameAvailability","summary":"Check production hostname availability","description":"Validates a candidate production hostname label and reports whether it is allowed and globally available.","tags":["Hostnames"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose hostnames are managed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"label","in":"query","required":true,"schema":{"description":"Candidate production hostname label to check.","examples":["my-app"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/hostname":{"put":{"operationId":"setApplicationProductionHostname","summary":"Set the production hostname","description":"Sets the user-chosen production hostname label for an application. The production alias `{label}.gigadrive.app` is re-pointed to the latest production deployment.","tags":["Hostnames"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application whose hostnames are managed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"requestBody":{"content":{},"required":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["label","hostname","live"],"properties":{"label":{"description":"The normalized production label that was saved.","type":"string"},"hostname":{"description":"The resulting `{label}.gigadrive.app` hostname.","type":"string"},"live":{"description":"Whether the hostname now routes. False when the label is reserved but no ACTIVE production deployment exists yet, so the URL only becomes live after the next production deployment.","type":"boolean"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/applications/{applicationId}/domains":{"get":{"operationId":"listApplicationDomains","summary":"List custom domains","description":"Lists the custom domains attached to an application with their state, the DNS records still to publish, the last DNS observation and certificate status. Poll this endpoint (or get one domain) while a domain is pending; Gigadrive advances it automatically.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}},"post":{"operationId":"addApplicationDomain","summary":"Add custom domain","description":"Attaches a hostname to the application. The response lists the DNS records to publish: a TXT record proving ownership (unless the organization already verified the domain) and a CNAME, or an ALIAS for an apex domain, pointing at Gigadrive. The domain then moves through `pending_ownership`, `pending_dns` and `issuing_certificate` to `active` without further calls. Counts toward the plan limits for custom domains. An application API key attaches the hostname without adding its registrable domain to the organization, so the TXT record it gets proves this hostname only. Deployment and function tokens cannot add, change, check, claim or remove custom domains.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"requestBody":{"content":{},"required":true},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/applications/{applicationId}/domains/claim":{"post":{"operationId":"claimApplicationDomain","summary":"Claim custom domain from another organization","description":"Moves a hostname that another organization attached to this application. The organization needs a verified ownership covering the hostname, and the claim checks that ownership’s TXT record live, so keep the record published while you claim. The previous attachment stops serving immediately and its organization is notified. Only users and organization API keys can claim. Counts toward the daily add limit and the plan limits for custom domains like an add.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"requestBody":{"content":{},"required":true},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/applications/{applicationId}/domains/{domainId}":{"get":{"operationId":"getApplicationDomain","summary":"Get custom domain","description":"Returns one custom domain with its state, required DNS records and certificate status.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Custom domain to act on.","examples":["0197b2f5-1a2b-7c3d-8e4f-555555555555"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}},"patch":{"operationId":"updateApplicationDomain","summary":"Update custom domain","description":"Changes what a domain serves (production, a branch or a redirect) or makes it the primary domain. A serving domain switches immediately. Fails with `conflict` when the domain changed at the same time (reason `state_changed`) or another domain became primary concurrently (reason `primary_taken`); retry with the current state.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Custom domain to act on.","examples":["0197b2f5-1a2b-7c3d-8e4f-555555555555"],"type":"string"}}],"requestBody":{"description":"Send at least one of `target` and `primary`.","content":{},"required":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}},"delete":{"operationId":"removeApplicationDomain","summary":"Remove custom domain","description":"Stops serving the domain immediately and removes it from the CDN. The ownership verification of the organization stays, so the domain can be attached again without a new TXT record. A domain suspended by Gigadrive cannot be removed (`conflict`, reason `admin_suspended`).","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Custom domain to act on.","examples":["0197b2f5-1a2b-7c3d-8e4f-555555555555"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The domain stopped serving and is being removed.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/applications/{applicationId}/domains/{domainId}/refresh":{"post":{"operationId":"refreshApplicationDomain","summary":"Check custom domain again","description":"Asks Gigadrive to check the domain now instead of waiting for the next scheduled check. A `failed` domain restarts at its first unmet step. Rate limited per domain and organization: a `rate_limited` response carries a `Retry-After` header.","tags":["Domains"],"parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"format":"uuid","description":"Application the custom domains belong to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"domainId","in":"path","required":true,"schema":{"format":"uuid","description":"Custom domain to act on.","examples":["0197b2f5-1a2b-7c3d-8e4f-555555555555"],"type":"string"}}],"responses":{"202":{"description":"Response for status 202","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}}}}}},"/deployments":{"get":{"operationId":"listDeployments","summary":"List deployments","description":"Returns deployments visible to the authenticated actor. Deployments represent immutable attempts to build and ship an application version to Network infrastructure. Use the organization, application, and status filters to power deployment dashboards, CI status checks, or automation that waits for a deployment to leave a pending or processing state.","tags":["Deployments"],"parameters":[{"name":"organizationId","in":"query","required":false,"schema":{"description":"Restricts results to deployments whose application belongs to this organization.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"}},{"name":"applicationId","in":"query","required":false,"schema":{"description":"Restricts results to deployments for a single application.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"}},{"name":"from","in":"query","required":false,"schema":{"description":"Cursor for the next page of list results. Pass the last resource ID returned by the previous page to continue listing from that point within the same filters and authenticated actor scope.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}},{"name":"limit","in":"query","required":true,"schema":{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Maximum number of resources to return for this page. The API still reports `total` for the full scoped and filtered result set.","minimum":1,"maximum":100,"default":10,"examples":[25],"type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","applicationId","status","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application that owns this deployment and receives the resulting code, assets, and runtime configuration.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deployment"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createDeployment","summary":"Create a deployment","description":"Creates a new deployment for an application. When `gitSource` is provided, it selects the branch, tag, or commit and the build is queued immediately. Without `gitSource`, the deployment remains pending until its source ZIP is finalized through the multipart upload endpoints. Deployment and function actors cannot create additional deployments.","tags":["Deployments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicationId"],"properties":{"applicationId":{"description":"The application that should receive a new deployment.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"gitSource":{"type":"object","required":["ref"],"properties":{"ref":{"description":"Git ref to deploy, usually a branch or tag name.","example":"main","type":"string"},"sha":{"description":"Exact commit SHA to deploy when the ref should be pinned.","example":"1234567890","type":"string"}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["applicationId"],"properties":{"applicationId":{"description":"The application that should receive a new deployment.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"gitSource":{"type":"object","required":["ref"],"properties":{"ref":{"description":"Git ref to deploy, usually a branch or tag name.","example":"main","type":"string"},"sha":{"description":"Exact commit SHA to deploy when the ref should be pinned.","example":"1234567890","type":"string"}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["applicationId"],"properties":{"applicationId":{"description":"The application that should receive a new deployment.","format":"uuid","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"gitSource":{"type":"object","required":["ref"],"properties":{"ref":{"description":"Git ref to deploy, usually a branch or tag name.","example":"main","type":"string"},"sha":{"description":"Exact commit SHA to deploy when the ref should be pinned.","example":"1234567890","type":"string"}}}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","status","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application that owns this deployment and receives the resulting code, assets, and runtime configuration.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deployment"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}":{"get":{"operationId":"getDeployment","summary":"Get a deployment","description":"Returns a single deployment by ID after verifying that the authenticated actor can read the deployment. Use this endpoint to poll the current deployment status after creating a deployment or uploading a deployment archive.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","status","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application that owns this deployment and receives the resulting code, assets, and runtime configuration.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deployment"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/logs":{"get":{"operationId":"listDeploymentLogs","summary":"List deployment logs","description":"Returns build and provisioning logs in chronological order. Use offset pagination while a deployment is active, or createdAt[gt] to tail entries emitted after a known timestamp.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"default":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"default":0,"type":"integer"}]}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":100,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":100,"type":"integer"}]}},{"name":"createdAt[gt]","in":"query","required":false,"schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["totalItems","limit","offset","items"],"properties":{"totalItems":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"limit":{"minimum":1,"maximum":100,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"type":"integer"}]},"offset":{"minimum":0,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"type":"integer"}]},"items":{"type":"array","items":{"type":"object","required":["id","message","type","createdAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"message":{"description":"Build or provisioning log message emitted for this deployment.","type":"string"},"type":{"default":"INFO","description":"Severity level assigned by the deployment pipeline.","type":"string","enum":["INFO","ERROR","WARN","DEBUG"]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deploymentLog"}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/logs/stream":{"get":{"operationId":"streamDeploymentLogs","summary":"Stream deployment logs","description":"Tails build and provisioning logs over Server-Sent Events. Events: `log` (`{id, type, message, createdAt}`, with the SSE `id` field carrying the resume cursor), `status` (`{status, statusReason, terminal}`, emitted on every status change), `end` (`{reason: \"terminal\" | \"budget\"}`), and `error` (`{retryable: true}`); comment frames keep idle connections alive. The stream closes after the deployment reaches a terminal status or the duration budget expires; on budget closes, reconnect with the `Last-Event-ID` header (sent automatically by EventSource clients) to resume without loss. Connections are subject to per-credential and per-organization concurrent-stream limits and a connect-rate limit; rejections return JSON with a `retry-after` header.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"maxLength":128,"description":"Resume position: the `id` field of the last received SSE frame. The `Last-Event-ID` request header takes precedence. Invalid cursors are ignored and the stream starts from the beginning of the tail.","type":"string"}},{"name":"budgetSeconds","in":"query","required":false,"schema":{"minimum":5,"maximum":900,"description":"Optional cap on how long the server keeps this stream open before ending it.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":5,"maximum":900,"description":"Optional cap on how long the server keeps this stream open before ending it.","type":"integer"}]}}],"responses":{"200":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only.","content":{"application/json":{"schema":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only."}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}}}}},"/deployments/{deploymentId}/upload/start":{"post":{"operationId":"startDeploymentUpload","summary":"Start deployment archive upload","description":"Starts a multipart upload for an archive-based deployment. Call this after creating a pending deployment when your automation already built the application package and needs to upload the resulting ZIP archive. The returned `uploadId` identifies the provider-side upload and must be reused when requesting signed part URLs and completing the upload. Archives can be at most 2 GiB in at most 410 parts.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sizeBytes":{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"sizeBytes":{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"sizeBytes":{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Size of the ZIP archive in bytes, if known. Archives larger than 2147483648 bytes (2 GiB) are refused here instead of after the upload. The completed archive is measured either way.","example":52428800,"examples":[52428800],"type":"integer"}]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["uploadId"],"properties":{"uploadId":{"description":"Provider multipart upload ID used by subsequent part and complete calls.","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/upload/part":{"post":{"operationId":"createDeploymentUploadPartUrl","summary":"Create deployment upload part URL","description":"Creates a short-lived signed URL for one part of a deployment archive multipart upload. Upload the corresponding ZIP bytes directly to the returned URL with an HTTP `PUT`, then keep the returned ETag so it can be submitted to the complete endpoint. Part numbers must match the order expected by the object storage provider.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partNumber","uploadId"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"type":"integer"}]},"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["partNumber","uploadId"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"type":"integer"}]},"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["partNumber","uploadId"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number to upload, at most 410.","example":1,"examples":[1],"type":"integer"}]},"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"description":"Short-lived signed provider URL where the client uploads this archive part with HTTP PUT.","format":"uri","examples":["https://deployment-archives.s3.fr-par.scw.cloud/archive.zip?X-Amz-Signature=..."],"type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/upload/complete":{"post":{"operationId":"completeDeploymentUpload","summary":"Complete deployment archive upload","description":"Completes a deployment archive multipart upload after every part has been uploaded through its signed URL. Submit the provider ETags for all uploaded parts in ascending order. A successful response finalizes the archive object and queues the deployment workflow exactly once. An archive larger than 2 GiB is deleted and refused with `413`. When every build slot of the organization is taken, the deployment fails and the endpoint returns `429`: deploy again once a running build finishes.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"description":"Deployment to read or upload archive data for.","format":"uuid","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["uploadId","parts"],"properties":{"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"},"parts":{"maxItems":410,"type":"array","items":{"type":"object","required":["partNumber","etag"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"type":"integer"}]},"etag":{"description":"ETag returned by the storage provider after uploading the part.","example":"\"9b2cf535f27731c974343645a3985328\"","examples":["\"9b2cf535f27731c974343645a3985328\""],"type":"string"}}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["uploadId","parts"],"properties":{"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"},"parts":{"maxItems":410,"type":"array","items":{"type":"object","required":["partNumber","etag"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"type":"integer"}]},"etag":{"description":"ETag returned by the storage provider after uploading the part.","example":"\"9b2cf535f27731c974343645a3985328\"","examples":["\"9b2cf535f27731c974343645a3985328\""],"type":"string"}}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["uploadId","parts"],"properties":{"uploadId":{"description":"Multipart upload ID returned by the start endpoint.","example":"2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1","examples":["2~JwJjMGE1ZTYtYzY2Zi00YmE2LWI4Y2EtMzYxN2Y4YjE5N2Y1"],"type":"string"},"parts":{"maxItems":410,"type":"array","items":{"type":"object","required":["partNumber","etag"],"properties":{"partNumber":{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":410,"description":"One-based multipart part number that was uploaded.","example":1,"examples":[1],"type":"integer"}]},"etag":{"description":"ETag returned by the storage provider after uploading the part.","example":"\"9b2cf535f27731c974343645a3985328\"","examples":["\"9b2cf535f27731c974343645a3985328\""],"type":"string"}}}}}}}}},"responses":{"201":{"description":"Response for status 201","content":{"type":"null"}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/hostnames":{"get":{"operationId":"listDeploymentHostnames","summary":"List deployment hostnames","description":"Returns the gigadrive.app hostnames that currently route to a deployment.","tags":["Hostnames"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"format":"uuid","description":"Deployment whose hostnames should be listed.","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","hostname","type","active","deploymentId","branchId","source","createdAt"],"properties":{"id":{"type":"string"},"hostname":{"type":"string"},"type":{"description":"DEPLOYMENT, BRANCH, APP, or CUSTOM (an active custom domain).","type":"string"},"active":{"type":"boolean"},"deploymentId":{"anyOf":[{"type":"string"},{"type":"null"}]},"branchId":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"system or user.","type":"string"},"createdAt":{"type":"string"}}}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/deployments/{deploymentId}/image-cache":{"get":{"operationId":"getDeploymentImageCache","summary":"Get deployment image cache status","description":"Returns whether managed image optimization is enabled for a deployment, the CDN tags used for cache invalidation, and the active image policy when configured. Requires the `network:image_optimization:read` scope. Pass an optional `source` query parameter to resolve the source-specific CDN tag for every transform of that image.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"format":"uuid","description":"Deployment whose managed image cache should be inspected or purged.","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"minLength":1,"maxLength":4096,"description":"Optional image source URL or path. When set, responses and purges target the CDN tag for every transform of that source. When omitted, the deployment-wide image tag is used.","examples":["https://images.example.com/hero.jpg","/assets/logo.png"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["enabled","deploymentTag","sourceTag","policy"],"properties":{"enabled":{"description":"Whether managed image optimization is enabled for this deployment.","examples":[true],"type":"boolean"},"deploymentTag":{"description":"CDN cache tag that covers every optimized image for this deployment.","examples":["deployment-0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"},"sourceTag":{"nullable":true,"anyOf":[{"description":"CDN cache tag for every transform of the requested `source`. Null when `source` is omitted from the query.","examples":["source-a1b2c3d4e5f6789012345678abcdef01"],"type":"string"},{"type":"null"}]},"policy":{"nullable":true,"anyOf":[{"type":"object","required":["localPatterns","remotePatterns","widths","heights","qualities","formats","minimumCacheTTL","dangerouslyAllowSVG","contentSecurityPolicy","contentDispositionType","maximumRedirects","maximumResponseBody","variants"],"properties":{"localPatterns":{"description":"Patterns that allow local deployment assets to be optimized.","type":"array","items":{"type":"object","required":["pathname"],"properties":{"protocol":{"description":"Allowed URL protocol for matching sources.","examples":["https"],"type":"string"},"hostname":{"description":"Allowed hostname for matching sources.","examples":["images.example.com"],"type":"string"},"port":{"description":"Optional port constraint for matching sources.","examples":["443"],"type":"string"},"pathname":{"description":"Pathname pattern that must match the image source.","examples":["/**"],"type":"string"},"search":{"description":"Optional query-string constraint for matching sources.","type":"string"}}}},"remotePatterns":{"description":"Patterns that allow remote HTTP(S) sources to be fetched and optimized.","type":"array","items":{"type":"object","required":["hostname","pathname"],"properties":{"protocol":{"description":"Allowed URL protocol for remote sources.","examples":["https"],"type":"string"},"hostname":{"description":"Allowed hostname for remote sources.","examples":["images.example.com"],"type":"string"},"port":{"description":"Optional port constraint for remote sources.","examples":["443"],"type":"string"},"pathname":{"description":"Pathname pattern that must match the remote image source.","examples":["/**"],"type":"string"},"search":{"description":"Optional query-string constraint for remote sources.","type":"string"}}}},"widths":{"description":"Allowed output widths accepted by the image optimizer.","type":"array","items":{"type":"number"}},"heights":{"description":"Allowed output heights accepted by the image optimizer.","type":"array","items":{"type":"number"}},"qualities":{"description":"Allowed output qualities accepted by the image optimizer.","type":"array","items":{"type":"number"}},"formats":{"description":"Allowed output formats for optimized images.","type":"array","items":{"anyOf":[{"const":"image/avif","type":"string"},{"const":"image/webp","type":"string"},{"const":"image/jpeg","type":"string"},{"const":"image/png","type":"string"}]}},"minimumCacheTTL":{"description":"Minimum CDN cache TTL in seconds applied to optimized image responses.","type":"number"},"dangerouslyAllowSVG":{"description":"Whether remote SVG sources may be reflected through the optimizer.","type":"boolean"},"contentSecurityPolicy":{"description":"Content-Security-Policy applied to optimized or pass-through image responses.","type":"string"},"contentDispositionType":{"description":"Content-Disposition type applied to image responses.","anyOf":[{"const":"inline","type":"string"},{"const":"attachment","type":"string"}]},"maximumRedirects":{"description":"Maximum number of redirects followed when fetching a remote image source.","type":"number"},"maximumResponseBody":{"description":"Maximum remote source response body size in bytes.","type":"number"},"variants":{"description":"Named image variants configured for the deployment.","type":"object","patternProperties":{"^(.*)$":{"type":"object","properties":{"width":{"description":"Target width in pixels for the named variant.","type":"number"},"height":{"description":"Target height in pixels for the named variant.","type":"number"},"quality":{"description":"Output quality for the named variant.","type":"number"},"format":{"description":"Output content type for the named variant.","anyOf":[{"const":"image/avif","type":"string"},{"const":"image/webp","type":"string"},{"const":"image/jpeg","type":"string"},{"const":"image/png","type":"string"}]},"fit":{"description":"How the source is fitted into the variant dimensions.","anyOf":[{"const":"contain","type":"string"},{"const":"cover","type":"string"},{"const":"fill","type":"string"},{"const":"inside","type":"string"},{"const":"outside","type":"string"}]}}}}}}},{"type":"null"}]}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"delete":{"operationId":"purgeDeploymentImageCache","summary":"Purge deployment image cache","description":"Purges managed image-optimization CDN cache for a deployment. Omitting `source` purges the deployment-wide image tag. Providing `source` purges every transform of that image source. Requires the `network:image_optimization:purge` scope and returns `409` when image optimization is not enabled for the deployment.","tags":["Deployments"],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"format":"uuid","description":"Deployment whose managed image cache should be inspected or purged.","examples":["0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"minLength":1,"maxLength":4096,"description":"Optional image source URL or path. When set, responses and purges target the CDN tag for every transform of that source. When omitted, the deployment-wide image tag is used.","examples":["https://images.example.com/hero.jpg","/assets/logo.png"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["purged","tag"],"properties":{"purged":{"description":"Always true when the purge request is accepted by the CDN.","const":true,"type":"boolean"},"tag":{"description":"CDN cache tag that was purged. Either the deployment-wide tag or a source-specific tag.","examples":["deployment-0197b2f2-3c5e-7d1f-9b3a-333333333333"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/microvms":{"post":{"operationId":"createMicroVm","summary":"Create a microVM","description":"Boots an isolated Linux microVM from an image and answers once it is running (`201`), or right away with `?wait=false` (`202`, status `pending` or `starting`). When no capacity is free it waits for some; `503 capacity_unavailable` means none came in time, so try again later. It stops by itself after `timeoutMs`. Exposed ports get preview URLs, public unless `network.previews` is `private`, in which case the answer carries the `previewToken` they require. Plan limits apply to vCPUs, memory, disk, lifetime and the number of microVMs running at once.","tags":["MicroVMs"],"parameters":[{"name":"wait","in":"query","required":false,"schema":{"description":"Default `true`: answer `201` once the microVM is running. When no capacity is free, the request waits up to 25 seconds; if the microVM is still not running by then it is answered `202` and keeps waiting for capacity (up to 8 minutes) and boots by itself, so poll `GET /microvms/{id}`. `false` answers `202` right away.","type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"applicationId":{"format":"uuid","description":"Application the microVM belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"image":{"minLength":1,"maxLength":64,"description":"Image name or id: a built-in image such as `node22` or one of the application's images. Default `node22`. Not with `snapshotId`.","examples":["node22"],"type":"string"},"snapshotId":{"format":"uuid","description":"Create the microVM from this snapshot instead of an image: its memory, running processes and disk. It keeps the snapshot's image, vCPUs and memory; `diskMb` may be larger than the snapshot's. Not with `image`.","type":"string"},"vcpus":{"type":"string","enum":[1,2,4,8]},"memoryMb":{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","type":"integer"}]},"diskMb":{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","type":"integer"}]},"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","type":"integer"}]},"onTimeout":{"type":"string","enum":["stop","pause"]},"autoResume":{"description":"Resume the microVM on its own while it is paused: a command or file operation resumes it and waits, and a request to a public preview URL resumes it and waits up to 20 seconds. Default `false`.","type":"boolean"},"ports":{"maxItems":8,"description":"Ports to expose on public preview URLs, at most 8. Ports 10000 and 10001 are reserved.","examples":[[3000]],"type":"array","items":{"minimum":1,"maximum":65535,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":65535,"type":"integer"}]}},"env":{"description":"Environment variables for every command. Values are never stored or returned.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"metadata":{"description":"Your own labels, returned on the microVM. At most 64 entries.","type":"object","patternProperties":{"^(.*)$":{"maxLength":512,"type":"string"}}},"region":{"minLength":1,"maxLength":64,"examples":["fr-par"],"type":"string"},"volumes":{"maxItems":4,"description":"Persistent volumes to attach, at most 4, each at its own mount path and none inside another. A volume can be attached to one microVM at a time (`409 microvm_volume_in_use`). Its contents are saved when the microVM stops. Not with `snapshotId` or `onTimeout: \"pause\"`; a microVM with volumes cannot be paused or snapshotted, and starts about one second slower.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","description":"A volume of the application, from `POST /microvm-volumes`.","type":"string"},"mountPath":{"minLength":1,"maxLength":255,"description":"Absolute, normalized directory the volume is mounted at, such as `/data`: letters, digits and `. _ / -`, no `.` or `..` segments, no trailing `/`. Not `/` and not in a system directory (`/proc`, `/sys`, `/dev`, `/run`, `/etc`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/usr`, `/boot`). It is created if needed.","examples":["/data"],"type":"string"}}}},"network":{"type":"object","required":["egress"],"properties":{"egress":{"default":"allow","description":"`deny` blocks all outbound traffic. Private networks are always blocked.","type":"string","enum":["allow","deny"]},"previews":{"type":"string","enum":["public","private"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"applicationId":{"format":"uuid","description":"Application the microVM belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"image":{"minLength":1,"maxLength":64,"description":"Image name or id: a built-in image such as `node22` or one of the application's images. Default `node22`. Not with `snapshotId`.","examples":["node22"],"type":"string"},"snapshotId":{"format":"uuid","description":"Create the microVM from this snapshot instead of an image: its memory, running processes and disk. It keeps the snapshot's image, vCPUs and memory; `diskMb` may be larger than the snapshot's. Not with `image`.","type":"string"},"vcpus":{"type":"string","enum":[1,2,4,8]},"memoryMb":{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","type":"integer"}]},"diskMb":{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","type":"integer"}]},"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","type":"integer"}]},"onTimeout":{"type":"string","enum":["stop","pause"]},"autoResume":{"description":"Resume the microVM on its own while it is paused: a command or file operation resumes it and waits, and a request to a public preview URL resumes it and waits up to 20 seconds. Default `false`.","type":"boolean"},"ports":{"maxItems":8,"description":"Ports to expose on public preview URLs, at most 8. Ports 10000 and 10001 are reserved.","examples":[[3000]],"type":"array","items":{"minimum":1,"maximum":65535,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":65535,"type":"integer"}]}},"env":{"description":"Environment variables for every command. Values are never stored or returned.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"metadata":{"description":"Your own labels, returned on the microVM. At most 64 entries.","type":"object","patternProperties":{"^(.*)$":{"maxLength":512,"type":"string"}}},"region":{"minLength":1,"maxLength":64,"examples":["fr-par"],"type":"string"},"volumes":{"maxItems":4,"description":"Persistent volumes to attach, at most 4, each at its own mount path and none inside another. A volume can be attached to one microVM at a time (`409 microvm_volume_in_use`). Its contents are saved when the microVM stops. Not with `snapshotId` or `onTimeout: \"pause\"`; a microVM with volumes cannot be paused or snapshotted, and starts about one second slower.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","description":"A volume of the application, from `POST /microvm-volumes`.","type":"string"},"mountPath":{"minLength":1,"maxLength":255,"description":"Absolute, normalized directory the volume is mounted at, such as `/data`: letters, digits and `. _ / -`, no `.` or `..` segments, no trailing `/`. Not `/` and not in a system directory (`/proc`, `/sys`, `/dev`, `/run`, `/etc`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/usr`, `/boot`). It is created if needed.","examples":["/data"],"type":"string"}}}},"network":{"type":"object","required":["egress"],"properties":{"egress":{"default":"allow","description":"`deny` blocks all outbound traffic. Private networks are always blocked.","type":"string","enum":["allow","deny"]},"previews":{"type":"string","enum":["public","private"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"applicationId":{"format":"uuid","description":"Application the microVM belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"image":{"minLength":1,"maxLength":64,"description":"Image name or id: a built-in image such as `node22` or one of the application's images. Default `node22`. Not with `snapshotId`.","examples":["node22"],"type":"string"},"snapshotId":{"format":"uuid","description":"Create the microVM from this snapshot instead of an image: its memory, running processes and disk. It keeps the snapshot's image, vCPUs and memory; `diskMb` may be larger than the snapshot's. Not with `image`.","type":"string"},"vcpus":{"type":"string","enum":[1,2,4,8]},"memoryMb":{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":512,"maximum":8192,"description":"Memory in MB, default 2048. The plan caps the maximum.","type":"integer"}]},"diskMb":{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Writable disk in MB, default 10240. The plan caps the maximum.","type":"integer"}]},"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"Lifetime in milliseconds after which the microVM stops, default 300000. Extend it with `POST /microvms/{id}/timeout`.","type":"integer"}]},"onTimeout":{"type":"string","enum":["stop","pause"]},"autoResume":{"description":"Resume the microVM on its own while it is paused: a command or file operation resumes it and waits, and a request to a public preview URL resumes it and waits up to 20 seconds. Default `false`.","type":"boolean"},"ports":{"maxItems":8,"description":"Ports to expose on public preview URLs, at most 8. Ports 10000 and 10001 are reserved.","examples":[[3000]],"type":"array","items":{"minimum":1,"maximum":65535,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":65535,"type":"integer"}]}},"env":{"description":"Environment variables for every command. Values are never stored or returned.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"metadata":{"description":"Your own labels, returned on the microVM. At most 64 entries.","type":"object","patternProperties":{"^(.*)$":{"maxLength":512,"type":"string"}}},"region":{"minLength":1,"maxLength":64,"examples":["fr-par"],"type":"string"},"volumes":{"maxItems":4,"description":"Persistent volumes to attach, at most 4, each at its own mount path and none inside another. A volume can be attached to one microVM at a time (`409 microvm_volume_in_use`). Its contents are saved when the microVM stops. Not with `snapshotId` or `onTimeout: \"pause\"`; a microVM with volumes cannot be paused or snapshotted, and starts about one second slower.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","description":"A volume of the application, from `POST /microvm-volumes`.","type":"string"},"mountPath":{"minLength":1,"maxLength":255,"description":"Absolute, normalized directory the volume is mounted at, such as `/data`: letters, digits and `. _ / -`, no `.` or `..` segments, no trailing `/`. Not `/` and not in a system directory (`/proc`, `/sys`, `/dev`, `/run`, `/etc`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/usr`, `/boot`). It is created if needed.","examples":["/data"],"type":"string"}}}},"network":{"type":"object","required":["egress"],"properties":{"egress":{"default":"allow","description":"`deny` blocks all outbound traffic. Private networks are always blocked.","type":"string","enum":["allow","deny"]},"previews":{"type":"string","enum":["public","private"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}}}}}},"responses":{"201":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}},"previewToken":{"description":"Only for `network.previews: \"private\"`: the token preview requests must carry, in the `x-gigadrive-preview-token` header or once as `?gd_preview_token=` (which sets a cookie for that preview URL). Shown only here and when rotated.","examples":["gdpv_3q2n7r..."],"type":"string"}}}}}},"202":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}},"previewToken":{"description":"Only for `network.previews: \"private\"`: the token preview requests must carry, in the `x-gigadrive-preview-token` header or once as `?gd_preview_token=` (which sets a cookie for that preview URL). Shown only here and when rotated.","examples":["gdpv_3q2n7r..."],"type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"get":{"operationId":"listMicroVms","summary":"List microVMs","description":"Lists an application's microVMs, newest first, including stopped ones (kept 30 days). Page with `cursor`.","tags":["MicroVMs"],"parameters":[{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Application the microVM belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","starting","running","pausing","paused","resuming","stopping","stopped","failed"]}},{"name":"cursor","in":"query","required":false,"schema":{"format":"uuid","description":"`pagination.nextCursor` of the previous page. Omit for the first page.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}},"pagination":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"nullable":true,"anyOf":[{"description":"Pass as `cursor` to read the next page.","type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}":{"get":{"operationId":"getMicroVm","summary":"Get a microVM","description":"Reads one microVM: status, size, preview URLs and when it expires.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"deleteMicroVm","summary":"Delete a microVM","description":"Stops the microVM if it is still running and removes it from the API.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The microVM is stopped and deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/timeout":{"post":{"operationId":"extendMicroVmTimeout","summary":"Extend a microVM timeout","description":"Sets a running microVM to stop `timeoutMs` from now. Its running time may not exceed the plan maximum; time spent paused does not count.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["timeoutMs"],"properties":{"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["timeoutMs"],"properties":{"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["timeoutMs"],"properties":{"timeoutMs":{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1000,"maximum":86400000,"description":"New lifetime, counted from now. The running time may not exceed the plan maximum (paused time does not count).","type":"integer"}]}}}}}},"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/network":{"patch":{"operationId":"updateMicroVmNetwork","summary":"Update a microVM network policy","description":"Replaces what a running or paused microVM may reach: `egress` and the `allow` list, as at create. A running microVM keeps running and the new rules apply at once. Connections it opened that the new rules no longer allow are closed, and the others continue. Names it may still reach keep working without a new lookup. A paused microVM uses the new rules when it resumes. Preview access and ports do not change. Without `inject` the egress header injection rules stay as they are, since their values are never returned; `inject` replaces them all, `inject: []` removes them, and so does `egress: \"deny\"`. `409 microvm_network_update_unavailable` means this microVM cannot change its network while it runs: pause and resume it first. `409 microvm_egress_inject_unsupported` means this microVM started without egress header injection and cannot take rules: stop it and create it again.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["egress"],"properties":{"egress":{"type":"string","enum":["allow","deny"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["egress"],"properties":{"egress":{"type":"string","enum":["allow","deny"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["egress"],"properties":{"egress":{"type":"string","enum":["allow","deny"]},"allow":{"maxItems":32,"description":"Domain names and public IPv4 networks (`a.b.c.d/n`) the microVM may reach. `*.example.com` covers every subdomain of example.com, not example.com itself. A name is enforced by the addresses the microVM resolves it to, so DNS for other names is refused. Omit to reach the whole internet. Needs `egress: \"allow\"`.","type":"array","items":{"minLength":1,"maxLength":255,"examples":["api.openai.com","*.github.com","140.82.112.0/20"],"type":"string"}},"inject":{"maxItems":8,"description":"Egress header injection: the host adds these headers to the microVM's HTTPS requests (port 443) to each domain, so a credential never enters the microVM. The most specific rule wins: an exact name over a wildcard. At most 8 rules and 32 KiB of header names and values in total. Plain HTTP to a rule's domain is refused. Programs that do not read the system trust store must trust `/etc/gigadrive/egress-ca.pem`; `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE` and `DENO_CERT` are set. The destination receives the values and may echo them back, so only configure credentials for hosts you trust. Needs `egress: \"allow\"` (`422 invalid_network` otherwise).","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"minLength":1,"maxLength":255,"description":"Domain name the headers are sent to, like an `allow` entry: `*.example.com` covers every subdomain of example.com, not example.com itself. A wildcard over a public suffix such as `*.vercel.app` or `*.co.uk` is refused, since anyone can register names under it. At most one rule per domain. Reachable even when `allow` does not list it.","examples":["api.openai.com"],"type":"string"},"headers":{"description":"Headers to set, 1 to 8, by name (case-insensitive). They replace any header of the same name the microVM sends. A value is 1 to 8192 bytes of visible ASCII, spaces and tabs, without leading or trailing whitespace. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Keep-Alive, TE, Trailer and Proxy-* cannot be set. Values are stored encrypted and never returned.","examples":[{"Authorization":"Bearer sk-..."}],"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}}}}}}},"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/preview-token":{"post":{"operationId":"rotateMicroVmPreviewToken","summary":"Rotate a microVM preview token","description":"Issues a new preview token for a microVM created with `network.previews: \"private\"` and revokes the previous one. The token is shown only in this answer. `400` for a microVM with public previews.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"responses":{"200":{"description":"A new preview token.","content":{"application/json":{"schema":{"description":"A new preview token.","type":"object","required":["previewToken"],"properties":{"previewToken":{"description":"The new preview token. The previous one stops working within a second.","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/stop":{"post":{"operationId":"stopMicroVm","summary":"Stop a microVM","description":"Stops a microVM and discards its disk. Billing ends. Stopping a stopped microVM succeeds and changes nothing. A running microVM with volumes first saves them: it answers `stopping` and becomes `stopped` once the save finished, then its volumes are free to attach again.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/volumes/save":{"post":{"operationId":"saveMicroVmVolumes","summary":"Save microVM volumes","description":"Saves the volumes of a running microVM while it keeps running: it is frozen only while the volume files are copied on its host. A later microVM that attaches a volume sees this save, or a newer one. A stop saves the volumes by itself. `409 microvm_volumes_not_attached` for a microVM without volumes, `409 capture_in_progress` while another save runs. If the save fails the volumes keep their previous contents (`502 microvm_capture_failed`).","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"wait","in":"query","required":false,"schema":{"description":"Default `true`: answer once the volumes are saved (up to two minutes). `false` answers `202` while the save still runs.","type":"boolean"}}],"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"202":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/pause":{"post":{"operationId":"pauseMicroVm","summary":"Pause a microVM","description":"Captures a running microVM, memory and disk, and frees its resources: a paused microVM accrues no CPU or memory, only snapshot storage. Its processes keep their state, and its timeout stops counting until it resumes. Commands, files and preview URLs answer `409 microvm_paused` until then. A paused microVM is deleted after the plan maximum pause retention. If the capture fails, the microVM keeps running (`502 microvm_capture_failed`). An organization holds at most as many paused microVMs as its plan runs concurrently (`429 quota_exceeded`), and cannot pause while its compute is suspended (`402 billing_suspended`).","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"wait","in":"query","required":false,"schema":{"description":"Default `true`: answer once the microVM is paused (up to two minutes). `false` answers `202` while it is still pausing.","type":"boolean"}}],"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"202":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/resume":{"post":{"operationId":"resumeMicroVm","summary":"Resume a microVM","description":"Restores a paused microVM with its memory, processes and disk, and continues its timeout where it stopped. Its id, preview URLs and metadata stay the same. Network connections that were open when it paused are closed. If the resume fails the microVM stays paused and can be resumed again.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"wait","in":"query","required":false,"schema":{"description":"Default `true`: answer once the microVM runs again. `false` answers `202` while it is still resuming.","type":"boolean"}}],"responses":{"200":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"202":{"description":"An isolated Linux microVM.","content":{"application/json":{"schema":{"description":"An isolated Linux microVM.","type":"object","required":["id","slug","applicationId","organizationId","status","image","vcpus","memoryMb","diskMb","region","ports","network","metadata","timeoutMs","onTimeout","autoResume","expiresAt","createdAt","startedAt","stoppedAt","stopReason","pausedAt","sourceSnapshotId","volumes"],"properties":{"id":{"format":"uuid","type":"string"},"slug":{"description":"Unguessable label used in preview URLs.","type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"status":{"description":"`pending`, `starting`, `running`, `pausing`, `paused`, `resuming`, `stopping`, `stopped` or `failed`.","examples":["running"],"type":"string"},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"region":{"examples":["fr-par"],"type":"string"},"ports":{"type":"array","items":{"type":"object","required":["port","url"],"properties":{"port":{"examples":[3000],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[3000],"type":"integer"}]},"url":{"description":"Preview URL of the port.","type":"string"}}}},"network":{"type":"object","required":["egress","previews"],"properties":{"egress":{"default":"allow","type":"string","enum":["allow","deny"]},"previews":{"default":"public","description":"`private` preview URLs answer only requests that carry the preview token.","type":"string","enum":["public","private"]},"allow":{"description":"The only domain names and public IPv4 networks the microVM may reach.","type":"array","items":{"type":"string"}},"inject":{"description":"Egress header injection rules, without their values: header values are never returned. Absent when there are none.","type":"array","items":{"type":"object","required":["domain","headers"],"properties":{"domain":{"examples":["api.openai.com"],"type":"string"},"headers":{"description":"Lowercase names of the headers the microVM gets on its HTTPS requests to the domain.","examples":[["authorization"]],"type":"array","items":{"type":"string"}}}}}}},"metadata":{"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"timeoutMs":{"description":"Requested lifetime in milliseconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Requested lifetime in milliseconds.","type":"integer"}]},"onTimeout":{"default":"stop","description":"What happens when the timeout ends: `stop` discards the microVM, `pause` pauses it.","type":"string","enum":["stop","pause"]},"autoResume":{"description":"Whether a paused microVM resumes on its own when it is used.","type":"boolean"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM stops automatically.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"startedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stoppedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"stopReason":{"nullable":true,"anyOf":[{"examples":["timeout"],"type":"string"},{"type":"null"}]},"pausedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the microVM was paused, while it is paused.","type":"string"},{"type":"null"}]},"sourceSnapshotId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The snapshot the microVM was created from, if any.","type":"string"},{"type":"null"}]},"volumes":{"description":"The volumes the microVM attached at create, and where they are mounted.","type":"array","items":{"type":"object","required":["volumeId","mountPath"],"properties":{"volumeId":{"format":"uuid","type":"string"},"mountPath":{"examples":["/data"],"type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/snapshots":{"post":{"operationId":"createMicroVmSnapshot","summary":"Snapshot a microVM","description":"Captures a running microVM, memory and disk, into a snapshot that new microVMs can be created from (`POST /microvms` with `snapshotId`). The microVM keeps running; it is frozen only for the moments the capture takes. Snapshots are billed as storage until they are deleted or expire, so a snapshot is refused while the organization compute is suspended (`402 billing_suspended`).","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"wait","in":"query","required":false,"schema":{"description":"Default `true`: answer once the snapshot is ready (up to two minutes). `false` answers `202` while it is still being created.","type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":64,"description":"Your label for the snapshot.","examples":["after-install"],"type":"string"},"expiresInMs":{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":64,"description":"Your label for the snapshot.","examples":["after-install"],"type":"string"},"expiresInMs":{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":64,"description":"Your label for the snapshot.","examples":["after-install"],"type":"string"},"expiresInMs":{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60000,"maximum":31536000000,"description":"Delete the snapshot after this many milliseconds. Default and maximum: the plan retention.","type":"integer"}]}}}}}},"responses":{"201":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","content":{"application/json":{"schema":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","type":"object","required":["id","name","applicationId","organizationId","sourceMicrovmId","status","image","vcpus","memoryMb","diskMb","sizeBytes","error","expiresAt","createdAt","readyAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"anyOf":[{"examples":["after-install"],"type":"string"},{"type":"null"}]},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sourceMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM the snapshot was taken of.","type":"string"},{"type":"null"}]},"status":{"default":"creating","description":"New microVMs can be created from a `ready` snapshot.","type":"string","enum":["creating","ready","failed"]},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the snapshot, billed as snapshot storage.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the snapshot, billed as snapshot storage.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the snapshot failed.","type":"string"},{"type":"null"}]},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the snapshot is deleted.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"readyAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"202":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","content":{"application/json":{"schema":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","type":"object","required":["id","name","applicationId","organizationId","sourceMicrovmId","status","image","vcpus","memoryMb","diskMb","sizeBytes","error","expiresAt","createdAt","readyAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"anyOf":[{"examples":["after-install"],"type":"string"},{"type":"null"}]},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sourceMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM the snapshot was taken of.","type":"string"},{"type":"null"}]},"status":{"default":"creating","description":"New microVMs can be created from a `ready` snapshot.","type":"string","enum":["creating","ready","failed"]},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the snapshot, billed as snapshot storage.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the snapshot, billed as snapshot storage.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the snapshot failed.","type":"string"},{"type":"null"}]},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the snapshot is deleted.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"readyAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"402":{"description":"Response for status 402","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands":{"post":{"operationId":"runMicroVmCommand","summary":"Run a command","description":"Runs a command in a running microVM. By default the request waits for it to exit and returns its exit code and output (up to 1 MiB per stream). With `wait: false` it answers `201` as soon as the command started; stream its output from `GET /microvms/{id}/commands/{cmdId}/logs`.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cmd"],"properties":{"cmd":{"minLength":1,"maxLength":4096,"description":"Program to run, looked up on `PATH`.","examples":["npm"],"type":"string"},"args":{"maxItems":4096,"examples":[["test"]],"type":"array","items":{"maxLength":131072,"type":"string"}},"cwd":{"minLength":1,"maxLength":4096,"description":"Working directory, default the image.","type":"string"},"env":{"description":"Extra environment variables, on top of those set at create.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"user":{"minLength":1,"maxLength":64,"description":"User to run as, default the image user.","type":"string"},"stdin":{"description":"Keep stdin open for `POST .../stdin`. Without it the command reads end of file.","type":"boolean"},"pty":{"description":"Run in a pseudo-terminal of this size; stdout and stderr are merged.","type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}},"timeoutMs":{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","type":"integer"}]},"wait":{"description":"Default `true`: answer with the output once the command exits. `false` answers `201` with the running command; follow it with the logs stream.","type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["cmd"],"properties":{"cmd":{"minLength":1,"maxLength":4096,"description":"Program to run, looked up on `PATH`.","examples":["npm"],"type":"string"},"args":{"maxItems":4096,"examples":[["test"]],"type":"array","items":{"maxLength":131072,"type":"string"}},"cwd":{"minLength":1,"maxLength":4096,"description":"Working directory, default the image.","type":"string"},"env":{"description":"Extra environment variables, on top of those set at create.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"user":{"minLength":1,"maxLength":64,"description":"User to run as, default the image user.","type":"string"},"stdin":{"description":"Keep stdin open for `POST .../stdin`. Without it the command reads end of file.","type":"boolean"},"pty":{"description":"Run in a pseudo-terminal of this size; stdout and stderr are merged.","type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}},"timeoutMs":{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","type":"integer"}]},"wait":{"description":"Default `true`: answer with the output once the command exits. `false` answers `201` with the running command; follow it with the logs stream.","type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","required":["cmd"],"properties":{"cmd":{"minLength":1,"maxLength":4096,"description":"Program to run, looked up on `PATH`.","examples":["npm"],"type":"string"},"args":{"maxItems":4096,"examples":[["test"]],"type":"array","items":{"maxLength":131072,"type":"string"}},"cwd":{"minLength":1,"maxLength":4096,"description":"Working directory, default the image.","type":"string"},"env":{"description":"Extra environment variables, on top of those set at create.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"user":{"minLength":1,"maxLength":64,"description":"User to run as, default the image user.","type":"string"},"stdin":{"description":"Keep stdin open for `POST .../stdin`. Without it the command reads end of file.","type":"boolean"},"pty":{"description":"Run in a pseudo-terminal of this size; stdout and stderr are merged.","type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}},"timeoutMs":{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Kill the command after this many milliseconds. With `wait` the request waits at most 600000 ms.","type":"integer"}]},"wait":{"description":"Default `true`: answer with the output once the command exits. `false` answers `201` with the running command; follow it with the logs stream.","type":"boolean"}}}}}},"responses":{"200":{"description":"The result of a command run to completion.","content":{"application/json":{"schema":{"description":"The result of a command run to completion.","type":"object","required":["id","exitCode","signal","stdout","stderr","truncated","durationMs","timedOut"],"properties":{"id":{"type":"string"},"exitCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"signal":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"stdout":{"description":"UTF-8 decoded standard output, at most 1 MiB.","type":"string"},"stderr":{"description":"UTF-8 decoded standard error, at most 1 MiB.","type":"string"},"truncated":{"description":"Some output was left out: over 1 MiB, or no longer retained.","type":"boolean"},"durationMs":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"timedOut":{"type":"boolean"}}}}}},"201":{"description":"A command started in a microVM.","content":{"application/json":{"schema":{"description":"A command started in a microVM.","type":"object","required":["id","cmd","args","cwd","user","status","exitCode","signal","timedOut","pid","pty","startedAt","finishedAt"],"properties":{"id":{"description":"Command id, unique within the microVM.","type":"string"},"cmd":{"examples":["npm"],"type":"string"},"args":{"examples":[["test"]],"type":"array","items":{"type":"string"}},"cwd":{"examples":["/workspace"],"type":"string"},"user":{"examples":["user"],"type":"string"},"status":{"default":"running","type":"string","enum":["running","exited"]},"exitCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"signal":{"nullable":true,"anyOf":[{"description":"Signal that ended the command, if any.","examples":["SIGKILL"],"type":"string"},{"type":"null"}]},"timedOut":{"description":"The command was killed because it ran past its `timeoutMs`.","type":"boolean"},"pid":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"pty":{"type":"boolean"},"startedAt":{"format":"date-time","type":"string"},"finishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"get":{"operationId":"listMicroVmCommands","summary":"List commands","description":"Lists the commands the microVM still retains, newest first.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"description":"A command started in a microVM.","type":"object","required":["id","cmd","args","cwd","user","status","exitCode","signal","timedOut","pid","pty","startedAt","finishedAt"],"properties":{"id":{"description":"Command id, unique within the microVM.","type":"string"},"cmd":{"examples":["npm"],"type":"string"},"args":{"examples":[["test"]],"type":"array","items":{"type":"string"}},"cwd":{"examples":["/workspace"],"type":"string"},"user":{"examples":["user"],"type":"string"},"status":{"default":"running","type":"string","enum":["running","exited"]},"exitCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"signal":{"nullable":true,"anyOf":[{"description":"Signal that ended the command, if any.","examples":["SIGKILL"],"type":"string"},{"type":"null"}]},"timedOut":{"description":"The command was killed because it ran past its `timeoutMs`.","type":"boolean"},"pid":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"pty":{"type":"boolean"},"startedAt":{"format":"date-time","type":"string"},"finishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}":{"get":{"operationId":"getMicroVmCommand","summary":"Get a command","description":"Reads one command: whether it is still running, its exit code and when it started and ended.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Command id, from `POST /microvms/{id}/commands` or the command list.","type":"string"}}],"responses":{"200":{"description":"A command started in a microVM.","content":{"application/json":{"schema":{"description":"A command started in a microVM.","type":"object","required":["id","cmd","args","cwd","user","status","exitCode","signal","timedOut","pid","pty","startedAt","finishedAt"],"properties":{"id":{"description":"Command id, unique within the microVM.","type":"string"},"cmd":{"examples":["npm"],"type":"string"},"args":{"examples":[["test"]],"type":"array","items":{"type":"string"}},"cwd":{"examples":["/workspace"],"type":"string"},"user":{"examples":["user"],"type":"string"},"status":{"default":"running","type":"string","enum":["running","exited"]},"exitCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"signal":{"nullable":true,"anyOf":[{"description":"Signal that ended the command, if any.","examples":["SIGKILL"],"type":"string"},{"type":"null"}]},"timedOut":{"description":"The command was killed because it ran past its `timeoutMs`.","type":"boolean"},"pid":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"pty":{"type":"boolean"},"startedAt":{"format":"date-time","type":"string"},"finishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}/wait":{"post":{"operationId":"waitMicroVmCommand","summary":"Wait for a command","description":"Waits until the command exits or `timeoutMs` elapses, then returns it. A command still `running` means the wait timed out; call again to keep waiting.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Command id, from `POST /microvms/{id}/commands` or the command list.","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"timeoutMs":{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"timeoutMs":{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"timeoutMs":{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":60000,"description":"Longest to wait, default and maximum 60000 ms.","type":"integer"}]}}}}}},"responses":{"200":{"description":"A command started in a microVM.","content":{"application/json":{"schema":{"description":"A command started in a microVM.","type":"object","required":["id","cmd","args","cwd","user","status","exitCode","signal","timedOut","pid","pty","startedAt","finishedAt"],"properties":{"id":{"description":"Command id, unique within the microVM.","type":"string"},"cmd":{"examples":["npm"],"type":"string"},"args":{"examples":[["test"]],"type":"array","items":{"type":"string"}},"cwd":{"examples":["/workspace"],"type":"string"},"user":{"examples":["user"],"type":"string"},"status":{"default":"running","type":"string","enum":["running","exited"]},"exitCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"signal":{"nullable":true,"anyOf":[{"description":"Signal that ended the command, if any.","examples":["SIGKILL"],"type":"string"},{"type":"null"}]},"timedOut":{"description":"The command was killed because it ran past its `timeoutMs`.","type":"boolean"},"pid":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"pty":{"type":"boolean"},"startedAt":{"format":"date-time","type":"string"},"finishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}/stdin":{"post":{"operationId":"writeMicroVmCommandStdin","summary":"Write to command stdin","description":"Writes the raw request body (`application/octet-stream`) to the stdin of a command started with `stdin: true`, or to its terminal for `pty` commands. `?eof=true` closes stdin afterwards.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Command id, from `POST /microvms/{id}/commands` or the command list.","type":"string"}},{"name":"eof","in":"query","required":false,"schema":{"description":"Close stdin after writing the body (or right away without one).","type":"boolean"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The bytes reached the command.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}/signal":{"post":{"operationId":"signalMicroVmCommand","summary":"Signal a command","description":"Sends a signal to a running command, for example `SIGTERM` to stop it or `SIGINT` for Ctrl-C.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Command id, from `POST /microvms/{id}/commands` or the command list.","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signal"],"properties":{"signal":{"default":"SIGTERM","description":"Signal sent to the command and the processes it started.","type":"string","enum":["SIGTERM","SIGKILL","SIGINT","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2"]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["signal"],"properties":{"signal":{"default":"SIGTERM","description":"Signal sent to the command and the processes it started.","type":"string","enum":["SIGTERM","SIGKILL","SIGINT","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2"]}}}},"multipart/form-data":{"schema":{"type":"object","required":["signal"],"properties":{"signal":{"default":"SIGTERM","description":"Signal sent to the command and the processes it started.","type":"string","enum":["SIGTERM","SIGKILL","SIGINT","SIGHUP","SIGQUIT","SIGUSR1","SIGUSR2"]}}}}}},"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The signal was sent.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}/resize":{"post":{"operationId":"resizeMicroVmCommand","summary":"Resize a command terminal","description":"Resizes the terminal of a command started with `pty`.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","description":"Command id, from `POST /microvms/{id}/commands` or the command list.","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["cols","rows"],"properties":{"cols":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]},"rows":{"minimum":1,"maximum":1000,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1000,"type":"integer"}]}}}}}},"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The terminal was resized.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/commands/{cmdId}/logs":{"get":{"operationId":"streamMicroVmCommandLogs","summary":"Stream command output","description":"Streams the output of a command over Server-Sent Events. Events: `stdout` and `stderr` with `{ data, offset }`, where `data` is base64 and `offset` is the absolute byte offset of its first byte; `truncated` `{}` when part of the requested output is no longer retained (each stream keeps the last 8 MiB); a final `exit` `{ exitCode, signal, timedOut, finishedAt }`. With `follow=false` the stream ends after the retained output, with `exit` if the command already exited and `end` `{ reason: \"snapshot\" }` if it is still running. To resume after a disconnect, reconnect with `stdoutOffset` and `stderrOffset` set past the bytes already received. `error` `{ retryable: true }` reports a failure mid-stream. Concurrent streams are limited per credential and organization.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"cmdId","in":"path","required":true,"schema":{"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$","type":"string"}},{"name":"follow","in":"query","required":false,"schema":{"description":"Default `true`: keep streaming until the command exits. `false` sends the retained output and ends.","type":"boolean"}},{"name":"stdoutOffset","in":"query","required":false,"schema":{"minimum":0,"description":"Resume stdout at this absolute byte offset: the last `offset` plus the decoded length.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Resume stdout at this absolute byte offset: the last `offset` plus the decoded length.","type":"integer"}]}},{"name":"stderrOffset","in":"query","required":false,"schema":{"minimum":0,"description":"Resume stderr at this absolute byte offset.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Resume stderr at this absolute byte offset.","type":"integer"}]}}],"responses":{"200":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only.","content":{"application/json":{"schema":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only."}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}}}}},"/microvms/{id}/files/content":{"get":{"operationId":"readMicroVmFile","summary":"Read a file","description":"Streams a file out of a running microVM as raw bytes (`application/octet-stream`). `offset` and `length` read a range. `x-gigadrive-file-size` carries the full size of the file.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"minimum":0,"description":"First byte to read, default 0.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"First byte to read, default 0.","type":"integer"}]}},{"name":"length","in":"query","required":false,"schema":{"minimum":0,"description":"Most bytes to read, default to the end.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":0,"description":"Most bytes to read, default to the end.","type":"integer"}]}}],"responses":{"200":{"description":"The file bytes (`application/octet-stream`).","content":{"application/json":{"schema":{"description":"The file bytes (`application/octet-stream`)."}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"put":{"operationId":"writeMicroVmFile","summary":"Write a file","description":"Writes the raw request body (`application/octet-stream`) to a file in a running microVM, replacing it atomically. Missing parent directories are created unless `mkdirs=false`.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}},{"name":"mode","in":"query","required":false,"schema":{"pattern":"^0?[0-7]{3,4}$","description":"Permission bits in octal, such as `0644`.","type":"string"}},{"name":"mkdirs","in":"query","required":false,"schema":{"description":"Create missing parent directories. Default `true`.","type":"boolean"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["path","bytes"],"properties":{"path":{"type":"string"},"bytes":{"description":"Size of the file after the write.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size of the file after the write.","type":"integer"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/files":{"get":{"operationId":"listMicroVmFiles","summary":"List a directory","description":"Lists a directory of a running microVM, sorted by path.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}},{"name":"recursive","in":"query","required":false,"schema":{"description":"Include subdirectories. Links are not followed.","type":"boolean"}},{"name":"depth","in":"query","required":false,"schema":{"minimum":1,"maximum":64,"description":"How deep a recursive listing goes.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":64,"description":"How deep a recursive listing goes.","type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["entries","truncated"],"properties":{"entries":{"type":"array","items":{"description":"A file, directory or link in a microVM.","type":"object","required":["path","name","type","size","mode","modifiedAt","target"],"properties":{"path":{"examples":["/workspace/package.json"],"type":"string"},"name":{"examples":["package.json"],"type":"string"},"type":{"default":"file","type":"string","enum":["file","directory","symlink","other"]},"size":{"description":"Size in bytes.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size in bytes.","type":"integer"}]},"mode":{"description":"Permission bits in octal.","examples":["0644"],"type":"string"},"modifiedAt":{"format":"date-time","type":"string"},"target":{"nullable":true,"anyOf":[{"description":"Link target, for symlinks.","type":"string"},{"type":"null"}]}}}},"truncated":{"description":"The listing hit its size limit; list a narrower directory.","type":"boolean"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"removeMicroVmFile","summary":"Remove a file","description":"Removes a file or an empty directory in a running microVM; `recursive=true` removes a directory with its contents.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}},{"name":"recursive","in":"query","required":false,"schema":{"description":"Remove a directory with everything in it.","type":"boolean"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The path was removed.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/files/watch":{"get":{"operationId":"watchMicroVmDirectory","summary":"Watch a directory","description":"Streams the changes in a directory of a running microVM over Server-Sent Events. The response starts once the watch is set up. Events: `ready` `{ path, recursive }` first; `change` `{ type, path, isDirectory }` for every change, where `type` is `create`, `write`, `remove`, `rename` (the old path of a move) or `chmod`, and `overflow` when changes were lost; `end` `{ reason: \"directory_gone\" }` when the watched directory is deleted or moved. `recursive=true` also watches subdirectories, up to 8192 directories. `error` `{ retryable: true }` reports a failure mid-stream, including the microVM stopping. `409` `microvm_watch_unsupported` means the microVM was started before directory watching was available. Concurrent streams are limited per credential and organization.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}},{"name":"recursive","in":"query","required":false,"schema":{"description":"Also watch every subdirectory, and directories created later. Default `false`. Links are not followed.","type":"boolean"}},{"name":"user","in":"query","required":false,"schema":{"minLength":1,"maxLength":64,"description":"User whose permissions the watch uses, default the image user.","type":"string"}}],"responses":{"200":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only.","content":{"application/json":{"schema":{"description":"A `text/event-stream` body. See the endpoint description for the event catalog; this schema is documentation-only."}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"examples":["too_many_concurrent_streams"],"type":"string"},"message":{"type":"string"}}}}}}}}},"/microvms/{id}/files/stat":{"get":{"operationId":"statMicroVmFile","summary":"Get file information","description":"Reads the type, size, permissions and modification time of a path in a running microVM.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"path","in":"query","required":true,"schema":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"}}],"responses":{"200":{"description":"A file, directory or link in a microVM.","content":{"application/json":{"schema":{"description":"A file, directory or link in a microVM.","type":"object","required":["path","name","type","size","mode","modifiedAt","target"],"properties":{"path":{"examples":["/workspace/package.json"],"type":"string"},"name":{"examples":["package.json"],"type":"string"},"type":{"default":"file","type":"string","enum":["file","directory","symlink","other"]},"size":{"description":"Size in bytes.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size in bytes.","type":"integer"}]},"mode":{"description":"Permission bits in octal.","examples":["0644"],"type":"string"},"modifiedAt":{"format":"date-time","type":"string"},"target":{"nullable":true,"anyOf":[{"description":"Link target, for symlinks.","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/files/mkdir":{"post":{"operationId":"makeMicroVmDirectory","summary":"Create a directory","description":"Creates a directory in a running microVM. An existing directory is not an error.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path"],"properties":{"path":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"parents":{"description":"Create missing parent directories. Default `true`.","type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["path"],"properties":{"path":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"parents":{"description":"Create missing parent directories. Default `true`.","type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","required":["path"],"properties":{"path":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"parents":{"description":"Create missing parent directories. Default `true`.","type":"boolean"}}}}}},"responses":{"200":{"description":"A file, directory or link in a microVM.","content":{"application/json":{"schema":{"description":"A file, directory or link in a microVM.","type":"object","required":["path","name","type","size","mode","modifiedAt","target"],"properties":{"path":{"examples":["/workspace/package.json"],"type":"string"},"name":{"examples":["package.json"],"type":"string"},"type":{"default":"file","type":"string","enum":["file","directory","symlink","other"]},"size":{"description":"Size in bytes.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size in bytes.","type":"integer"}]},"mode":{"description":"Permission bits in octal.","examples":["0644"],"type":"string"},"modifiedAt":{"format":"date-time","type":"string"},"target":{"nullable":true,"anyOf":[{"description":"Link target, for symlinks.","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/files/move":{"post":{"operationId":"moveMicroVmFile","summary":"Move a file","description":"Moves or renames a file or directory in a running microVM. Returns the entry at its new path.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"to":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"overwrite":{"description":"Replace an existing `to`. Default `false`.","type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"to":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"overwrite":{"description":"Replace an existing `to`. Default `false`.","type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","required":["from","to"],"properties":{"from":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"to":{"minLength":1,"maxLength":4096,"description":"Absolute path in the microVM, or a path relative to the working directory of the image.","examples":["/workspace/index.js"],"type":"string"},"overwrite":{"description":"Replace an existing `to`. Default `false`.","type":"boolean"}}}}}},"responses":{"200":{"description":"A file, directory or link in a microVM.","content":{"application/json":{"schema":{"description":"A file, directory or link in a microVM.","type":"object","required":["path","name","type","size","mode","modifiedAt","target"],"properties":{"path":{"examples":["/workspace/package.json"],"type":"string"},"name":{"examples":["package.json"],"type":"string"},"type":{"default":"file","type":"string","enum":["file","directory","symlink","other"]},"size":{"description":"Size in bytes.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size in bytes.","type":"integer"}]},"mode":{"description":"Permission bits in octal.","examples":["0644"],"type":"string"},"modifiedAt":{"format":"date-time","type":"string"},"target":{"nullable":true,"anyOf":[{"description":"Link target, for symlinks.","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"413":{"description":"Response for status 413","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"502":{"description":"Response for status 502","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvms/{id}/metrics":{"get":{"operationId":"getMicroVmMetrics","summary":"Get microVM metrics","description":"Returns the microVM's CPU use over the last `windowMinutes`, in points of at least 5 seconds, and, while it runs, its memory and disk use as the microVM itself reports them. Reading metrics never resumes a paused microVM.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-333333333333"],"type":"string"}},{"name":"windowMinutes","in":"query","required":false,"schema":{"minimum":1,"maximum":1440,"description":"How far back the CPU series reaches, in minutes. Default 15, at most one day.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":1440,"description":"How far back the CPU series reaches, in minutes. Default 15, at most one day.","type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["microvmId","vcpus","memoryMb","windowMinutes","stepSeconds","cpu","current"],"properties":{"microvmId":{"type":"string"},"vcpus":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"memoryMb":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"windowMinutes":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"stepSeconds":{"description":"Length of each CPU point, at least 5 seconds.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Length of each CPU point, at least 5 seconds.","type":"integer"}]},"cpu":{"description":"Points with no CPU sample (the microVM was not running) are omitted.","type":"array","items":{"type":"object","required":["time","cpuPercent"],"properties":{"time":{"format":"date-time","description":"Start of the point.","type":"string"},"cpuPercent":{"description":"CPU the microVM used over the point, as a share of all its vCPUs (0 to 100).","type":"number"}}}},"current":{"nullable":true,"anyOf":[{"description":"The microVM's own memory and disk use right now. `null` unless it is running and answered within 3 seconds.","type":"object","required":["sampledAt","uptimeMs","memoryUsedBytes","memoryTotalBytes","diskUsedBytes","diskTotalBytes"],"properties":{"sampledAt":{"format":"date-time","type":"string"},"uptimeMs":{"type":"number"},"memoryUsedBytes":{"description":"Memory in use inside the microVM (total minus available).","type":"number"},"memoryTotalBytes":{"type":"number"},"diskUsedBytes":{"description":"Space in use on the microVM disk.","type":"number"},"diskTotalBytes":{"type":"number"}}},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-images":{"get":{"operationId":"listMicroVmImages","summary":"List microVM images","description":"Lists the built-in images, then the application's own images by name.","tags":["MicroVMs"],"parameters":[{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Also list this application's own images. Inferred for application, deployment and function credentials.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"description":"An image microVMs boot from.","type":"object","required":["id","name","builtin","applicationId","organizationId","status","source","sourceDigest","sizeBytes","error","buildStartedAt","buildFinishedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"},"builtin":{"description":"Provided by Gigadrive and available to every application.","type":"boolean"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"organizationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"status":{"default":"pending","type":"string","enum":["pending","building","ready","failed"]},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"type":"string"}}}]},"sourceDigest":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Size of the unpacked root filesystem.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size of the unpacked root filesystem.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the last build failed.","type":"string"},{"type":"null"}]},"buildStartedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"buildFinishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"post":{"operationId":"createMicroVmImage","summary":"Create a microVM image","description":"Builds a custom image from a public registry image or a Dockerfile. Answers `202` right away; the image is `ready` once the build finished (poll `GET /microvm-images/{id}`). The plan limits how many images an organization keeps.","tags":["MicroVMs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","source"],"properties":{"applicationId":{"format":"uuid","description":"Application the image belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"pattern":"^[a-z0-9][a-z0-9._-]{0,62}$","description":"Name to boot the image by, unique within the application: lowercase letters, digits, `.`, `_` and `-`.","examples":["my-tools"],"type":"string"},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"minLength":1,"maxLength":512,"description":"Public linux/amd64 image reference.","examples":["python:3.13-bookworm"],"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"minLength":1,"maxLength":262144,"description":"Dockerfile to build.","type":"string"}}}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name","source"],"properties":{"applicationId":{"format":"uuid","description":"Application the image belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"pattern":"^[a-z0-9][a-z0-9._-]{0,62}$","description":"Name to boot the image by, unique within the application: lowercase letters, digits, `.`, `_` and `-`.","examples":["my-tools"],"type":"string"},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"minLength":1,"maxLength":512,"description":"Public linux/amd64 image reference.","examples":["python:3.13-bookworm"],"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"minLength":1,"maxLength":262144,"description":"Dockerfile to build.","type":"string"}}}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["name","source"],"properties":{"applicationId":{"format":"uuid","description":"Application the image belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"pattern":"^[a-z0-9][a-z0-9._-]{0,62}$","description":"Name to boot the image by, unique within the application: lowercase letters, digits, `.`, `_` and `-`.","examples":["my-tools"],"type":"string"},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"minLength":1,"maxLength":512,"description":"Public linux/amd64 image reference.","examples":["python:3.13-bookworm"],"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"minLength":1,"maxLength":262144,"description":"Dockerfile to build.","type":"string"}}}]}}}}}},"responses":{"202":{"description":"An image microVMs boot from.","content":{"application/json":{"schema":{"description":"An image microVMs boot from.","type":"object","required":["id","name","builtin","applicationId","organizationId","status","source","sourceDigest","sizeBytes","error","buildStartedAt","buildFinishedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"},"builtin":{"description":"Provided by Gigadrive and available to every application.","type":"boolean"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"organizationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"status":{"default":"pending","type":"string","enum":["pending","building","ready","failed"]},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"type":"string"}}}]},"sourceDigest":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Size of the unpacked root filesystem.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size of the unpacked root filesystem.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the last build failed.","type":"string"},{"type":"null"}]},"buildStartedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"buildFinishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-images/{id}":{"get":{"operationId":"getMicroVmImage","summary":"Get a microVM image","description":"Reads one image, including its build status and the reason a build failed.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM image id, from the image list.","type":"string"}}],"responses":{"200":{"description":"An image microVMs boot from.","content":{"application/json":{"schema":{"description":"An image microVMs boot from.","type":"object","required":["id","name","builtin","applicationId","organizationId","status","source","sourceDigest","sizeBytes","error","buildStartedAt","buildFinishedAt","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"},"builtin":{"description":"Provided by Gigadrive and available to every application.","type":"boolean"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"organizationId":{"nullable":true,"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"status":{"default":"pending","type":"string","enum":["pending","building","ready","failed"]},"source":{"anyOf":[{"type":"object","required":["type","ref"],"properties":{"type":{"const":"registry","type":"string"},"ref":{"type":"string"}}},{"type":"object","required":["type","dockerfile"],"properties":{"type":{"const":"dockerfile","type":"string"},"dockerfile":{"type":"string"}}}]},"sourceDigest":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Size of the unpacked root filesystem.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Size of the unpacked root filesystem.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the last build failed.","type":"string"},{"type":"null"}]},"buildStartedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"buildFinishedAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"deleteMicroVmImage","summary":"Delete a microVM image","description":"Deletes one of your images. Refused while a running microVM uses it. Built-in images cannot be deleted.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"microVM image id, from the image list.","type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The image was deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-snapshots":{"get":{"operationId":"listMicroVmSnapshots","summary":"List microVM snapshots","description":"Lists an application's microVM snapshots, newest first. Page with `cursor`.","tags":["MicroVMs"],"parameters":[{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Application whose snapshots to list. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"format":"uuid","description":"`pagination.nextCursor` of the previous page. Omit for the first page.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","type":"object","required":["id","name","applicationId","organizationId","sourceMicrovmId","status","image","vcpus","memoryMb","diskMb","sizeBytes","error","expiresAt","createdAt","readyAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"anyOf":[{"examples":["after-install"],"type":"string"},{"type":"null"}]},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sourceMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM the snapshot was taken of.","type":"string"},{"type":"null"}]},"status":{"default":"creating","description":"New microVMs can be created from a `ready` snapshot.","type":"string","enum":["creating","ready","failed"]},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the snapshot, billed as snapshot storage.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the snapshot, billed as snapshot storage.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the snapshot failed.","type":"string"},{"type":"null"}]},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the snapshot is deleted.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"readyAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}},"pagination":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"nullable":true,"anyOf":[{"description":"Pass as `cursor` to read the next page.","type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-snapshots/{id}":{"get":{"operationId":"getMicroVmSnapshot","summary":"Get a microVM snapshot","description":"Reads one microVM snapshot: its status, size, image and when it expires.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Snapshot id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-444444444444"],"type":"string"}}],"responses":{"200":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","content":{"application/json":{"schema":{"description":"A snapshot of a microVM: its memory and disk, ready to create new microVMs from.","type":"object","required":["id","name","applicationId","organizationId","sourceMicrovmId","status","image","vcpus","memoryMb","diskMb","sizeBytes","error","expiresAt","createdAt","readyAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"nullable":true,"anyOf":[{"examples":["after-install"],"type":"string"},{"type":"null"}]},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sourceMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM the snapshot was taken of.","type":"string"},{"type":"null"}]},"status":{"default":"creating","description":"New microVMs can be created from a `ready` snapshot.","type":"string","enum":["creating","ready","failed"]},"image":{"type":"object","required":["id","name"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["node22"],"type":"string"}}},"vcpus":{"examples":[1],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[1],"type":"integer"}]},"memoryMb":{"examples":[2048],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[2048],"type":"integer"}]},"diskMb":{"examples":[10240],"anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"type":"integer"}]},"sizeBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the snapshot, billed as snapshot storage.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the snapshot, billed as snapshot storage.","type":"integer"}]},{"type":"null"}]},"error":{"nullable":true,"anyOf":[{"description":"Why the snapshot failed.","type":"string"},{"type":"null"}]},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the snapshot is deleted.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"readyAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"deleteMicroVmSnapshot","summary":"Delete a microVM snapshot","description":"Deletes a snapshot: no new microVM can be created from it, and its storage stops being billed. microVMs already created from it keep running.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Snapshot id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-444444444444"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The snapshot is deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-volumes":{"post":{"operationId":"createMicroVmVolume","summary":"Create a microVM volume","description":"Creates an empty, persistent filesystem. Attach it to a microVM with `volumes` on `POST /microvms`; the first microVM that attaches it formats it. Its contents are saved when that microVM stops, and the next microVM that attaches it, on any host, sees what was saved. `409 microvm_volume_exists` means the application already has a volume of that name. The plan limits how many volumes an organization keeps.","tags":["MicroVMs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"applicationId":{"format":"uuid","description":"Application the volume belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"},"sizeMb":{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name"],"properties":{"applicationId":{"format":"uuid","description":"Application the volume belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"},"sizeMb":{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"applicationId":{"format":"uuid","description":"Application the volume belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"},"sizeMb":{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1024,"maximum":51200,"description":"Size of the filesystem in MB, default 10240. It cannot change later.","type":"integer"}]}}}}}},"responses":{"201":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","content":{"application/json":{"schema":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","type":"object","required":["id","name","applicationId","organizationId","sizeMb","storedBytes","status","attachedMicrovmId","lastSavedAt","lastSaveError","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["workspace"],"type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sizeMb":{"examples":[10240],"description":"Size of the filesystem in MB.","anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"description":"Size of the filesystem in MB.","type":"integer"}]},"storedBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","type":"integer"}]},{"type":"null"}]},"status":{"default":"available","description":"`available`: can be attached. `in_use`: attached to a microVM. `saving`: its microVM is saving it (a stop or `POST /microvms/{id}/volumes/save`).","type":"string","enum":["available","in_use","saving"]},"attachedMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM using the volume.","type":"string"},{"type":"null"}]},"lastSavedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the volume was last saved.","type":"string"},{"type":"null"}]},"lastSaveError":{"nullable":true,"anyOf":[{"description":"Why the last save failed. The volume kept the contents of its previous save.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"get":{"operationId":"listMicroVmVolumes","summary":"List microVM volumes","description":"Lists an application's microVM volumes, newest first. Page with `cursor`.","tags":["MicroVMs"],"parameters":[{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Application whose volumes to list. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"format":"uuid","description":"`pagination.nextCursor` of the previous page. Omit for the first page.","type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":20,"description":"Page size, 1 to 100.","type":"integer"}]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","type":"object","required":["id","name","applicationId","organizationId","sizeMb","storedBytes","status","attachedMicrovmId","lastSavedAt","lastSaveError","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["workspace"],"type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sizeMb":{"examples":[10240],"description":"Size of the filesystem in MB.","anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"description":"Size of the filesystem in MB.","type":"integer"}]},"storedBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","type":"integer"}]},{"type":"null"}]},"status":{"default":"available","description":"`available`: can be attached. `in_use`: attached to a microVM. `saving`: its microVM is saving it (a stop or `POST /microvms/{id}/volumes/save`).","type":"string","enum":["available","in_use","saving"]},"attachedMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM using the volume.","type":"string"},{"type":"null"}]},"lastSavedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the volume was last saved.","type":"string"},{"type":"null"}]},"lastSaveError":{"nullable":true,"anyOf":[{"description":"Why the last save failed. The volume kept the contents of its previous save.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}},"pagination":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"nullable":true,"anyOf":[{"description":"Pass as `cursor` to read the next page.","type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-volumes/{id}":{"get":{"operationId":"getMicroVmVolume","summary":"Get a microVM volume","description":"Reads one microVM volume: its size, whether a microVM uses it, and when it was last saved.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Volume id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-555555555555"],"type":"string"}}],"responses":{"200":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","content":{"application/json":{"schema":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","type":"object","required":["id","name","applicationId","organizationId","sizeMb","storedBytes","status","attachedMicrovmId","lastSavedAt","lastSaveError","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["workspace"],"type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sizeMb":{"examples":[10240],"description":"Size of the filesystem in MB.","anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"description":"Size of the filesystem in MB.","type":"integer"}]},"storedBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","type":"integer"}]},{"type":"null"}]},"status":{"default":"available","description":"`available`: can be attached. `in_use`: attached to a microVM. `saving`: its microVM is saving it (a stop or `POST /microvms/{id}/volumes/save`).","type":"string","enum":["available","in_use","saving"]},"attachedMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM using the volume.","type":"string"},{"type":"null"}]},"lastSavedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the volume was last saved.","type":"string"},{"type":"null"}]},"lastSaveError":{"nullable":true,"anyOf":[{"description":"Why the last save failed. The volume kept the contents of its previous save.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"patch":{"operationId":"updateMicroVmVolume","summary":"Rename a microVM volume","description":"Renames a volume, also while a microVM uses it. `409 microvm_volume_exists` means the application already has a volume of that name.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Volume id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-555555555555"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"minLength":1,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"Unique per application: 1 to 64 lowercase letters, digits and dashes, starting with a letter or digit.","examples":["workspace"],"type":"string"}}}}}},"responses":{"200":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","content":{"application/json":{"schema":{"description":"A persistent filesystem that outlives the microVMs it is attached to.","type":"object","required":["id","name","applicationId","organizationId","sizeMb","storedBytes","status","attachedMicrovmId","lastSavedAt","lastSaveError","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"name":{"examples":["workspace"],"type":"string"},"applicationId":{"format":"uuid","type":"string"},"organizationId":{"format":"uuid","type":"string"},"sizeMb":{"examples":[10240],"description":"Size of the filesystem in MB.","anyOf":[{"format":"integer","default":0,"type":"string"},{"examples":[10240],"description":"Size of the filesystem in MB.","type":"integer"}]},"storedBytes":{"nullable":true,"anyOf":[{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Stored size of the last save, billed as snapshot storage. `null` until saved.","type":"integer"}]},{"type":"null"}]},"status":{"default":"available","description":"`available`: can be attached. `in_use`: attached to a microVM. `saving`: its microVM is saving it (a stop or `POST /microvms/{id}/volumes/save`).","type":"string","enum":["available","in_use","saving"]},"attachedMicrovmId":{"nullable":true,"anyOf":[{"format":"uuid","description":"The microVM using the volume.","type":"string"},{"type":"null"}]},"lastSavedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the volume was last saved.","type":"string"},{"type":"null"}]},"lastSaveError":{"nullable":true,"anyOf":[{"description":"Why the last save failed. The volume kept the contents of its previous save.","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"deleteMicroVmVolume","summary":"Delete a microVM volume","description":"Deletes a volume and its saved contents; its storage stops being billed. `409 microvm_volume_in_use` means a microVM still uses it: stop that microVM first.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Volume id, from create or list.","examples":["0197b2f1-2f4a-7a0b-8a2d-555555555555"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The volume and its saved contents are deleted.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"409":{"description":"Response for status 409","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-webhooks":{"get":{"operationId":"listMicroVmWebhooks","summary":"List microVM webhooks","description":"Lists an application's microVM webhooks, oldest first. Secrets are not included.","tags":["MicroVMs"],"parameters":[{"name":"applicationId","in":"query","required":false,"schema":{"format":"uuid","description":"Application whose webhooks to list. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"description":"An endpoint that receives microVM lifecycle events.","type":"object","required":["id","applicationId","url","description","events","enabled","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"url":{"type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"post":{"operationId":"createMicroVmWebhook","summary":"Create a microVM webhook","description":"Registers an HTTPS endpoint for microVM lifecycle events of the application. The answer carries the signing secret, which is shown only once. An application has at most 10 webhooks.","tags":["MicroVMs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"applicationId":{"format":"uuid","description":"Application the webhook belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"maxLength":255,"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["url","events"],"properties":{"applicationId":{"format":"uuid","description":"Application the webhook belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"maxLength":255,"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["url","events"],"properties":{"applicationId":{"format":"uuid","description":"Application the webhook belongs to. Required for user and organization credentials; inferred for application, deployment and function credentials.","type":"string"},"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"maxLength":255,"type":"string"}}}}}},"responses":{"201":{"description":"Response for status 201","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","url","description","events","enabled","createdAt","updatedAt","secret"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"url":{"type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"secret":{"description":"Signing secret (`whsec_...`), shown only now and on rotation. Each request carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers (Standard Webhooks).","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-webhooks/{id}":{"get":{"operationId":"getMicroVmWebhook","summary":"Get a microVM webhook","description":"Reads one webhook. The secret is not included.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Webhook id.","type":"string"}}],"responses":{"200":{"description":"An endpoint that receives microVM lifecycle events.","content":{"application/json":{"schema":{"description":"An endpoint that receives microVM lifecycle events.","type":"object","required":["id","applicationId","url","description","events","enabled","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"url":{"type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"patch":{"operationId":"updateMicroVmWebhook","summary":"Update a microVM webhook","description":"Changes the URL, events, description or enabled state of a webhook.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Webhook id.","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"nullable":true,"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}]},"enabled":{"description":"A disabled webhook receives no new events.","type":"boolean"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"nullable":true,"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}]},"enabled":{"description":"A disabled webhook receives no new events.","type":"boolean"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"url":{"minLength":1,"maxLength":2048,"description":"HTTPS URL the events are POSTed to. Private and local addresses are refused.","examples":["https://example.com/hooks/microvms"],"type":"string"},"events":{"minItems":1,"maxItems":5,"uniqueItems":true,"description":"Events to receive. `microvm.created` when a microVM is created; `microvm.running` when it starts or resumes; `microvm.paused`, `microvm.stopped` and `microvm.failed` when it reaches that state.","type":"array","items":{"default":"microvm.created","type":"string","enum":["microvm.created","microvm.running","microvm.paused","microvm.stopped","microvm.failed"]}},"description":{"nullable":true,"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}]},"enabled":{"description":"A disabled webhook receives no new events.","type":"boolean"}}}}}},"responses":{"200":{"description":"An endpoint that receives microVM lifecycle events.","content":{"application/json":{"schema":{"description":"An endpoint that receives microVM lifecycle events.","type":"object","required":["id","applicationId","url","description","events","enabled","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"url":{"type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}},"delete":{"operationId":"deleteMicroVmWebhook","summary":"Delete a microVM webhook","description":"Deletes a webhook and its pending deliveries.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Webhook id.","type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"type":"void"}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-webhooks/{id}/secret":{"post":{"operationId":"rotateMicroVmWebhookSecret","summary":"Rotate a microVM webhook secret","description":"Replaces the signing secret. The old one stops signing requests at once.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Webhook id.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","applicationId","url","description","events","enabled","createdAt","updatedAt","secret"],"properties":{"id":{"format":"uuid","type":"string"},"applicationId":{"format":"uuid","type":"string"},"url":{"type":"string"},"description":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"secret":{"description":"Signing secret (`whsec_...`), shown only now and on rotation. Each request carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers (Standard Webhooks).","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/microvm-webhooks/{id}/deliveries":{"get":{"operationId":"listMicroVmWebhookDeliveries","summary":"List microVM webhook deliveries","description":"The webhook's 50 most recent deliveries, newest first, with their attempts and the last response. A delivery is retried with backoff for about a day before it fails.","tags":["MicroVMs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"format":"uuid","description":"Webhook id.","type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","messageId","eventType","microvmId","status","attempts","lastStatusCode","lastError","nextAttemptAt","deliveredAt","createdAt"],"properties":{"id":{"format":"uuid","type":"string"},"messageId":{"description":"The `webhook-id` header of the request.","type":"string"},"eventType":{"type":"string"},"microvmId":{"format":"uuid","type":"string"},"status":{"default":"pending","type":"string","enum":["pending","delivered","failed"]},"attempts":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"lastStatusCode":{"nullable":true,"anyOf":[{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},{"type":"null"}]},"lastError":{"nullable":true,"anyOf":[{"type":"string"},{"type":"null"}]},"nextAttemptAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"deliveredAt":{"nullable":true,"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","type":"string"}}}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed.","type":"string"},"code":{"description":"Stable machine-readable error code.","examples":["not_found"],"type":"string"}}}}}}}}},"/api-keys":{"get":{"operationId":"listApiKeys","summary":"List application API keys","description":"Lists the API keys scoped to an application. Secrets are never returned — only key metadata (id, name, scopes, expiry). Use this to audit or revoke keys.","tags":["API Keys"],"parameters":[{"name":"applicationId","in":"query","required":true,"schema":{"format":"uuid","description":"Application whose API keys should be listed.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","name","applicationId","scopes","expiresAt","lastUsedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Human-readable label for the API key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application this key is scoped to. The key can only act on this application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"scopes":{"description":"API capability scopes granted to this key.","type":"array","items":{"description":"API capability scope granted to this key.","examples":["network:env_vars:read"],"type":"string"}},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key expires, or null if it never expires.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"lastUsedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key last exchanged a token or authenticated a request, or null if it has never been used. Recorded at most once every few minutes, so it can trail the most recent use.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/apiKey"}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}},"post":{"operationId":"createApiKey","summary":"Create an application-scoped API key","description":"Provisions a new API key bound to an application. The key is least-privilege: its actor is the application (not you) and its scopes must be a subset of your own access. The plaintext secret is returned exactly once — store it immediately, as it cannot be retrieved again. Use the returned `id` and `secret` as OAuth client credentials against `/oauth2/token`.","tags":["API Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","applicationId"],"properties":{"name":{"minLength":1,"maxLength":255,"description":"Human-readable label for the key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"format":"uuid","description":"Application to scope the key to. The key can only act on this application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"scopes":{"description":"API capability scopes to grant. Each must be a subset of your own access and cannot include API key management. Defaults to a minimal read-only set when omitted.","type":"array","items":{"description":"API capability scope to grant.","examples":["network:env_vars:read"],"type":"string"}},"expiresAt":{"format":"date-time","description":"Optional expiry. Defaults to 90 days when omitted. Must be in the future and at most 365 days away.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["name","applicationId"],"properties":{"name":{"minLength":1,"maxLength":255,"description":"Human-readable label for the key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"format":"uuid","description":"Application to scope the key to. The key can only act on this application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"scopes":{"description":"API capability scopes to grant. Each must be a subset of your own access and cannot include API key management. Defaults to a minimal read-only set when omitted.","type":"array","items":{"description":"API capability scope to grant.","examples":["network:env_vars:read"],"type":"string"}},"expiresAt":{"format":"date-time","description":"Optional expiry. Defaults to 90 days when omitted. Must be in the future and at most 365 days away.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["name","applicationId"],"properties":{"name":{"minLength":1,"maxLength":255,"description":"Human-readable label for the key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"format":"uuid","description":"Application to scope the key to. The key can only act on this application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"scopes":{"description":"API capability scopes to grant. Each must be a subset of your own access and cannot include API key management. Defaults to a minimal read-only set when omitted.","type":"array","items":{"description":"API capability scope to grant.","examples":["network:env_vars:read"],"type":"string"}},"expiresAt":{"format":"date-time","description":"Optional expiry. Defaults to 90 days when omitted. Must be in the future and at most 365 days away.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","name","applicationId","scopes","expiresAt","secret","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Human-readable label for the API key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application this key is scoped to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"scopes":{"description":"API capability scopes granted to this key.","type":"array","items":{"description":"API capability scope granted to this key.","type":"string"}},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key expires, or null if it never expires.","type":"string"},{"type":"null"}]},"secret":{"description":"The plaintext client secret. Returned only once at creation time and never retrievable again — store it now. Use it together with the key `id` as OAuth client credentials.","examples":["gdnet_secret_QWxhZGRpbjpvcGVuc2VzYW1l"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/apiKeyWithSecret"}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/api-keys/{apiKeyId}":{"delete":{"operationId":"deleteApiKey","summary":"Revoke an API key","description":"Permanently revokes an application-scoped API key. Revocation is immediate: tokens already issued from the key stop authenticating on their next request, and no new tokens can be minted from it.","tags":["API Keys"],"parameters":[{"name":"apiKeyId","in":"path","required":true,"schema":{"format":"uuid","description":"API key to revoke.","examples":["0197b2fa-b4c6-7561-8db2-aaaaaaaaaaaa"],"type":"string"}}],"responses":{"204":{"description":"Response for status 204","content":{"application/json":{"schema":{"anyOf":[{"description":"The API key was revoked.","type":"null"},{"type":"null"},{"type":"undefined"}]}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/sticky-sessions/urls":{"post":{"operationId":"createStickySessionUrl","summary":"Create a sticky session URL","description":"Creates a signed URL that keeps HTTP, streaming, or WebSocket traffic for an opaque key on the same execution environment. The URL controls routing only and does not authenticate the application user.","tags":["Sticky Sessions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","endpoint"],"properties":{"key":{"minLength":1,"maxLength":512,"description":"Opaque application-defined sticky key.","type":"string"},"endpoint":{"minLength":1,"maxLength":2048,"description":"Relative route within the current immutable deployment hostname.","examples":["/socket"],"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE","HEAD","OPTIONS","PATCH"]},"expiresInSeconds":{"minimum":60,"maximum":86400,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":86400,"type":"integer"}]}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["key","endpoint"],"properties":{"key":{"minLength":1,"maxLength":512,"description":"Opaque application-defined sticky key.","type":"string"},"endpoint":{"minLength":1,"maxLength":2048,"description":"Relative route within the current immutable deployment hostname.","examples":["/socket"],"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE","HEAD","OPTIONS","PATCH"]},"expiresInSeconds":{"minimum":60,"maximum":86400,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":86400,"type":"integer"}]}}}},"multipart/form-data":{"schema":{"type":"object","required":["key","endpoint"],"properties":{"key":{"minLength":1,"maxLength":512,"description":"Opaque application-defined sticky key.","type":"string"},"endpoint":{"minLength":1,"maxLength":2048,"description":"Relative route within the current immutable deployment hostname.","examples":["/socket"],"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE","HEAD","OPTIONS","PATCH"]},"expiresInSeconds":{"minimum":60,"maximum":86400,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":60,"maximum":86400,"type":"integer"}]}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["url","expiresAt"],"properties":{"url":{"format":"uri","type":"string"},"expiresAt":{"format":"date-time","type":"string"}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"503":{"description":"Response for status 503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/ai/v1/audio/speech":{"post":{"tags":["AI Gateway"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input","voice"],"properties":{"model":{"description":"Speech-capable AI Gateway model identifier.","type":"string"},"input":{"description":"Text to synthesize.","type":"string"},"voice":{"description":"Provider voice identifier.","type":"string"},"response_format":{"type":"string","enum":["mp3","opus","aac","flac","wav","pcm"]},"speed":{"minimum":0.25,"maximum":4,"type":"number"},"provider":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"allow_fallbacks":{"type":"boolean"},"require_zdr":{"type":"boolean"}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["model","input","voice"],"properties":{"model":{"description":"Speech-capable AI Gateway model identifier.","type":"string"},"input":{"description":"Text to synthesize.","type":"string"},"voice":{"description":"Provider voice identifier.","type":"string"},"response_format":{"type":"string","enum":["mp3","opus","aac","flac","wav","pcm"]},"speed":{"minimum":0.25,"maximum":4,"type":"number"},"provider":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"allow_fallbacks":{"type":"boolean"},"require_zdr":{"type":"boolean"}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["model","input","voice"],"properties":{"model":{"description":"Speech-capable AI Gateway model identifier.","type":"string"},"input":{"description":"Text to synthesize.","type":"string"},"voice":{"description":"Provider voice identifier.","type":"string"},"response_format":{"type":"string","enum":["mp3","opus","aac","flac","wav","pcm"]},"speed":{"minimum":0.25,"maximum":4,"type":"number"},"provider":{"type":"object","properties":{"order":{"type":"array","items":{"type":"string"}},"allow_fallbacks":{"type":"boolean"},"require_zdr":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}},"operationId":"postAiV1AudioSpeech"}},"/ai/v1/audio/transcriptions":{"post":{"tags":["AI Gateway"],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}},"operationId":"postAiV1AudioTranscriptions"}},"/ai/v1/videos/models":{"get":{"tags":["AI Gateway"],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["object","data"],"properties":{"object":{"const":"list","type":"string"},"data":{"type":"array","items":{}}}}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}},"operationId":"getAiV1VideosModels"}},"/ai/v1/videos":{"post":{"tags":["AI Gateway"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}},"multipart/form-data":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}},"operationId":"postAiV1Videos"}},"/ai/v1/chat/completions":{"post":{"tags":["AI Gateway"],"operationId":"createAiChatCompletion","summary":"Create chat completion","description":"Creates a chat completion through Gigadrive AI Gateway using the OpenAI-compatible Chat Completions shape. The gateway routes requests across configured model providers, applies the authenticated actor and scope checks, and can fall back between providers when a model supports multiple routes. Use this endpoint when integrating existing OpenAI-style chat clients while centralizing provider credentials and model access in Gigadrive.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"messages":{"description":"Conversation turns that define the context the selected model should answer.","type":"array","items":{"anyOf":[{"type":"object","required":["role","content"],"properties":{"role":{"description":"System message that sets behavior for the model.","const":"system","type":"string"},"content":{"description":"System instruction text, or null to preserve OpenAI-compatible shape.","anyOf":[{"description":"System instruction text sent to the model.","type":"string"},{"type":"null"}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"User message representing input from the end user or calling application.","const":"user","type":"string"},"content":{"description":"User input as text, multimodal content parts, or null for provider-compatible empty content.","anyOf":[{"description":"User text sent to the model.","type":"string"},{"type":"null"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"text","type":"string"},"text":{"description":"Text content sent to the selected chat model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as an image input for vision-capable models.","const":"image_url","type":"string"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Image URL or supported data URL passed to the model provider.","type":"string"},"detail":{"description":"Vision detail level requested from providers that support image detail controls.","anyOf":[{"const":"auto","type":"string"},{"const":"low","type":"string"},{"const":"high","type":"string"}]}}}}},{"type":"object","required":["type","file"],"properties":{"type":{"description":"Marks this content part as a file input for OpenRouter-compatible file models.","const":"file","type":"string"},"file":{"type":"object","properties":{"filename":{"description":"Optional filename supplied to the provider.","type":"string"},"file_data":{"description":"File URL or base64 data URL supplied to the provider.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as a video input for OpenRouter-compatible video models.","const":"video_url","type":"string"},"video_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}}}]}}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"Assistant message from prior model output, usually used to continue a conversation.","const":"assistant","type":"string"},"content":{"description":"Assistant text from previous turns, or null when the turn only contains tool calls.","anyOf":[{"description":"Assistant text produced by a previous model turn.","type":"string"},{"type":"null"}]},"name":{"description":"Optional assistant participant name.","type":"string"},"tool_calls":{"description":"Tool calls emitted by the assistant in a previous turn.","type":"array","items":{"type":"object","required":["id","type","function"],"properties":{"id":{"description":"Provider-generated tool call ID that must be referenced by the matching tool response.","type":"string"},"type":{"description":"Tool call type. AI Gateway currently supports function tool calls.","const":"function","type":"string"},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"description":"Function name selected by the model.","type":"string"},"arguments":{"description":"JSON string containing the function arguments generated by the model.","type":"string"}}}}}}}},{"type":"object","required":["role","content","tool_call_id"],"properties":{"role":{"description":"Tool result message supplied after executing a model-requested function.","const":"tool","type":"string"},"content":{"description":"Tool execution result content returned to the model.","anyOf":[{"description":"Serialized result returned by the executed tool.","type":"string"},{"type":"null"}]},"tool_call_id":{"description":"The ID of the tool call this message is responding to (required for tool messages)","type":"string"}}}]}},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"n":{"minimum":1,"maximum":1,"description":"Number of completion choices. AI Gateway always returns a single choice.","examples":[1],"type":"number"},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"stop":{"description":"Stop sequence or sequences where generation should end.","anyOf":[{"description":"Single stop sequence where generation should end.","type":"string"},{"type":"array","items":{"description":"Stop sequence where generation should end.","type":"string"}}]},"max_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"presence_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating topics already present in the conversation.","type":"number"},"frequency_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating tokens that already appeared frequently.","type":"number"},"logit_bias":{"description":"Provider-compatible token bias map for steering token selection.","type":"object","patternProperties":{"^(.*)$":{"type":"number"}}},"user":{"description":"End-user identifier forwarded to providers that support abuse monitoring or analytics.","examples":["user_123"],"type":"string"},"tools":{"description":"Function tools the selected model may call while producing a chat completion.","type":"array","items":{"type":"object","required":["type","function"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}}}}}}},"tool_choice":{"description":"Controls whether the model may call tools, must call tools, or must call a specific function.","anyOf":[{"const":"none","type":"string"},{"const":"auto","type":"string"},{"const":"required","type":"string"},{"type":"object","required":["type","function"],"properties":{"type":{"const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Specific function the model must call.","examples":["lookupOrder"],"type":"string"}}}}}]},"response_format":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object"]}}},"seed":{"description":"Best-effort deterministic seed forwarded to providers that support seeded generation.","examples":[12345],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","examples":[["text","image"]],"type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}},"fallback_models":{"description":"Ordered model fallback list used after the primary model is unavailable or rejected by routing policy.","type":"array","items":{"description":"Alternative AI Gateway model identifier to try if the primary model cannot serve the request.","examples":["anthropic/claude-3-5-sonnet"],"type":"string"}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"messages":{"description":"Conversation turns that define the context the selected model should answer.","type":"array","items":{"anyOf":[{"type":"object","required":["role","content"],"properties":{"role":{"description":"System message that sets behavior for the model.","const":"system","type":"string"},"content":{"description":"System instruction text, or null to preserve OpenAI-compatible shape.","anyOf":[{"description":"System instruction text sent to the model.","type":"string"},{"type":"null"}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"User message representing input from the end user or calling application.","const":"user","type":"string"},"content":{"description":"User input as text, multimodal content parts, or null for provider-compatible empty content.","anyOf":[{"description":"User text sent to the model.","type":"string"},{"type":"null"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"text","type":"string"},"text":{"description":"Text content sent to the selected chat model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as an image input for vision-capable models.","const":"image_url","type":"string"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Image URL or supported data URL passed to the model provider.","type":"string"},"detail":{"description":"Vision detail level requested from providers that support image detail controls.","anyOf":[{"const":"auto","type":"string"},{"const":"low","type":"string"},{"const":"high","type":"string"}]}}}}},{"type":"object","required":["type","file"],"properties":{"type":{"description":"Marks this content part as a file input for OpenRouter-compatible file models.","const":"file","type":"string"},"file":{"type":"object","properties":{"filename":{"description":"Optional filename supplied to the provider.","type":"string"},"file_data":{"description":"File URL or base64 data URL supplied to the provider.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as a video input for OpenRouter-compatible video models.","const":"video_url","type":"string"},"video_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}}}]}}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"Assistant message from prior model output, usually used to continue a conversation.","const":"assistant","type":"string"},"content":{"description":"Assistant text from previous turns, or null when the turn only contains tool calls.","anyOf":[{"description":"Assistant text produced by a previous model turn.","type":"string"},{"type":"null"}]},"name":{"description":"Optional assistant participant name.","type":"string"},"tool_calls":{"description":"Tool calls emitted by the assistant in a previous turn.","type":"array","items":{"type":"object","required":["id","type","function"],"properties":{"id":{"description":"Provider-generated tool call ID that must be referenced by the matching tool response.","type":"string"},"type":{"description":"Tool call type. AI Gateway currently supports function tool calls.","const":"function","type":"string"},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"description":"Function name selected by the model.","type":"string"},"arguments":{"description":"JSON string containing the function arguments generated by the model.","type":"string"}}}}}}}},{"type":"object","required":["role","content","tool_call_id"],"properties":{"role":{"description":"Tool result message supplied after executing a model-requested function.","const":"tool","type":"string"},"content":{"description":"Tool execution result content returned to the model.","anyOf":[{"description":"Serialized result returned by the executed tool.","type":"string"},{"type":"null"}]},"tool_call_id":{"description":"The ID of the tool call this message is responding to (required for tool messages)","type":"string"}}}]}},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"n":{"minimum":1,"maximum":1,"description":"Number of completion choices. AI Gateway always returns a single choice.","examples":[1],"type":"number"},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"stop":{"description":"Stop sequence or sequences where generation should end.","anyOf":[{"description":"Single stop sequence where generation should end.","type":"string"},{"type":"array","items":{"description":"Stop sequence where generation should end.","type":"string"}}]},"max_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"presence_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating topics already present in the conversation.","type":"number"},"frequency_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating tokens that already appeared frequently.","type":"number"},"logit_bias":{"description":"Provider-compatible token bias map for steering token selection.","type":"object","patternProperties":{"^(.*)$":{"type":"number"}}},"user":{"description":"End-user identifier forwarded to providers that support abuse monitoring or analytics.","examples":["user_123"],"type":"string"},"tools":{"description":"Function tools the selected model may call while producing a chat completion.","type":"array","items":{"type":"object","required":["type","function"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}}}}}}},"tool_choice":{"description":"Controls whether the model may call tools, must call tools, or must call a specific function.","anyOf":[{"const":"none","type":"string"},{"const":"auto","type":"string"},{"const":"required","type":"string"},{"type":"object","required":["type","function"],"properties":{"type":{"const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Specific function the model must call.","examples":["lookupOrder"],"type":"string"}}}}}]},"response_format":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object"]}}},"seed":{"description":"Best-effort deterministic seed forwarded to providers that support seeded generation.","examples":[12345],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","examples":[["text","image"]],"type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}},"fallback_models":{"description":"Ordered model fallback list used after the primary model is unavailable or rejected by routing policy.","type":"array","items":{"description":"Alternative AI Gateway model identifier to try if the primary model cannot serve the request.","examples":["anthropic/claude-3-5-sonnet"],"type":"string"}}}}},"multipart/form-data":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"messages":{"description":"Conversation turns that define the context the selected model should answer.","type":"array","items":{"anyOf":[{"type":"object","required":["role","content"],"properties":{"role":{"description":"System message that sets behavior for the model.","const":"system","type":"string"},"content":{"description":"System instruction text, or null to preserve OpenAI-compatible shape.","anyOf":[{"description":"System instruction text sent to the model.","type":"string"},{"type":"null"}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"User message representing input from the end user or calling application.","const":"user","type":"string"},"content":{"description":"User input as text, multimodal content parts, or null for provider-compatible empty content.","anyOf":[{"description":"User text sent to the model.","type":"string"},{"type":"null"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"text","type":"string"},"text":{"description":"Text content sent to the selected chat model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as an image input for vision-capable models.","const":"image_url","type":"string"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Image URL or supported data URL passed to the model provider.","type":"string"},"detail":{"description":"Vision detail level requested from providers that support image detail controls.","anyOf":[{"const":"auto","type":"string"},{"const":"low","type":"string"},{"const":"high","type":"string"}]}}}}},{"type":"object","required":["type","file"],"properties":{"type":{"description":"Marks this content part as a file input for OpenRouter-compatible file models.","const":"file","type":"string"},"file":{"type":"object","properties":{"filename":{"description":"Optional filename supplied to the provider.","type":"string"},"file_data":{"description":"File URL or base64 data URL supplied to the provider.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as a video input for OpenRouter-compatible video models.","const":"video_url","type":"string"},"video_url":{"type":"object","required":["url"],"properties":{"url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}}}]}}]},"name":{"description":"Optional participant name used by providers that support named messages.","type":"string"}}},{"type":"object","required":["role","content"],"properties":{"role":{"description":"Assistant message from prior model output, usually used to continue a conversation.","const":"assistant","type":"string"},"content":{"description":"Assistant text from previous turns, or null when the turn only contains tool calls.","anyOf":[{"description":"Assistant text produced by a previous model turn.","type":"string"},{"type":"null"}]},"name":{"description":"Optional assistant participant name.","type":"string"},"tool_calls":{"description":"Tool calls emitted by the assistant in a previous turn.","type":"array","items":{"type":"object","required":["id","type","function"],"properties":{"id":{"description":"Provider-generated tool call ID that must be referenced by the matching tool response.","type":"string"},"type":{"description":"Tool call type. AI Gateway currently supports function tool calls.","const":"function","type":"string"},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"description":"Function name selected by the model.","type":"string"},"arguments":{"description":"JSON string containing the function arguments generated by the model.","type":"string"}}}}}}}},{"type":"object","required":["role","content","tool_call_id"],"properties":{"role":{"description":"Tool result message supplied after executing a model-requested function.","const":"tool","type":"string"},"content":{"description":"Tool execution result content returned to the model.","anyOf":[{"description":"Serialized result returned by the executed tool.","type":"string"},{"type":"null"}]},"tool_call_id":{"description":"The ID of the tool call this message is responding to (required for tool messages)","type":"string"}}}]}},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"n":{"minimum":1,"maximum":1,"description":"Number of completion choices. AI Gateway always returns a single choice.","examples":[1],"type":"number"},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"stop":{"description":"Stop sequence or sequences where generation should end.","anyOf":[{"description":"Single stop sequence where generation should end.","type":"string"},{"type":"array","items":{"description":"Stop sequence where generation should end.","type":"string"}}]},"max_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"presence_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating topics already present in the conversation.","type":"number"},"frequency_penalty":{"minimum":-2,"maximum":2,"description":"Penalty that discourages repeating tokens that already appeared frequently.","type":"number"},"logit_bias":{"description":"Provider-compatible token bias map for steering token selection.","type":"object","patternProperties":{"^(.*)$":{"type":"number"}}},"user":{"description":"End-user identifier forwarded to providers that support abuse monitoring or analytics.","examples":["user_123"],"type":"string"},"tools":{"description":"Function tools the selected model may call while producing a chat completion.","type":"array","items":{"type":"object","required":["type","function"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}}}}}}},"tool_choice":{"description":"Controls whether the model may call tools, must call tools, or must call a specific function.","anyOf":[{"const":"none","type":"string"},{"const":"auto","type":"string"},{"const":"required","type":"string"},{"type":"object","required":["type","function"],"properties":{"type":{"const":"function","type":"string"},"function":{"type":"object","required":["name"],"properties":{"name":{"description":"Specific function the model must call.","examples":["lookupOrder"],"type":"string"}}}}}]},"response_format":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object"]}}},"seed":{"description":"Best-effort deterministic seed forwarded to providers that support seeded generation.","examples":[12345],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","examples":[["text","image"]],"type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}},"fallback_models":{"description":"Ordered model fallback list used after the primary model is unavailable or rejected by routing policy.","type":"array","items":{"description":"Alternative AI Gateway model identifier to try if the primary model cannot serve the request.","examples":["anthropic/claude-3-5-sonnet"],"type":"string"}}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}}}},"/ai/v1/responses":{"post":{"tags":["AI Gateway"],"operationId":"createAiResponse","summary":"Create response","description":"Creates a model response through Gigadrive AI Gateway using the OpenAI Responses API shape. Use this endpoint for newer multimodal or tool-capable response workflows while letting Gigadrive handle model routing, provider selection, access control, and provider fallback behind a single Network API credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"input":{"description":"User prompt or structured Responses API conversation input to send through AI Gateway.","anyOf":[{"description":"Prompt text sent to the model.","type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"description":"Input item type used by the Responses API conversation format.","anyOf":[{"const":"message","type":"string"},{"const":"function_call_output","type":"string"}]},"role":{"description":"Conversation role for message input items.","anyOf":[{"const":"user","type":"string"},{"const":"assistant","type":"string"},{"const":"system","type":"string"},{"const":"developer","type":"string"}]},"content":{"description":"Text or multimodal content for this Responses API input item.","anyOf":[{"description":"Plain text content for this input item.","type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"input_text","type":"string"},"text":{"description":"Text content supplied to the model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as image input for vision-capable models.","const":"input_image","type":"string"},"image_url":{"description":"Image URL or supported data URL supplied to the model.","type":"string"}}},{"type":"object","required":["type"],"properties":{"type":{"description":"Marks this content part as file input for OpenRouter-compatible file models.","const":"input_file","type":"string"},"filename":{"description":"Optional file name.","type":"string"},"file_data":{"description":"File URL or base64 data URL.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as video input for OpenRouter-compatible video models.","const":"input_video","type":"string"},"video_url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}]}}]},"call_id":{"description":"Function call ID this output item answers.","type":"string"},"output":{"description":"Function output text returned to the model.","type":"string"}}}}]},"previous_response_id":{"description":"Provider response ID used to continue context from a prior response when supported.","examples":["resp_01JZ0J3Q9Z7Z3N4N2Y0N1X8M0Q"],"type":"string"},"instructions":{"description":"System or developer instructions that guide model behavior for this response.","type":"string"},"tools":{"description":"NOT YET SUPPORTED: the Responses endpoint rejects non-empty tool lists with 400 until tool continuation is implemented. Use /v1/chat/completions for tool calling.","type":"array","items":{"type":"object","required":["type","name"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}},"strict":{"description":"Whether compatible providers should strictly enforce the supplied function schema.","type":"boolean"}}}},"tool_choice":{"type":"string","enum":["none","auto","required"]},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"max_output_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"parallel_tool_calls":{"description":"Whether compatible providers may emit multiple tool calls in parallel.","type":"boolean"},"metadata":{"description":"String metadata forwarded for provider-side tracing or application correlation.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}}}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"input":{"description":"User prompt or structured Responses API conversation input to send through AI Gateway.","anyOf":[{"description":"Prompt text sent to the model.","type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"description":"Input item type used by the Responses API conversation format.","anyOf":[{"const":"message","type":"string"},{"const":"function_call_output","type":"string"}]},"role":{"description":"Conversation role for message input items.","anyOf":[{"const":"user","type":"string"},{"const":"assistant","type":"string"},{"const":"system","type":"string"},{"const":"developer","type":"string"}]},"content":{"description":"Text or multimodal content for this Responses API input item.","anyOf":[{"description":"Plain text content for this input item.","type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"input_text","type":"string"},"text":{"description":"Text content supplied to the model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as image input for vision-capable models.","const":"input_image","type":"string"},"image_url":{"description":"Image URL or supported data URL supplied to the model.","type":"string"}}},{"type":"object","required":["type"],"properties":{"type":{"description":"Marks this content part as file input for OpenRouter-compatible file models.","const":"input_file","type":"string"},"filename":{"description":"Optional file name.","type":"string"},"file_data":{"description":"File URL or base64 data URL.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as video input for OpenRouter-compatible video models.","const":"input_video","type":"string"},"video_url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}]}}]},"call_id":{"description":"Function call ID this output item answers.","type":"string"},"output":{"description":"Function output text returned to the model.","type":"string"}}}}]},"previous_response_id":{"description":"Provider response ID used to continue context from a prior response when supported.","examples":["resp_01JZ0J3Q9Z7Z3N4N2Y0N1X8M0Q"],"type":"string"},"instructions":{"description":"System or developer instructions that guide model behavior for this response.","type":"string"},"tools":{"description":"NOT YET SUPPORTED: the Responses endpoint rejects non-empty tool lists with 400 until tool continuation is implemented. Use /v1/chat/completions for tool calling.","type":"array","items":{"type":"object","required":["type","name"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}},"strict":{"description":"Whether compatible providers should strictly enforce the supplied function schema.","type":"boolean"}}}},"tool_choice":{"type":"string","enum":["none","auto","required"]},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"max_output_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"parallel_tool_calls":{"description":"Whether compatible providers may emit multiple tool calls in parallel.","type":"boolean"},"metadata":{"description":"String metadata forwarded for provider-side tracing or application correlation.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}}}}},"multipart/form-data":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"description":"AI Gateway model identifier to route the request to, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"input":{"description":"User prompt or structured Responses API conversation input to send through AI Gateway.","anyOf":[{"description":"Prompt text sent to the model.","type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"description":"Input item type used by the Responses API conversation format.","anyOf":[{"const":"message","type":"string"},{"const":"function_call_output","type":"string"}]},"role":{"description":"Conversation role for message input items.","anyOf":[{"const":"user","type":"string"},{"const":"assistant","type":"string"},{"const":"system","type":"string"},{"const":"developer","type":"string"}]},"content":{"description":"Text or multimodal content for this Responses API input item.","anyOf":[{"description":"Plain text content for this input item.","type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","required":["type","text"],"properties":{"type":{"description":"Marks this content part as text input.","const":"input_text","type":"string"},"text":{"description":"Text content supplied to the model.","type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"description":"Marks this content part as image input for vision-capable models.","const":"input_image","type":"string"},"image_url":{"description":"Image URL or supported data URL supplied to the model.","type":"string"}}},{"type":"object","required":["type"],"properties":{"type":{"description":"Marks this content part as file input for OpenRouter-compatible file models.","const":"input_file","type":"string"},"filename":{"description":"Optional file name.","type":"string"},"file_data":{"description":"File URL or base64 data URL.","type":"string"},"file_id":{"description":"Provider file identifier when supported.","type":"string"}}},{"type":"object","required":["type","input_audio"],"properties":{"type":{"description":"Marks this content part as base64 audio input for OpenRouter-compatible audio models.","const":"input_audio","type":"string"},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"description":"Base64-encoded audio data.","type":"string"},"format":{"description":"Audio container or PCM format.","anyOf":[{"const":"wav","type":"string"},{"const":"mp3","type":"string"},{"const":"aiff","type":"string"},{"const":"aac","type":"string"},{"const":"ogg","type":"string"},{"const":"flac","type":"string"},{"const":"m4a","type":"string"},{"const":"pcm16","type":"string"},{"const":"pcm24","type":"string"}]}}}}},{"type":"object","required":["type","video_url"],"properties":{"type":{"description":"Marks this content part as video input for OpenRouter-compatible video models.","const":"input_video","type":"string"},"video_url":{"description":"Video URL or supported data URL supplied to the provider.","type":"string"}}}]}}]},"call_id":{"description":"Function call ID this output item answers.","type":"string"},"output":{"description":"Function output text returned to the model.","type":"string"}}}}]},"previous_response_id":{"description":"Provider response ID used to continue context from a prior response when supported.","examples":["resp_01JZ0J3Q9Z7Z3N4N2Y0N1X8M0Q"],"type":"string"},"instructions":{"description":"System or developer instructions that guide model behavior for this response.","type":"string"},"tools":{"description":"NOT YET SUPPORTED: the Responses endpoint rejects non-empty tool lists with 400 until tool continuation is implemented. Use /v1/chat/completions for tool calling.","type":"array","items":{"type":"object","required":["type","name"],"properties":{"type":{"description":"Tool type. AI Gateway currently supports function tools.","const":"function","type":"string"},"name":{"description":"Function name the model can call.","examples":["lookupOrder"],"type":"string"},"description":{"description":"Natural-language explanation of what the function does.","type":"string"},"parameters":{"description":"JSON Schema object describing valid function arguments.","type":"object","patternProperties":{"^(.*)$":{}}},"strict":{"description":"Whether compatible providers should strictly enforce the supplied function schema.","type":"boolean"}}}},"tool_choice":{"type":"string","enum":["none","auto","required"]},"temperature":{"minimum":0,"maximum":2,"description":"Sampling temperature. Lower values are more deterministic; higher values are more varied.","examples":[0.7],"type":"number"},"top_p":{"minimum":0,"maximum":1,"description":"Nucleus sampling cutoff used by compatible providers.","examples":[0.9],"type":"number"},"max_output_tokens":{"minimum":1,"description":"Maximum number of output tokens to generate.","examples":[1024],"type":"number"},"modalities":{"description":"Requested output modalities for providers that support multimodal generation.","type":"array","items":{"type":"string","enum":["text","image","audio"]}},"audio":{"type":"object","properties":{"voice":{"description":"Provider voice identifier for audio output.","type":"string"},"format":{"type":"string","enum":["wav","mp3","flac","opus","pcm16"]}}},"plugins":{"description":"OpenRouter provider plugins such as PDF parsing.","type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"description":"OpenRouter plugin identifier, for example `file-parser`.","type":"string"},"pdf":{"type":"object","properties":{"engine":{"description":"OpenRouter PDF parser engine.","type":"string"}}}}}},"stream":{"description":"When true, requests a streaming response from providers and models that support streaming.","type":"boolean"},"parallel_tool_calls":{"description":"Whether compatible providers may emit multiple tool calls in parallel.","type":"boolean"},"metadata":{"description":"String metadata forwarded for provider-side tracing or application correlation.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"provider":{"type":"object","properties":{"order":{"description":"Preferred provider route order for AI Gateway to try before default routing.","type":"array","items":{"description":"Provider route ID to try for this request.","examples":["openai"],"type":"string"}},"allow_fallbacks":{"description":"Whether AI Gateway may fall back to another configured provider if the preferred route fails.","type":"boolean"},"require_zdr":{"description":"Require Zero Data Retention providers only","examples":[true],"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{}}}},"400":{"description":"Response for status 400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type"],"properties":{"message":{"description":"Human-readable AI Gateway or provider error message.","type":"string"},"type":{"description":"OpenAI-compatible error category.","type":"string"},"param":{"description":"Request parameter associated with the error, when known.","type":"string"},"code":{"description":"Machine-readable error code for client handling.","type":"string"}}}}}}}}}}},"/ai/v1/models":{"get":{"tags":["AI Gateway"],"operationId":"listAiModels","summary":"List models","description":"Lists all AI models available to the authenticated actor through Gigadrive AI Gateway. The response includes product metadata such as capabilities, context limits, provider routing options, and zero-data-retention provider support so clients can choose the right model before sending inference requests.","responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"description":"Resources returned for the current authenticated actor, filters, and page.","type":"array","items":{"type":"object","required":["id","name","provider","capabilities","contextWindow","maxOutputTokens","routingProviders","routingProviderDetails","zdrProviders"],"properties":{"id":{"description":"Model identifier to pass to AI Gateway inference endpoints, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"name":{"description":"Human-readable model name shown in model pickers and dashboards.","examples":["GPT-4o"],"type":"string"},"provider":{"description":"Primary provider family or owner for this model as exposed through AI Gateway routing.","examples":["openai"],"type":"string"},"providerLogoUrl":{"description":"PNG logo URL for the primary model owner; omitted when no logo asset exists for the provider.","examples":["https://console.gigadrive.de/ai-gateway/logos/openai.png"],"type":"string"},"capabilities":{"type":"object","required":["chat","streaming","tools","vision","json_mode"],"properties":{"chat":{"description":"Whether the model can be used with chat-style conversational requests.","type":"boolean"},"streaming":{"description":"Whether the model can stream partial output tokens through supported endpoints.","type":"boolean"},"tools":{"description":"Whether the model supports function/tool calling through AI Gateway.","type":"boolean"},"vision":{"description":"Whether the model accepts image inputs in addition to text.","type":"boolean"},"json_mode":{"description":"Whether the model supports JSON-constrained responses.","type":"boolean"}}},"modalities":{"type":"object","required":["input","output"],"properties":{"input":{"type":"array","items":{"description":"Input modality accepted by the model.","type":"string"}},"output":{"type":"array","items":{"description":"Output modality the model can generate.","type":"string"}}}},"contextWindow":{"description":"Maximum combined input and output context window, measured in model tokens.","examples":[128000],"type":"number"},"maxOutputTokens":{"description":"Maximum output tokens AI Gateway will request from providers for this model.","examples":[16384],"type":"number"},"description":{"description":"Product-facing model summary, including recommended use cases when configured.","type":"string"},"routingProviders":{"description":"Provider routes that can serve this model. AI Gateway uses these values when selecting providers or honoring provider order preferences.","type":"array","items":{"description":"Provider route ID that can serve this model.","type":"string"}},"routingProviderDetails":{"description":"Display metadata for each routing provider that can serve this model.","type":"array","items":{"type":"object","required":["id","name","supportsZdr"],"properties":{"id":{"description":"Provider route ID that can serve this model.","type":"string"},"name":{"description":"Human-readable routing provider name.","type":"string"},"logoUrl":{"description":"PNG logo URL for the routing provider; omitted when no logo asset exists.","type":"string"},"supportsZdr":{"description":"Whether this provider route supports zero-data-retention handling.","type":"boolean"}}}},"zdrProviders":{"description":"Provider routes for this model that support zero-data-retention handling.","type":"array","items":{"description":"Provider route ID that can serve this model with zero-data-retention handling.","type":"string"}}}}},"total":{"description":"Total number of resources matching the same actor scope and filters. Cursor pagination limits which resources appear in `items`, but does not change this count.","examples":[42],"type":"number"}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/ai/v1/models/{modelId}":{"get":{"tags":["AI Gateway"],"operationId":"getAiModel","summary":"Get model","description":"Retrieves metadata for one AI Gateway model. Use this before sending inference requests when a client needs to verify the model identifier, supported capabilities, context window, provider routing options, or zero-data-retention availability.","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"description":"The model identifier (URL encoded, e.g., \"openai%2Fgpt-4o\")","examples":["openai/gpt-4o"],"type":"string"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"type":"object","required":["id","name","provider","capabilities","contextWindow","maxOutputTokens","routingProviders","routingProviderDetails","zdrProviders"],"properties":{"id":{"description":"Model identifier to pass to AI Gateway inference endpoints, for example `openai/gpt-4o`.","examples":["openai/gpt-4o"],"type":"string"},"name":{"description":"Human-readable model name shown in model pickers and dashboards.","examples":["GPT-4o"],"type":"string"},"provider":{"description":"Primary provider family or owner for this model as exposed through AI Gateway routing.","examples":["openai"],"type":"string"},"providerLogoUrl":{"description":"PNG logo URL for the primary model owner; omitted when no logo asset exists for the provider.","examples":["https://console.gigadrive.de/ai-gateway/logos/openai.png"],"type":"string"},"capabilities":{"type":"object","required":["chat","streaming","tools","vision","json_mode"],"properties":{"chat":{"description":"Whether the model can be used with chat-style conversational requests.","type":"boolean"},"streaming":{"description":"Whether the model can stream partial output tokens through supported endpoints.","type":"boolean"},"tools":{"description":"Whether the model supports function/tool calling through AI Gateway.","type":"boolean"},"vision":{"description":"Whether the model accepts image inputs in addition to text.","type":"boolean"},"json_mode":{"description":"Whether the model supports JSON-constrained responses.","type":"boolean"}}},"modalities":{"type":"object","required":["input","output"],"properties":{"input":{"type":"array","items":{"description":"Input modality accepted by the model.","type":"string"}},"output":{"type":"array","items":{"description":"Output modality the model can generate.","type":"string"}}}},"contextWindow":{"description":"Maximum combined input and output context window, measured in model tokens.","examples":[128000],"type":"number"},"maxOutputTokens":{"description":"Maximum output tokens AI Gateway will request from providers for this model.","examples":[16384],"type":"number"},"description":{"description":"Product-facing model summary, including recommended use cases when configured.","type":"string"},"routingProviders":{"description":"Provider routes that can serve this model. AI Gateway uses these values when selecting providers or honoring provider order preferences.","type":"array","items":{"description":"Provider route ID that can serve this model.","type":"string"}},"routingProviderDetails":{"description":"Display metadata for each routing provider that can serve this model.","type":"array","items":{"type":"object","required":["id","name","supportsZdr"],"properties":{"id":{"description":"Provider route ID that can serve this model.","type":"string"},"name":{"description":"Human-readable routing provider name.","type":"string"},"logoUrl":{"description":"PNG logo URL for the routing provider; omitted when no logo asset exists.","type":"string"},"supportsZdr":{"description":"Whether this provider route supports zero-data-retention handling.","type":"boolean"}}}},"zdrProviders":{"description":"Provider routes for this model that support zero-data-retention handling.","type":"array","items":{"description":"Provider route ID that can serve this model with zero-data-retention handling.","type":"string"}}}}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"404":{"description":"Response for status 404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false}}}}}}},"/.well-known/openid-configuration":{"get":{"operationId":"getOidcDiscoveryDocument","summary":"Get OIDC discovery document","description":"Returns the OpenID Connect discovery document for the Gigadrive Network API issuer. API clients use this metadata to discover the OAuth token endpoint, public JWKS URI, supported scopes, token claims, and the fact that this issuer is designed for machine-to-machine `client_credentials` authentication with API keys.","tags":["Authentication"],"security":[],"responses":{"200":{"description":"OIDC discovery metadata for the Network API issuer."}}}},"/.well-known/jwks.json":{"get":{"operationId":"getOidcJwks","summary":"Get OIDC signing keys","description":"Returns the JSON Web Key Set for the Gigadrive Network API issuer. Resource servers and clients use these public keys to verify bearer tokens issued by `/oauth2/token`. Keys are cacheable and may rotate; select the verification key by the JWT `kid` header.","tags":["Authentication"],"security":[],"responses":{"200":{"description":"Public JSON Web Keys for verifying Network API bearer tokens."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Raw bearer credential. Use this when pasting an existing Gigadrive JWT or a short-lived OAuth access token issued by `/oauth2/token`."},"networkOAuth2":{"type":"oauth2","description":"OAuth 2.0 client credentials flow for machine-to-machine Network API calls. Use a Gigadrive API key as the OAuth client credentials; issued access tokens are sent as bearer tokens and inherit the API key actor binding and scopes.","flows":{"clientCredentials":{"tokenUrl":"/oauth2/token","scopes":{"network:storage_buckets:read":"List and read storage bucket metadata.","network:storage_buckets:write":"Create storage buckets.","network:storage_buckets:delete":"Delete empty storage buckets.","network:storage_objects:read":"List and read objects, upload sessions, trash, and access URLs.","network:storage_objects:write":"Create upload sessions and restore trashed objects.","network:storage_objects:delete":"Trash, purge, and permanently delete storage objects.","network:queues:read":"List queues, read their depth, and browse messages and schedules.","network:queues:write":"Create and configure queues and schedules, pause, purge, and retry dead letters.","network:queues:delete":"Delete queues together with their messages.","network:queues:send":"Send, schedule, and cancel messages.","network:queues:consume":"Receive, acknowledge, retry, and extend leased messages.","network:microvms:read":"List and read microVMs.","network:microvms:write":"Create microVMs, stop them, and extend their timeout.","network:microvms:exec":"Run commands in microVMs and read and write their files.","network:microvms:delete":"Delete microVMs.","network:microvm_images:read":"List and read microVM images.","network:microvm_images:write":"Create custom microVM images.","network:microvm_images:delete":"Delete custom microVM images.","network:domains:read":"List and read custom domains and verified organization domains.","network:domains:write":"Add, update, check, claim and verify custom domains and organization domains.","network:domains:delete":"Remove custom domains and verified organization domains.","network:ai_gateway:chat":"Send AI Gateway inference requests for chat, audio, and video endpoints.","network:ai_gateway:models":"List AI Gateway models available through configured providers.","network:ai_gateway:usage:read":"Read organization AI Gateway usage summaries and request logs.","network:ai_gateway:budgets:read":"Read organization AI Gateway budgets.","network:ai_gateway:budgets:write":"Replace organization AI Gateway budgets.","network:ai_gateway:policies:read":"Read organization AI Gateway model/provider policies.","network:ai_gateway:policies:write":"Create or update organization AI Gateway model/provider policies.","network:sticky_sessions:write":"Mint routing-only sticky URLs from a deployed function."}}}},"gigadriveUserOAuth2":{"type":"oauth2","description":"User-facing Gigadrive IDP authorization-code flow. This redirects to the shared Gigadrive account app for sign-in and consent, then returns a user JWT that can call Network API endpoints when the OAuth client and user are allowed to request the required product scopes.","flows":{"authorizationCode":{"authorizationUrl":"https://idp.gigadrive.de/oauth2/authorize","tokenUrl":"https://idp.gigadrive.de/oauth2/token","scopes":{"openid":"Verify the signed-in Gigadrive user.","profile":"Read basic profile claims for the signed-in user.","email":"Read email claims for the signed-in user.","network:storage_buckets:read":"List and read storage bucket metadata.","network:storage_buckets:write":"Create storage buckets.","network:storage_buckets:delete":"Delete empty storage buckets.","network:storage_objects:read":"List and read objects, upload sessions, trash, and access URLs.","network:storage_objects:write":"Create upload sessions and restore trashed objects.","network:storage_objects:delete":"Trash, purge, and permanently delete storage objects.","network:queues:read":"List queues, read their depth, and browse messages and schedules.","network:queues:write":"Create and configure queues and schedules, pause, purge, and retry dead letters.","network:queues:delete":"Delete queues together with their messages.","network:queues:send":"Send, schedule, and cancel messages.","network:queues:consume":"Receive, acknowledge, retry, and extend leased messages.","network:microvms:read":"List and read microVMs.","network:microvms:write":"Create microVMs, stop them, and extend their timeout.","network:microvms:exec":"Run commands in microVMs and read and write their files.","network:microvms:delete":"Delete microVMs.","network:microvm_images:read":"List and read microVM images.","network:microvm_images:write":"Create custom microVM images.","network:microvm_images:delete":"Delete custom microVM images.","network:domains:read":"List and read custom domains and verified organization domains.","network:domains:write":"Add, update, check, claim and verify custom domains and organization domains.","network:domains:delete":"Remove custom domains and verified organization domains.","network:ai_gateway:chat":"Send AI Gateway inference requests for chat, audio, and video endpoints.","network:ai_gateway:models":"List AI Gateway models available through configured providers.","network:ai_gateway:usage:read":"Read organization AI Gateway usage summaries and request logs.","network:ai_gateway:budgets:read":"Read organization AI Gateway budgets.","network:ai_gateway:budgets:write":"Replace organization AI Gateway budgets.","network:ai_gateway:policies:read":"Read organization AI Gateway model/provider policies.","network:ai_gateway:policies:write":"Create or update organization AI Gateway model/provider policies."}}}}},"schemas":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"error":{"type":"object","required":["error"],"properties":{"error":{"description":"Human-readable explanation of why the API request failed.","examples":["Authentication required"],"type":"string"}},"$id":"#/components/schemas/error","additionalProperties":false},"organization":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"},"organizationMember":{"type":"object","required":["membershipId","organizationId","userId","email","givenName","familyName","imageUrl","role","joinedAt"],"properties":{"membershipId":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","description":"Organization that owns this membership.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"userId":{"format":"uuid","description":"User who belongs to the organization.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},"email":{"format":"email","description":"Email address of the organization member.","examples":["owner@example.com"],"type":"string"},"givenName":{"nullable":true,"anyOf":[{"description":"Given name of the organization member, or null when unset.","examples":["Ada"],"type":"string"},{"type":"null"}]},"familyName":{"nullable":true,"anyOf":[{"description":"Family name of the organization member, or null when unset.","examples":["Lovelace"],"type":"string"},{"type":"null"}]},"imageUrl":{"nullable":true,"anyOf":[{"format":"uri","description":"Avatar URL for the organization member, or null when unset.","examples":["https://cdn.gigadrive.de/users/ada.png"],"type":"string"},{"type":"null"}]},"role":{"default":"OWNER","description":"Organization membership role used for administration privileges.","type":"string","enum":["OWNER","ADMIN","MEMBER"]},"joinedAt":{"format":"date-time","description":"ISO 8601 timestamp when the user joined the organization.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organizationMember"},"organizationProductAccess":{"type":"object","required":["product","hasAccess","resolutionSource","explicitEntitlement","subscription"],"properties":{"product":{"type":"object","required":["slug","displayName","accessMode","defaultAccessPolicy","plans"],"properties":{"slug":{"description":"Stable product slug from the code-defined product registry.","examples":["network","office"],"type":"string"},"displayName":{"description":"Human-readable product name.","examples":["Gigadrive Network","Gigadrive Office"],"type":"string"},"accessMode":{"default":"organization","description":"Whether the product is granted to organizations or directly to users.","type":"string","enum":["organization","user"]},"defaultAccessPolicy":{"default":"granted","description":"Fallback access policy when no explicit entitlement override exists for the organization or user.","type":"string","enum":["granted","explicit_entitlement_required"]},"plans":{"description":"Locally activatable plans defined for the product. Empty when the product has no plan catalog.","type":"array","items":{"type":"object","required":["slug","displayName","description"],"properties":{"slug":{"description":"Stable plan slug from the code-defined product registry.","examples":["free","team"],"type":"string"},"displayName":{"description":"Human-readable plan name shown in product surfaces.","examples":["Free","Team"],"type":"string"},"description":{"description":"Short description of what the plan includes.","examples":["Get started with Office for a small team at no cost."],"type":"string"}}}}}},"hasAccess":{"description":"Whether the organization currently has effective access to the product.","examples":[true],"type":"boolean"},"resolutionSource":{"default":"explicit","description":"Whether effective access was resolved from an explicit entitlement override or the product registry default policy.","type":"string","enum":["explicit","default"]},"explicitEntitlement":{"description":"Explicit entitlement override when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","status","grantedByUserId","revokedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this entitlement override applies to.","examples":["office"],"type":"string"},"status":{"default":"ACTIVE","description":"Lifecycle status of the explicit entitlement override.","type":"string","enum":["ACTIVE","SUSPENDED","REVOKED"]},"grantedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who last granted or updated the entitlement override, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"revokedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the entitlement was revoked, or null when not revoked.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]},"subscription":{"description":"Local product subscription when one exists, otherwise null.","nullable":true,"anyOf":[{"type":"object","required":["id","product","plan","status","activatedByUserId","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"product":{"description":"Product slug this subscription applies to.","examples":["office"],"type":"string"},"plan":{"description":"Currently selected plan slug for the product.","examples":["free","team"],"type":"string"},"status":{"default":"ACTIVE","description":"Local subscription lifecycle status.","type":"string","enum":["ACTIVE","CANCELED"]},"activatedByUserId":{"nullable":true,"anyOf":[{"format":"uuid","description":"User who activated the current plan, or null when unknown.","examples":["0197b2f0-aaaa-7c2a-9f4e-222222222222"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}}},{"type":"null"}]}},"$id":"#/components/schemas/organizationProductAccess"},"organizationProductEntitlementCheck":{"type":"object","required":["organizationId","product","hasAccess"],"properties":{"organizationId":{"format":"uuid","description":"Organization that was checked.","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"product":{"description":"Product slug that was checked.","examples":["network","office"],"type":"string"},"hasAccess":{"description":"Whether the organization currently has effective access to the product.","examples":[true],"type":"boolean"}},"$id":"#/components/schemas/organizationProductEntitlementCheck"},"application":{"type":"object","required":["id","organization","name","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organization":{"type":"object","required":["id","name","slug","imageUrl","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Display name shown for the organization in Gigadrive products.","examples":["Gigadrive"],"type":"string"},"slug":{"description":"URL-safe organization slug used in product UI and human-facing references.","examples":["gigadrive"],"type":"string"},"imageUrl":{"description":"Organization avatar or logo URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/organizations/gigadrive.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/organization"},"name":{"description":"Application display name shown in the Network console and API clients.","examples":["Website"],"type":"string"},"imageUrl":{"description":"Application icon URL shown in Gigadrive product surfaces.","format":"uri","examples":["https://cdn.gigadrive.de/applications/website.png"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/application"},"deployment":{"type":"object","required":["id","applicationId","status","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application that owns this deployment and receives the resulting code, assets, and runtime configuration.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deployment"},"deploymentLog":{"type":"object","required":["id","message","type","createdAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"message":{"description":"Build or provisioning log message emitted for this deployment.","type":"string"},"type":{"default":"INFO","description":"Severity level assigned by the deployment pipeline.","type":"string","enum":["INFO","ERROR","WARN","DEBUG"]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"}},"$id":"#/components/schemas/deploymentLog"},"deploymentStatus":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"},"envVar":{"type":"object","required":["id","key","value","sensitive","scope","environmentId","environmentName","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Environment variable name injected into your functions, for example `DATABASE_URL` or `API_KEY`.","examples":["DATABASE_URL","API_KEY"],"type":"string"},"value":{"nullable":true,"anyOf":[{"description":"Stored variable value when the variable is not sensitive. Sensitive variables return `null` so clients can confirm the key exists without exposing the secret.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},{"type":"null"}]},"sensitive":{"description":"Whether Network redacts this variable value from API responses after it has been stored.","examples":[true],"type":"boolean"},"scope":{"default":"organization","description":"Configuration scope that controls where the variable applies: across an organization, across one application, or only for one environment override.","type":"string","enum":["organization","application","environment"]},"environmentId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Environment that owns this override. Null means the variable is not limited to one environment.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},{"type":"null"}]},"environmentName":{"nullable":true,"anyOf":[{"description":"Human-readable environment name for an environment-scoped variable, or null otherwise.","examples":["Production"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/envVar"},"resolvedEnvVar":{"type":"object","required":["key","value","source"],"properties":{"key":{"description":"Environment variable name.","examples":["DATABASE_URL","NEXT_PUBLIC_API_URL"],"type":"string"},"value":{"description":"Resolved variable value. Only non-sensitive variables are returned by the pull endpoint, so this is always the real value.","examples":["postgres://user:password@db.example.com:5432/app"],"type":"string"},"source":{"default":"organization","description":"Where the resolved value came from after applying inheritance: an organization-wide variable, an application-wide variable, or an environment-specific override.","type":"string","enum":["organization","application","environment"]}},"$id":"#/components/schemas/resolvedEnvVar"},"apiKey":{"type":"object","required":["id","name","applicationId","scopes","expiresAt","lastUsedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Human-readable label for the API key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application this key is scoped to. The key can only act on this application.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"scopes":{"description":"API capability scopes granted to this key.","type":"array","items":{"description":"API capability scope granted to this key.","examples":["network:env_vars:read"],"type":"string"}},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key expires, or null if it never expires.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"lastUsedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key last exchanged a token or authenticated a request, or null if it has never been used. Recorded at most once every few minutes, so it can trail the most recent use.","examples":["2026-10-01T12:00:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/apiKey"},"apiKeyWithSecret":{"type":"object","required":["id","name","applicationId","scopes","expiresAt","secret","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Human-readable label for the API key.","examples":["cli-dev:my-laptop"],"type":"string"},"applicationId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Application this key is scoped to.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},{"type":"null"}]},"scopes":{"description":"API capability scopes granted to this key.","type":"array","items":{"description":"API capability scope granted to this key.","type":"string"}},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"When the key expires, or null if it never expires.","type":"string"},{"type":"null"}]},"secret":{"description":"The plaintext client secret. Returned only once at creation time and never retrievable again — store it now. Use it together with the key `id` as OAuth client credentials.","examples":["gdnet_secret_QWxhZGRpbjpvcGVuc2VzYW1l"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/apiKeyWithSecret"},"storageBucket":{"type":"object","required":["id","applicationId","name","slug","visibility","cdnHostname","environmentId","createdAt","updatedAt"],"properties":{"id":{"format":"uuid","deprecated":true,"description":"Internal bucket UUID. Accepted by bucket-scoped API routes only as a deprecated compatibility fallback.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Network application that owns this bucket.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"name":{"minLength":3,"maxLength":63,"pattern":"^(?![0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical immutable API and IaC identifier. The lowercase URL-safe, non-UUID name is unique within the bucket environment.","examples":["user-uploads"],"type":"string"},"slug":{"description":"Globally unique delivery and S3 identifier used in CDN hostnames and S3-compatible bucket addressing. It is generated by the API for canonical clients.","examples":["website-user-uploads"],"type":"string"},"visibility":{"default":"public","description":"Bucket access policy. Public buckets can serve objects through the CDN hostname; private buckets require signed access URLs.","type":"string","enum":["public","private"]},"cdnHostname":{"description":"Hostname clients use to read public objects or signed private object URLs.","examples":["website-user-uploads.public.gigadriveuserstorage.com"],"type":"string"},"environmentId":{"format":"uuid","description":"Application environment this bucket belongs to.","examples":["0197b2f8-92a4-734f-9b90-999999999999"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageBucket"},"storageObject":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageObject"},"trashedStorageObject":{"type":"object","required":["id","bucketId","applicationId","uploadSessionId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","uploadedAt","createdAt","updatedAt","deletedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string"},"bucketId":{"format":"uuid","description":"Bucket that contains this stored object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and object.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"uploadSessionId":{"nullable":true,"anyOf":[{"format":"uuid","description":"Upload session that created this object, or null for provider-imported objects.","examples":["0197b2f6-7082-712d-9f7e-777777777777"],"type":"string"},{"type":"null"}]},"key":{"description":"Object key/path clients use when addressing this file inside the bucket.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Detected or client-declared MIME type for the stored object.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"description":"Stored object size in bytes after upload finalization.","examples":[5242880],"type":"number"},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum recorded for integrity verification, or null if unavailable.","type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum recorded for integrity verification.","type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum recorded for compatibility with storage providers, or null if unavailable.","type":"string"},{"type":"null"}]},"uploadedAt":{"format":"date-time","description":"ISO 8601 timestamp when the storage provider finalized the object upload.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"},"deletedAt":{"format":"date-time","description":"ISO 8601 timestamp when the object was moved to the trash.","examples":["2026-07-01T09:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/trashedStorageObject"},"storageObjectAccess":{"type":"object","required":["accessType","url","expiresAt"],"properties":{"accessType":{"default":"public","description":"`public` means the URL is a stable CDN URL. `signed` means the URL grants temporary access to a private object.","type":"string","enum":["public","signed"]},"url":{"format":"uri","description":"URL clients can use to download the object according to the bucket visibility policy.","examples":["https://website-user-uploads.public.gigadriveuserstorage.com/avatars/user-123.png"],"type":"string"},"expiresAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"Expiration timestamp for signed private-object URLs. Public URLs return null because they do not expire.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/storageObjectAccess"},"storageUploadSession":{"type":"object","required":["id","bucketId","applicationId","key","contentType","contentLength","checksumSha1","checksumSha256","checksumMd5","state","expiresAt","uploadedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"bucketId":{"format":"uuid","description":"Bucket that will receive the uploaded object.","examples":["0197b2f4-5e70-7f3b-9d5c-555555555555"],"type":"string"},"applicationId":{"format":"uuid","description":"Application that owns the bucket and upload session.","examples":["0197b2f1-2f4a-7a0b-8a2d-222222222222"],"type":"string"},"key":{"description":"Final object key/path inside the bucket once the upload completes.","examples":["avatars/user-123.png"],"type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"MIME type declared by the client for the object, or null if none was supplied.","examples":["image/png"],"type":"string"},{"type":"null"}]},"contentLength":{"nullable":true,"anyOf":[{"description":"Exact upload size in bytes declared when the session was created.","examples":[5242880],"type":"number"},{"type":"null"}]},"checksumSha1":{"nullable":true,"anyOf":[{"description":"SHA-1 checksum declared for upload validation, or null when not supplied.","examples":["2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"],"type":"string"},{"type":"null"}]},"checksumSha256":{"nullable":true,"anyOf":[{"description":"SHA-256 checksum used to validate the uploaded object content.","examples":["d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2"],"type":"string"},{"type":"null"}]},"checksumMd5":{"nullable":true,"anyOf":[{"description":"MD5 checksum declared for compatibility checks, or null when not supplied.","examples":["5d41402abc4b2a76b9719d911017c592"],"type":"string"},{"type":"null"}]},"state":{"default":"pending","description":"Upload lifecycle state. Pending sessions are still accepting bytes, completed sessions produced an object, and expired or failed sessions should not be reused.","type":"string","enum":["pending","ready","completed","failed","expired"]},"expiresAt":{"format":"date-time","description":"ISO 8601 timestamp after which the generated upload URL can no longer be used.","examples":["2026-06-03T12:15:00.000Z"],"type":"string"},"uploadedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the object upload completed, or null while pending.","examples":["2026-06-03T12:05:00.000Z"],"type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/storageUploadSession"},"networkRequest":{"type":"object","allOf":[{"type":"object","required":["id","application","deployment","deploymentFunction","deploymentAsset","storageBucket","storageObject","request","response","metrics","timings","startedAt","completedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"application":{"type":"object","required":["id","name"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Application that received and routed this request.","type":"string"}}},"deployment":{"description":"Deployment associated with the request when traffic matched deployed code or assets.","nullable":true,"anyOf":[{"type":"object","required":["id","status"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"}}},{"type":"null"}]},"deploymentFunction":{"description":"Function route that handled the request, or null when the request did not execute a function.","nullable":true,"anyOf":[{"type":"object","required":["id","name","path","region"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"nullable":true,"anyOf":[{"description":"Function display name configured for the route, or null if unnamed.","type":"string"},{"type":"null"}]},"path":{"description":"Application route path that matched this serverless function.","type":"string"},"region":{"nullable":true,"anyOf":[{"description":"Execution region that handled the function request, or null if not recorded.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"deploymentAsset":{"description":"Static deployment asset that handled the request, or null when the request was not served from an asset.","nullable":true,"anyOf":[{"type":"object","required":["id","path","objectKey"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"path":{"description":"Application route path that matched this static deployment asset.","type":"string"},"objectKey":{"description":"Storage object key backing the served static asset.","type":"string"}}},{"type":"null"}]},"storageBucket":{"description":"Storage bucket involved in the request when traffic was served through Network storage.","nullable":true,"anyOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Storage bucket that served this object request.","type":"string"},"slug":{"description":"Bucket slug used in the storage serving hostname.","type":"string"}}},{"type":"null"}]},"storageObject":{"description":"Storage object involved in the request when a concrete object was served.","nullable":true,"anyOf":[{"type":"object","required":["id","key","contentType"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Object key/path served by this storage request.","type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Stored object MIME type, or null when unknown.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"request":{"type":"object","required":["method","hostname","path","query","protocol","country","userAgent","referer"],"properties":{"method":{"description":"HTTP method sent by the client, such as `GET`, `POST`, or `PATCH`.","type":"string"},"hostname":{"description":"Hostname that received the request, including custom domains and storage hostnames.","type":"string"},"path":{"description":"URL path used for route matching inside Network routing.","type":"string"},"query":{"nullable":true,"anyOf":[{"description":"Sanitized query string without the leading `?`, or null when no query was recorded.","type":"string"},{"type":"null"}]},"protocol":{"nullable":true,"anyOf":[{"description":"Protocol observed by the edge, usually `https`.","type":"string"},{"type":"null"}]},"country":{"nullable":true,"anyOf":[{"description":"ISO 3166-1 alpha-2 country code inferred at the edge, or null if unavailable.","type":"string"},{"type":"null"}]},"userAgent":{"nullable":true,"anyOf":[{"description":"Sanitized client User-Agent header used for debugging traffic sources.","type":"string"},{"type":"null"}]},"referer":{"nullable":true,"anyOf":[{"description":"Sanitized Referer header used for debugging traffic origins.","type":"string"},{"type":"null"}]}}},"response":{"type":"object","required":["status","cacheStatus","cacheHit","region","edgeLocation"],"properties":{"status":{"nullable":true,"anyOf":[{"description":"HTTP status code returned to the client, or null if the request did not complete.","type":"number"},{"type":"null"}]},"cacheStatus":{"nullable":true,"anyOf":[{"default":"hit","description":"CDN cache state recorded for this request when cache metadata was available.","type":"string","enum":["hit","miss","bypass","revalidated","stale","updating"]},{"type":"null"}]},"cacheHit":{"nullable":true,"anyOf":[{"description":"Whether the response body was served from cache instead of the origin/runtime.","type":"boolean"},{"type":"null"}]},"region":{"nullable":true,"anyOf":[{"description":"Function or storage origin region that handled the request.","type":"string"},{"type":"null"}]},"edgeLocation":{"nullable":true,"anyOf":[{"description":"Edge location identifier closest to the client for this request.","type":"string"},{"type":"null"}]}}},"metrics":{"type":"object","required":["requestBodyBytes","responseBodyBytes","bytesSent","durationMs"],"properties":{"requestBodyBytes":{"nullable":true,"anyOf":[{"description":"Client request body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"responseBodyBytes":{"nullable":true,"anyOf":[{"description":"Origin/runtime response body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"bytesSent":{"nullable":true,"anyOf":[{"description":"Total bytes sent from Network edge to the client.","type":"number"},{"type":"null"}]},"durationMs":{"nullable":true,"anyOf":[{"description":"End-to-end request duration observed by Network, in milliseconds.","type":"number"},{"type":"null"}]}}},"timings":{"description":"Phases of `metrics.durationMs`. Each is null when it was not measured or the request did not go through it; when measured, the three add up to `metrics.durationMs`.","type":"object","required":["edgeMs","coldStartMs","functionMs"],"properties":{"edgeMs":{"nullable":true,"anyOf":[{"description":"Edge time: `metrics.durationMs` minus cold start and function time, i.e. routing, admission, asset reads and, for CDN-fronted requests, the CDN hop, in ms.","type":"number"},{"type":"null"}]},"coldStartMs":{"nullable":true,"anyOf":[{"description":"Time waiting for compute (an instance waking, scale-out, a suspend transition or replacement) before the function ran, in ms.","type":"number"},{"type":"null"}]},"functionMs":{"nullable":true,"anyOf":[{"description":"Time from dispatch to the function until its response headers arrived, in ms.","type":"number"},{"type":"null"}]}}},"startedAt":{"format":"date-time","description":"ISO 8601 timestamp when Network started handling the request.","type":"string"},"completedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the request completed, or null if completion was not recorded.","type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/networkRequestSummary"},{"type":"object","required":["requestHeaders","responseHeaders"],"properties":{"requestHeaders":{"description":"Sanitized request headers captured for debugging. Sensitive values are removed before storage.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},"responseHeaders":{"description":"Sanitized response headers captured for debugging. Sensitive values are removed before storage.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}}],"$id":"#/components/schemas/networkRequest"},"networkRequestSummary":{"type":"object","required":["id","application","deployment","deploymentFunction","deploymentAsset","storageBucket","storageObject","request","response","metrics","timings","startedAt","completedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"application":{"type":"object","required":["id","name"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Application that received and routed this request.","type":"string"}}},"deployment":{"description":"Deployment associated with the request when traffic matched deployed code or assets.","nullable":true,"anyOf":[{"type":"object","required":["id","status"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"status":{"description":"Current deployment lifecycle state. Use this value to decide whether a deployment is still pending work, actively processing, ready to serve traffic, or failed.","type":"string","enum":["PENDING","QUEUED","STARTING","BUILDING","PROVISIONING","WAITING_FOR_CAPACITY","WAITING_FOR_RUNTIME_SNAPSHOT","ACTIVE","FAILED","EXPIRED"],"$id":"#/components/schemas/deploymentStatus"}}},{"type":"null"}]},"deploymentFunction":{"description":"Function route that handled the request, or null when the request did not execute a function.","nullable":true,"anyOf":[{"type":"object","required":["id","name","path","region"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"nullable":true,"anyOf":[{"description":"Function display name configured for the route, or null if unnamed.","type":"string"},{"type":"null"}]},"path":{"description":"Application route path that matched this serverless function.","type":"string"},"region":{"nullable":true,"anyOf":[{"description":"Execution region that handled the function request, or null if not recorded.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"deploymentAsset":{"description":"Static deployment asset that handled the request, or null when the request was not served from an asset.","nullable":true,"anyOf":[{"type":"object","required":["id","path","objectKey"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"path":{"description":"Application route path that matched this static deployment asset.","type":"string"},"objectKey":{"description":"Storage object key backing the served static asset.","type":"string"}}},{"type":"null"}]},"storageBucket":{"description":"Storage bucket involved in the request when traffic was served through Network storage.","nullable":true,"anyOf":[{"type":"object","required":["id","name","slug"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"name":{"description":"Storage bucket that served this object request.","type":"string"},"slug":{"description":"Bucket slug used in the storage serving hostname.","type":"string"}}},{"type":"null"}]},"storageObject":{"description":"Storage object involved in the request when a concrete object was served.","nullable":true,"anyOf":[{"type":"object","required":["id","key","contentType"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"key":{"description":"Object key/path served by this storage request.","type":"string"},"contentType":{"nullable":true,"anyOf":[{"description":"Stored object MIME type, or null when unknown.","type":"string"},{"type":"null"}]}}},{"type":"null"}]},"request":{"type":"object","required":["method","hostname","path","query","protocol","country","userAgent","referer"],"properties":{"method":{"description":"HTTP method sent by the client, such as `GET`, `POST`, or `PATCH`.","type":"string"},"hostname":{"description":"Hostname that received the request, including custom domains and storage hostnames.","type":"string"},"path":{"description":"URL path used for route matching inside Network routing.","type":"string"},"query":{"nullable":true,"anyOf":[{"description":"Sanitized query string without the leading `?`, or null when no query was recorded.","type":"string"},{"type":"null"}]},"protocol":{"nullable":true,"anyOf":[{"description":"Protocol observed by the edge, usually `https`.","type":"string"},{"type":"null"}]},"country":{"nullable":true,"anyOf":[{"description":"ISO 3166-1 alpha-2 country code inferred at the edge, or null if unavailable.","type":"string"},{"type":"null"}]},"userAgent":{"nullable":true,"anyOf":[{"description":"Sanitized client User-Agent header used for debugging traffic sources.","type":"string"},{"type":"null"}]},"referer":{"nullable":true,"anyOf":[{"description":"Sanitized Referer header used for debugging traffic origins.","type":"string"},{"type":"null"}]}}},"response":{"type":"object","required":["status","cacheStatus","cacheHit","region","edgeLocation"],"properties":{"status":{"nullable":true,"anyOf":[{"description":"HTTP status code returned to the client, or null if the request did not complete.","type":"number"},{"type":"null"}]},"cacheStatus":{"nullable":true,"anyOf":[{"default":"hit","description":"CDN cache state recorded for this request when cache metadata was available.","type":"string","enum":["hit","miss","bypass","revalidated","stale","updating"]},{"type":"null"}]},"cacheHit":{"nullable":true,"anyOf":[{"description":"Whether the response body was served from cache instead of the origin/runtime.","type":"boolean"},{"type":"null"}]},"region":{"nullable":true,"anyOf":[{"description":"Function or storage origin region that handled the request.","type":"string"},{"type":"null"}]},"edgeLocation":{"nullable":true,"anyOf":[{"description":"Edge location identifier closest to the client for this request.","type":"string"},{"type":"null"}]}}},"metrics":{"type":"object","required":["requestBodyBytes","responseBodyBytes","bytesSent","durationMs"],"properties":{"requestBodyBytes":{"nullable":true,"anyOf":[{"description":"Client request body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"responseBodyBytes":{"nullable":true,"anyOf":[{"description":"Origin/runtime response body size in bytes, or null when not measured.","type":"number"},{"type":"null"}]},"bytesSent":{"nullable":true,"anyOf":[{"description":"Total bytes sent from Network edge to the client.","type":"number"},{"type":"null"}]},"durationMs":{"nullable":true,"anyOf":[{"description":"End-to-end request duration observed by Network, in milliseconds.","type":"number"},{"type":"null"}]}}},"timings":{"description":"Phases of `metrics.durationMs`. Each is null when it was not measured or the request did not go through it; when measured, the three add up to `metrics.durationMs`.","type":"object","required":["edgeMs","coldStartMs","functionMs"],"properties":{"edgeMs":{"nullable":true,"anyOf":[{"description":"Edge time: `metrics.durationMs` minus cold start and function time, i.e. routing, admission, asset reads and, for CDN-fronted requests, the CDN hop, in ms.","type":"number"},{"type":"null"}]},"coldStartMs":{"nullable":true,"anyOf":[{"description":"Time waiting for compute (an instance waking, scale-out, a suspend transition or replacement) before the function ran, in ms.","type":"number"},{"type":"null"}]},"functionMs":{"nullable":true,"anyOf":[{"description":"Time from dispatch to the function until its response headers arrived, in ms.","type":"number"},{"type":"null"}]}}},"startedAt":{"format":"date-time","description":"ISO 8601 timestamp when Network started handling the request.","type":"string"},"completedAt":{"nullable":true,"anyOf":[{"format":"date-time","description":"ISO 8601 timestamp when the request completed, or null if completion was not recorded.","type":"string"},{"type":"null"}]}},"$id":"#/components/schemas/networkRequestSummary"},"customDomain":{"type":"object","required":["id","applicationId","hostname","unicodeHostname","apex","isApex","state","suspendedReason","target","primary","ownership","requiredRecords","error","certificate","dns","nextCheckAt","activatedAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"applicationId":{"format":"uuid","description":"Application the domain is attached to.","type":"string"},"hostname":{"description":"Hostname in ASCII (punycode) form, lowercased.","examples":["shop.example.com"],"type":"string"},"unicodeHostname":{"description":"Hostname for display, with international characters.","type":"string"},"apex":{"description":"Registrable domain of the hostname.","examples":["example.com"],"type":"string"},"isApex":{"description":"True when the hostname is the registrable domain itself.","type":"boolean"},"state":{"type":"string","enum":["pending_ownership","pending_dns","issuing_certificate","active","degraded","failed","suspended","removing"]},"suspendedReason":{"anyOf":[{"const":"claimed","type":"string"},{"const":"admin","type":"string"},{"const":"plan_limit","type":"string"},{"type":"null"}]},"target":{"type":"object","required":["type","branchId","redirectTo","redirectStatusCode","redirectPreservePath"],"properties":{"type":{"type":"string","enum":["production","branch","redirect"]},"branchId":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}]},"redirectTo":{"anyOf":[{"type":"string"},{"type":"null"}]},"redirectStatusCode":{"anyOf":[{"type":"number"},{"type":"null"}]},"redirectPreservePath":{"type":"boolean"}}},"primary":{"description":"Whether this is the application’s primary URL.","type":"boolean"},"ownership":{"type":"object","required":["name","verified"],"properties":{"name":{"description":"Domain whose verification authorizes this hostname, usually the registrable domain.","anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"requiredRecords":{"description":"DNS records to publish, in the order to add them.","type":"array","items":{"type":"object","required":["purpose","type","name","host","value","status"],"properties":{"purpose":{"type":"string","enum":["ownership","routing"]},"type":{"type":"string","enum":["TXT","CNAME","ALIAS"]},"name":{"description":"Fully qualified record name.","examples":["shop.example.com"],"type":"string"},"host":{"description":"Record name relative to the registrable domain, as most DNS dashboards expect it (`@` for the apex).","examples":["shop"],"type":"string"},"value":{"description":"Record value to publish.","examples":["cname.gigadrive-dns.net"],"type":"string"},"status":{"type":"string","enum":["ok","pending","mismatch"]}}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"certificate":{"type":"object","required":["status","expiresAt"],"properties":{"status":{"type":"string","enum":["none","pending","issued","failed","blocked_caa"]},"expiresAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]}}},"dns":{"anyOf":[{"type":"object","required":["checkedAt","cname","a","aaaa","nameservers","pointsToEdge"],"properties":{"checkedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"cname":{"description":"CNAME chain starting at the hostname.","type":"array","items":{"type":"string"}},"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"nameservers":{"description":"Nameservers of the registrable domain.","type":"array","items":{"type":"string"}},"pointsToEdge":{"type":"boolean"}}},{"type":"null"}]},"nextCheckAt":{"description":"When Gigadrive checks the domain next, or null when nothing is scheduled.","anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"activatedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/customDomain"},"domainOwnership":{"type":"object","required":["id","organizationId","name","unicodeName","status","verificationMethod","record","error","verifiedAt","nextCheckAt","createdAt","updatedAt"],"properties":{"id":{"description":"Stable UUID for this resource. Use this value in follow-up API calls that reference the resource.","format":"uuid","examples":["0197b2f0-8b6d-7c2a-9f4e-111111111111"],"type":"string","$id":"#/components/schemas/id"},"organizationId":{"format":"uuid","type":"string"},"name":{"description":"Verified (or claimed) domain in ASCII form.","examples":["example.com"],"type":"string"},"unicodeName":{"type":"string"},"status":{"type":"string","enum":["pending","verified"]},"verificationMethod":{"anyOf":[{"const":"txt","type":"string"},{"const":"nameservers","type":"string"},{"const":"domain_connect","type":"string"},{"const":"legacy_fqdn_txt","type":"string"},{"type":"null"}]},"record":{"description":"TXT record that proves control of the domain. Keep it published after verification.","type":"object","required":["type","name","host","value"],"properties":{"type":{"const":"TXT","type":"string"},"name":{"examples":["_gigadrive-challenge.example.com"],"type":"string"},"host":{"examples":["_gigadrive-challenge"],"type":"string"},"value":{"examples":["gigadrive-verification=4f1c2e8a9b7d6c5e4f3a2b1c0d9e8f7a"],"type":"string"}}},"error":{"description":"Why the domain is not working yet, or null when there is nothing to fix.","anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"description":"Stable code of the problem, for example `dns_record_missing`, `dns_proxied_by_cloudflare`, `cert_blocked_caa` or `ownership_timeout`.","examples":["dns_record_missing"],"type":"string"},"message":{"description":"What is wrong and how to fix it.","examples":["No DNS record points this hostname at Gigadrive yet."],"type":"string"}}},{"type":"null"}]},"verifiedAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"createdAt":{"format":"date-time","description":"ISO 8601 timestamp for when this API resource was first created in Gigadrive Network.","examples":["2026-06-03T12:00:00.000Z"],"type":"string"},"updatedAt":{"format":"date-time","description":"ISO 8601 timestamp for the most recent persisted change to this API resource.","examples":["2026-06-03T12:30:00.000Z"],"type":"string"}},"$id":"#/components/schemas/domainOwnership"},"domainError":{"type":"object","required":["error","code"],"properties":{"error":{"description":"Human-readable explanation of why the request failed, suitable for showing to users.","examples":["shop.example.com is already attached to an application in this organization."],"type":"string"},"code":{"description":"Stable machine-readable error code: `unauthenticated`, `insufficient_scope`, `forbidden`, `not_found`, `invalid_domain`, `blocked_domain`, `invalid_target`, `feature_disabled`, `domain_in_use`, `conflict`, `ownership_exists`, `ownership_in_use`, `claim_refused`, `quota_exceeded`, `rate_limited` or `internal_error`.","examples":["domain_in_use"],"type":"string"},"reason":{"description":"Finer-grained reason for some codes, for example `redirects_not_available` for `invalid_target`, `primary_taken` for `conflict` or `ownership_not_live` for `claim_refused`.","examples":["redirects_not_available"],"type":"string"},"retryAfterSeconds":{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"description":"Seconds to wait before retrying. Set for `rate_limited`, together with the `Retry-After` response header.","examples":[60],"type":"integer"}]}},"$id":"#/components/schemas/domainError"}}},"security":[{"gigadriveUserOAuth2":[]},{"networkOAuth2":[]},{"bearerAuth":[]}]}