openapi: 3.0.3 info: title: Volcano Hosting API description: |- Public API for Volcano Hosting clients, SDKs, and CLI tooling (Port 8000). This specification intentionally excludes first-party/internal APIs. See api/openapi-internal.yaml for non-public internal and Builder operations. version: 3.0.0 contact: name: Volcano Hosting email: support@volcano.dev servers: - url: https://api.volcano.dev description: Production API server - url: http://localhost:8000 description: Development API server (use VOLCANO_API_URL env var) tags: - name: Projects description: Project management operations - name: Logs description: Project-scoped log search and activity APIs - name: Functions description: Function deployment and management - name: Frontends description: Frontend deployment and management. Supports Next.js 15.x and 16.x with Node.js 22.x or 24.x inferred from package.json engines.node when the selected Node.js family satisfies the installed Next.js package engines.node constraint. - name: Tokens description: Service keys for function invocation and database admin access - name: Variables description: Environment variable management - name: Databases description: Serverless PostgreSQL database provisioning and management - name: Database Branches description: Short-lived forks of a database for development and testing - name: Database Queries description: REST API for querying databases (SELECT, INSERT, UPDATE, DELETE) - name: Authentication description: End-user authentication (signup, signin, profile) - name: Auth Admin description: Auth user management (platform admin only) - name: Auth Configuration description: Authentication settings and anon keys - name: Anon Keys description: Project-specific public keys for frontend auth - name: Service Keys description: Project-specific secret keys for admin operations (bypass RLS - backend only!) - name: OAuth Configuration description: OAuth provider configuration (Google, GitHub, Microsoft, Apple) - name: OAuth Authentication description: OAuth login flows and provider management for end users - name: Git Connections description: Platform-user git provider connections for deployment source integrations - name: Project Imports description: Read-only project source discovery and import readiness checks - name: Storage Buckets description: Storage bucket management (platform admin) - name: Storage Policies description: Storage access policy management (platform admin) - name: Storage Admin description: Storage statistics and cross-bucket object listing (platform admin) - name: Storage Objects description: File upload, download, and management (SDK-facing) - name: Locks description: Project-scoped leases for backend coordination (service-role keys only) - name: Realtime description: WebSocket realtime configuration and monitoring - name: System description: System health and monitoring endpoints - name: CLI Authentication description: | Browser-based CLI login flow for automatic token provisioning. The CLI creates a session, opens a browser for user authentication, and polls for completion. Session completion is handled by volcano.dev via the Management API. paths: /user/imports/connect: post: tags: - Project Imports summary: Start a project import provider connection description: | Starts a first-party dashboard user's provider connection flow. The response sets a short-lived HttpOnly browser-binding cookie for the public provider callback. operationId: startImportConnect security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: query required: false description: Import provider to connect. Defaults to Vercel. schema: $ref: '#/components/schemas/ImportProvider' - name: redirect in: query required: false description: Validated application URL used after the provider callback. schema: type: string format: uri pattern: '^https://[^/?#]+(?:[/?][^#]*)?$|^http://(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?(?:[/?][^#]*)?$' responses: '200': description: Provider authorization URL content: application/json: schema: $ref: '#/components/schemas/ImportConnectStartResponse' '400': description: Unsupported provider or invalid redirect content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to start the connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Import provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /imports/{provider}/callback: get: tags: - Project Imports summary: Complete a project import provider connection description: | Public provider callback protected by signed state and the browser-binding cookie created by startImportConnect. operationId: completeImportConnect security: [] parameters: - name: provider in: path required: true schema: $ref: '#/components/schemas/ImportProvider' - name: state in: query required: true description: Signed connect state generated by startImportConnect. schema: type: string - name: code in: query required: false description: Provider authorization code. schema: type: string - name: error in: query required: false description: Provider error category. schema: type: string - name: teamId in: query required: false description: Vercel team selected during installation. schema: type: string - name: configurationId in: query required: false description: Vercel Integration configuration identifier. schema: type: string - name: next in: query required: false description: Provider completion URL validated by the provider adapter. schema: type: string - name: source in: query required: false description: Vercel installation source indicator. schema: type: string responses: '303': description: Redirect to the provider completion URL, signed application redirect, or Volcano import page headers: Location: description: Validated redirect target schema: type: string '400': description: Invalid callback request, state, or browser binding content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many callback attempts content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to complete the connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Import provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /user/imports/connections: get: tags: - Project Imports summary: List project import provider connections operationId: listImportConnections security: - UserToken: [] - AuthUserAccessToken: [] responses: '200': description: Stored import provider connections content: application/json: schema: $ref: '#/components/schemas/ImportConnectionsResponse' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to list connections content: application/json: schema: $ref: '#/components/schemas/Error' /user/imports/connections/{connectionId}: delete: tags: - Project Imports summary: Delete a project import provider connection operationId: deleteImportConnection security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: connectionId in: path required: true description: Connection ID to delete. schema: type: string format: uuid responses: '204': description: Connection deleted '400': description: Malformed connection ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Connection changed while it was being deleted content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to delete the connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Import provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /imports/{provider}/sources: get: tags: - Project Imports summary: List project sources available from a provider connection description: Lists provider projects without changing provider or Volcano resources. operationId: listImportSources security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: $ref: '#/components/schemas/ImportProvider' - name: connection_id in: query required: true description: Owned provider connection used for discovery. schema: type: string format: uuid responses: '200': description: Provider sources available to import content: application/json: schema: $ref: '#/components/schemas/ImportSourcesResponse' '400': description: Invalid provider or connection ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The provider connection lacks a required Integration scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection or provider source not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The provider connection must be reconnected content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Provider rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to list provider sources content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Provider unavailable or integration not configured content: application/json: schema: $ref: '#/components/schemas/Error' /imports/{provider}/preflight: post: tags: - Project Imports summary: Check whether a provider project is ready to import description: Produces a deterministic read-only readiness report for a proposed new Volcano project. operationId: preflightProjectImport security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: $ref: '#/components/schemas/ImportProvider' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectImportPreflightRequest' responses: '200': description: Import readiness report content: application/json: schema: $ref: '#/components/schemas/ProjectImportReport' '400': description: Invalid provider, source, project name, or target content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The provider connection lacks a required Integration scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection or provider source not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The provider connection must be reconnected content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Provider rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to produce an import readiness report content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Provider unavailable or integration not configured content: application/json: schema: $ref: '#/components/schemas/Error' /imports/{provider}/runs: post: tags: - Project Imports summary: Start a Vercel project import description: Creates a Volcano project from an importable production preflight report. Retrying the same request with the same Idempotency-Key returns the existing run. operationId: startProjectImport security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: $ref: '#/components/schemas/ImportProvider' - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 pattern: '^[!-~]+$' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectImportStartRequest' responses: '202': description: Import run accepted headers: Location: required: true schema: type: string content: application/json: schema: $ref: '#/components/schemas/ProjectImportRun' '400': description: Invalid request or idempotency key content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Provider permission or project admission denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection or provider source not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Preflight is stale, idempotency key was reused, or destination conflicts content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Source is not importable content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Provider rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to start the import content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Provider unavailable or integration not configured content: application/json: schema: $ref: '#/components/schemas/Error' /imports/{provider}/runs/{runId}: get: tags: - Project Imports summary: Get a project import run operationId: getProjectImportRun security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: $ref: '#/components/schemas/ImportProvider' - name: runId in: path required: true schema: type: string format: uuid responses: '200': description: Import run status content: application/json: schema: $ref: '#/components/schemas/ProjectImportRun' '400': description: Invalid import run ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Import run not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to get the import run content: application/json: schema: $ref: '#/components/schemas/Error' /user/git/connect: post: tags: - Git Connections summary: Start a git provider connection description: | Starts a first-party dashboard user's git provider connection flow and returns the provider authorization URL. The response also sets a short-lived HttpOnly callback binding cookie tied to the authenticated user through the signed provider state. operationId: startGitConnect security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: provider in: query required: false description: Git provider to connect. Defaults to github. schema: type: string enum: [github] default: github - name: redirect in: query required: false description: URL to redirect the browser to after the provider callback completes. schema: type: string responses: '200': description: Provider authorization URL content: application/json: schema: $ref: '#/components/schemas/GitConnectStartResponse' '400': description: Unsupported provider or invalid redirect content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to start the connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /user/git/connections: get: tags: - Git Connections summary: List git provider connections operationId: listGitConnections security: - UserToken: [] - AuthUserAccessToken: [] responses: '200': description: Stored git provider connections content: application/json: schema: $ref: '#/components/schemas/GitConnectionsResponse' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to list connections content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /user/git/connections/{connectionId}: delete: tags: - Git Connections summary: Delete a git provider connection operationId: deleteGitConnection security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: connectionId in: path required: true description: Connection ID to delete schema: type: string format: uuid responses: '204': description: Connection deleted '400': description: Malformed connection ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to delete connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /user/git/connections/{connectionId}/installations: get: tags: - Git Connections summary: List GitHub App installations accessible to a connection description: | Live proxy to GitHub: lists the platform GitHub App installations the connection's stored user token can access. Nothing is persisted by this call. operationId: listGitInstallations security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: connectionId in: path required: true description: Connection ID to browse installations for. schema: type: string format: uuid responses: '200': description: Installations accessible to the connection content: application/json: schema: $ref: '#/components/schemas/GitInstallationsResponse' '400': description: Malformed connection ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to list installations content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /user/git/connections/{connectionId}/installations/{installationId}/repositories: get: tags: - Git Connections summary: List repos accessible to a connection through an installation description: | Live proxy to GitHub: lists the repos the connection's stored user token can access through installationId. Nothing is persisted by this call. operationId: listGitInstallationRepositories security: - UserToken: [] - AuthUserAccessToken: [] parameters: - name: connectionId in: path required: true description: Connection ID to browse repositories for. schema: type: string format: uuid - name: installationId in: path required: true description: GitHub App installation ID. schema: type: integer format: int64 responses: '200': description: Repositories accessible through the installation content: application/json: schema: $ref: '#/components/schemas/GitRepositoriesResponse' '400': description: Malformed connection or installation ID content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to list repositories content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /github/callback: get: tags: - Git Connections summary: Complete a GitHub App connection callback description: | Public GitHub App callback. The signed state and callback binding cookie bind the provider authorization to the browser that started the flow. operationId: gitConnectCallback security: [] parameters: - name: code in: query required: false description: GitHub user authorization code. schema: type: string - name: state in: query required: true description: Signed connect state generated by startGitConnect. schema: type: string - name: error in: query required: false description: Provider error returned by GitHub. schema: type: string responses: '303': description: Redirect back to the app after a successful or failed connect attempt headers: Location: description: Redirect target schema: type: string '400': description: Invalid callback request or state content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many callback attempts from this client content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to complete the connection content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /projects: get: tags: - Projects summary: List all projects for authenticated user description: | Returns projects that are not deleting or deleted, newest first. Supports two mutually exclusive pagination modes. Offset mode uses `page` and `limit`. Cursor mode uses `cursor` or `ending_before` with `limit`, returns `next_cursor`/`prev_cursor`, and supports a bounded `offset` past the cursor anchor. Supplying `limit` without `page` selects cursor mode. `search` applies a case-insensitive project-name filter in either mode. Sending `page` with `cursor` or `ending_before`, or sending both cursor directions, returns 400. operationId: listProjects security: - UserToken: [] parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedProjects' '400': description: Invalid or conflicting pagination parameters content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Projects summary: Create a new project description: | Creates a project for the authenticated user. Each user can create up to 1,000 projects. Requests over this cap return 403. operationId: createProject security: - UserToken: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProjectRequest' responses: '201': description: Project created content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project limit exceeded for the user content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}: get: tags: - Projects summary: Get project by ID operationId: getProject security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Project' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' patch: tags: - Projects summary: Update project metadata and region policy operationId: updateProject security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateProjectRequest' responses: '200': description: Project updated content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden (for example, selecting subset regions on non-PRO plan) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict (project name already exists or a resource deployment blocks a region change) content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Projects summary: Delete a project description: | Starts asynchronous project deletion. The project remains available from `GET /projects/{id}` with `status: deleting` until cleanup finishes, but is removed from project lists as soon as deletion starts. After cleanup it returns 404. operationId: deleteProject security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '202': description: Project deletion started '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/health: get: tags: - Projects summary: Get project health description: | Returns a fast control-plane health snapshot for the project and its deployed resources. The endpoint does not run live provider probes. A successful request returns 200 even when the project status is `unhealthy`; transport and authorization failures use HTTP errors. operationId: getProjectHealth security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Project health snapshot retrieved content: application/json: schema: $ref: '#/components/schemas/ProjectHealthResponse' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/metrics/query: post: tags: - Projects summary: Query project runtime metrics description: | Evaluates a batch of named, curated runtime metric queries over one trailing time range. Query IDs correlate each request with its result; raw backend query languages are intentionally not exposed. operationId: queryProjectMetrics security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectMetricsQueryRequest' responses: '200': description: Project runtime metric queries evaluated content: application/json: schema: $ref: '#/components/schemas/ProjectMetricsQueryResponse' '400': description: Invalid metric query content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Runtime metrics backend unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/logo: get: tags: - Projects summary: Get the project logo image description: | Returns the raw logo image stored in the project's storage folder. This endpoint is unauthenticated so the asset can be rendered directly in an `` tag; project IDs are unguessable UUIDs and logos are non-sensitive branding. The `Project.logo_url` field exposes a versioned path to this endpoint. operationId: getProjectLogo security: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Logo image content: image/png: schema: type: string format: binary image/jpeg: schema: type: string format: binary image/gif: schema: type: string format: binary image/webp: schema: type: string format: binary image/svg+xml: schema: type: string format: binary '404': description: Project or logo not found content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Projects summary: Upload or replace the project logo description: | Uploads an image as the project's logo, storing it in the project's storage folder. Accepts PNG, JPEG, GIF, WebP, or SVG up to 2 MB. Replaces any existing logo. Returns the updated project, whose `logo_url` reflects the new logo. operationId: uploadProjectLogo security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: multipart/form-data: schema: type: object required: - logo properties: logo: type: string format: binary description: Logo image (PNG, JPEG, GIF, WebP, or SVG; max 2 MB) responses: '200': description: Logo uploaded content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: Bad request (missing file, unsupported type, or too large) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Project is being deleted content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Logo storage is not configured content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Projects summary: Remove the project logo description: | Deletes the project logo from the project's storage folder and clears its record. Returns the updated project with no `logo_url`. operationId: deleteProjectLogo security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Logo removed content: application/json: schema: $ref: '#/components/schemas/Project' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Project is being deleted content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Logo storage is not configured content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/usage: get: tags: - Projects summary: Get usage metrics for a project description: | Returns project usage totals for the current usage month plus recent hourly and daily time series for each tracked metric. operationId: getProjectUsage security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Usage metrics retrieved content: application/json: schema: $ref: '#/components/schemas/ProjectUsageResponse' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/config: get: tags: - Projects summary: Export project configuration description: | Exports the project's current user-facing configuration as a declarative manifest. Returns JSON by default. Request the canonical volcano-config.yaml rendering with `Accept: application/yaml` or `?format=yaml`; the YAML is returned verbatim as the raw response body (`Content-Type: application/yaml`) and is meant to be saved as-is. Write-only secrets (SMTP password, OAuth client secrets, TLS material) are omitted from the export; the YAML rendering adds a header comment describing how to set them via CLI environment interpolation. operationId: getProjectConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: format in: query required: false description: Response format override. Takes precedence over the Accept header. schema: type: string enum: [json, yaml] responses: '200': description: | Current project configuration. JSON by default; when YAML is requested the body is the canonical volcano-config.yaml document served verbatim with `Content-Type: application/yaml`. content: application/json: schema: $ref: '#/components/schemas/ProjectConfig' application/yaml: schema: type: string format: binary description: | Canonical volcano-config.yaml document returned verbatim, ready to be saved as-is. '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Projects summary: Apply project configuration description: | Validates and applies a declarative configuration manifest to the project, reconciling each declared section and returning a per-resource report. Omitted sections are untouched. Declared collection keys (`variables`, `buckets[].policies`, `auth.providers.oauth`, `auth.email.templates`, `functions[].schedulers`) are fully synced: resources absent from the manifest are deleted. Functions, frontends, databases, and buckets are never created or deleted; manifest entries for resources that do not exist are skipped and reported in `skipped`, and existing resources missing from a declared section are reported in `missing`. Validation failures (including plan-gate violations) return 422 and nothing is applied. Set `dry_run=true` to get the projected report without applying changes. Applies are serialized per project; a concurrent apply returns 409. operationId: applyProjectConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: dry_run in: query required: false description: Validate and report projected actions without applying changes. schema: type: boolean default: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectConfig' responses: '200': description: | Apply report. Individual entries may still carry `action: error` for apply-phase failures (summary.errors > 0); already-applied changes are not rolled back. content: application/json: schema: $ref: '#/components/schemas/ProjectConfigApplyResult' '400': description: Malformed request body content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Another apply is in progress for this project content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Manifest validation failed; nothing was applied content: application/json: schema: $ref: '#/components/schemas/ProjectConfigValidationErrorResponse' /projects/{id}/git-connection/production-branch: put: tags: - Projects - Git Connections summary: Set the branch a project deploys from description: | Changes only the production branch, leaving the repository binding alone. PUT /projects/{id}/git-connection can also set it, but that is a full rebind: it needs connection_id, installation_id and a repository selector resent, and re-resolves the repository against GitHub for a field that does not depend on it. The branch does not have to exist. It is validated as a Git branch name and nothing more, so a project can be pointed at a branch that is about to be pushed — the case a repository created empty depends on. Setting the branch here marks it as the project's own choice, so a later default-branch rename on GitHub no longer moves it. Projects that never set one keep following the repository's default branch. operationId: setProjectGitProductionBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetProjectGitProductionBranchRequest' responses: '200': description: The project's repo connection, with the new branch content: application/json: schema: $ref: '#/components/schemas/ProjectGitConnection' '400': description: | Malformed request body, or a production_branch that is not a valid Git branch name content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project not owned by the caller content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: | Project not found, or it has no repository connected. The branch is part of the connection, so there is nothing to set it on until one exists. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to set the production branch content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/git-connection: get: tags: - Projects - Git Connections summary: Get a project's repo connection operationId: getProjectGitConnection security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: The project's current repo connection content: application/json: schema: $ref: '#/components/schemas/ProjectGitConnection' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project not owned by the caller content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found, or has no repo connection content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to get project git connection content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Projects - Git Connections summary: Connect or update a project's repo connection description: | Full replace, following Vercel's model: many projects may point at the same repo, so this only binds the project — it never creates or deletes git-provider state. Used for both the initial connect and later edits (repo change, root directory, production branch). Resolves the repository_id or repo_full_name selector against the repos accessible through installation_id via connection_id's stored GitHub user token, then persists repository metadata only from that validated GitHub response. operationId: connectProjectGit security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectProjectGitRequest' responses: '200': description: The project's repo connection content: application/json: schema: $ref: '#/components/schemas/ProjectGitConnection' '400': description: | Malformed request body, no repository selector, selectors that identify different repositories, a production_branch that is not a valid Git branch name, no production_branch on a repository with no default branch to follow (name one to connect a repository that has no commits yet), or a production_branch other than the new repository's default in a request that also changes repository. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | Project not owned by the caller, or the selected repository is not accessible through installation_id content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to connect project git content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Git provider integration is not configured content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Projects - Git Connections summary: Disconnect a project's repo connection operationId: disconnectProjectGit security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '204': description: Connection removed '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project not owned by the caller content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found, or has no repo connection content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to disconnect project git content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/git-deploy-settings: get: tags: - Projects - Git Connections summary: Get a project's Git auto-deploy settings operationId: getProjectGitDeploySettings security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: The project's current Git auto-deploy settings content: application/json: schema: $ref: '#/components/schemas/ProjectGitDeploySettings' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project not owned by the caller content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to get project git deploy settings content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Projects - Git Connections summary: Update a project's Git auto-deploy settings description: | Full replace of the project's Git auto-deploy settings: what a push to the connected repo's production branch deploys. Connecting a repository sets auto_deploy_enabled and deploy_functions to true for a project that has never called this endpoint, so a push deploys without any further setup. Once these settings have been saved here they are the project's own: connecting, rebinding, disconnecting and reconnecting all leave them untouched, including when they were saved before any repository was connected. Frontend settings are off until set here; the frontend need not exist when they are saved, since frontend_name is resolved at deploy time. operationId: updateProjectGitDeploySettings security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateProjectGitDeploySettingsRequest' responses: '200': description: The project's updated Git auto-deploy settings content: application/json: schema: $ref: '#/components/schemas/ProjectGitDeploySettings' '400': description: Malformed request body, or frontend_app_root without frontend_name content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Project not owned by the caller content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to update project git deploy settings content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}/queries: get: tags: - Databases summary: Get database queries description: | Returns the database's current top queries from pg_stat_statements ranked by total execution time. **PRO plan required.** This endpoint is only available to projects owned by users on the PRO billing plan. operationId: getProjectDatabaseQueries security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - name: limit in: query description: Maximum number of queries to return. schema: type: integer minimum: 1 maximum: 100 default: 10 responses: '200': description: Database query performance retrieved content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryPerformanceResponse' '400': description: Bad request - invalid query parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or database not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /deployments: get: tags: - Projects summary: List deployments across a user's projects description: | Lists Function and Frontend deployment attempts across every project the user owns, newest first. Pass `project_id` to narrow the feed to a single project. Scope is project **ownership** (`projects.user_id`). `owner_id` names whose deployments to return, not who started them — the actor is `initiated_by_user_id`, which this endpoint does not filter on. With a user token the scope is always the authenticated user: `owner_id` may be omitted, or set to that same user, but naming anyone else is refused with 403. Service callers on the management API must pass it, since they have no authenticated user. The owner is not checked for existence: an id with no projects returns an empty page rather than `404`. Unlike `/users/{id}/usage`, this endpoint is polled to detect an event, so a caller needs `404` to keep meaning "this route is not served here" — which is how a consumer notices it is running against an older release. A mistyped owner therefore reads as "nothing deployed"; callers that need to tell those apart should verify the user through `GET /users/{id}` first. Ordering is selectable. The default is the feed order — most recent attempt first. `completed_at.asc` orders by completion, oldest first, and considers only attempts that finished; combined with `limit=1` and a `status` filter it answers "when did this user first succeed" in one bounded query. Both pagination modes are supported, selected exactly as `/projects/{id}/deployments` selects them: `cursor`/`ending_before` (or a `limit` with no `page`) uses keyset pagination; otherwise `page`/`limit` offset pagination. `page` with a cursor, and `cursor` with `ending_before`, are rejected. A cursor is bound to every filter *and* to `order`, so changing any of them mid-pagination rejects the cursor rather than silently skipping or repeating rows. The keyset position is `(created_at, id)` for `created_at.desc` and `(completed_at, id)` for `completed_at.asc`. operationId: listDeployments security: - UserToken: [] parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/DeploymentOwnerId' - name: project_id in: query required: false description: Restrict the feed to a single project owned by the user. schema: type: string format: uuid - name: created_after in: query required: false description: Restrict results to attempts created at or after this timestamp. schema: type: string format: date-time - $ref: '#/components/parameters/DeploymentResourceType' - $ref: '#/components/parameters/DeploymentStatus' - $ref: '#/components/parameters/DeploymentOperation' - $ref: '#/components/parameters/DeploymentOrder' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedProjectDeployments' '400': description: Bad request - invalid filter or pagination content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - owner_id names a different user content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/deployments: get: tags: - Projects summary: List deployments in a project description: | Lists Function and Frontend deployment attempts across the project, ordered most-recent first. Each item includes a normalized resource reference so clients can render both resource types without extra fetches. operationId: listProjectDeployments security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' - name: created_after in: query required: false description: Restrict results to attempts created at or after this timestamp. schema: type: string format: date-time - name: resource_type in: query required: false description: | Restrict the feed to a single resource type. Omit to return both Function and Frontend deployments. schema: type: string enum: [function, frontend] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedProjectDeployments' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/deployments/summary: get: tags: - Projects summary: Summarize deployments in a project description: | Summarizes deployment attempts for one comparable resource pipeline. Success rate uses conclusive outcomes only: active and deleted attempts are successful; failed and degraded attempts are failures; in-progress and superseded attempts are excluded. Median build duration includes completed, non-superseded attempts with recorded build work, including failed builds. operationId: summarizeProjectDeployments security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: search in: query required: false description: Restrict the summary to resource names containing this value. schema: type: string - name: resource_type in: query required: true description: Restrict the summary to one comparable deployment pipeline. schema: type: string enum: [function, frontend] - name: created_after in: query required: false description: Restrict results to attempts created at or after this timestamp. schema: type: string format: date-time responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ProjectDeploymentSummary' '400': description: Bad request - invalid identifier or filter content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/domains: get: tags: - Frontends summary: List all custom domains in a project description: | Project-scoped custom-domain list. Returns every active custom domain across every frontend in the project (excludes soft-deleted rows). Each item inlines the linked frontend's id and name so the UI does not need a second fetch to render the "Linked to" column. operationId: listProjectCustomDomains security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedProjectCustomDomains' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/functions: get: tags: - Functions summary: List all functions in a project description: | Supports two mutually exclusive pagination modes. Offset mode uses `page` and `limit` and returns `next` (URL). Cursor mode uses `cursor` and `limit`, supports `search` (case-insensitive name match), and returns `next_cursor`/`prev_cursor`. Sending both `page` and `cursor` (or `page` and `search`) returns 400. operationId: listFunctions security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFunctions' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Functions summary: Create or update function code description: | Upload a serverless function source bundle. Direct API clients may send the function code as a ZIP or tar.gz archive via multipart/form-data. The API stores a normalized tar.gz source archive. Cloud deploys should include source files and dependency manifests/lockfiles, not installed dependency directories. Volcano installs Node.js, Python, and Ruby dependencies during the function compile build. Source archive size is enforced by the API with `SOURCE_ARCHIVE_SIZE_LIMIT_MB`; the CLI does not apply its own source archive size limit. After the final container image is built, the publish build enforces `LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB` before pushing. Uploaded source archives cannot contain symlink entries. Safe symlinks created during the cloud build are materialized before publish. Volcano builds and deploys the function asynchronously after upload. A deployment that starts immediately returns a Function resource with `status: provisioning`, then transitions to `active` or `failed`. If another deployment is running, the response preserves the resource's current status and exposes the queued deployment through `pending_deployment_id`. Existing function traffic continues to use the last known-good runtime during an update. A failed update keeps that runtime available and records the attempted deployment as failed. Only one deployment runs for a given function. A newer request supersedes any queued request and starts after the running deployment. Different functions and projects deploy concurrently. If a function with the same name already exists in the project, this operation updates that function's runtime, handler, and source bundle and returns `200 OK`. Each project can contain up to 10,000 functions. Creating a new function over this cap returns 403. operationId: createFunction security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: multipart/form-data: schema: type: object required: - name - code - runtime properties: name: type: string description: DNS-safe function name (lowercase letters, numbers, hyphens; cannot start or end with hyphen) maxLength: 63 pattern: '^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$' example: "my-api-function" code: type: string format: binary description: ZIP or tar.gz archive containing function source code plus dependency manifests/lockfiles. The API enforces SOURCE_ARCHIVE_SIZE_LIMIT_MB and stores a normalized tar.gz source archive. runtime: type: string enum: [nodejs22.x, nodejs24.x, python3.10, python3.11, python3.12, python3.13, python3.14, ruby3.3, ruby3.4, ruby4.0] description: | Runtime environment. Required. - Node.js: nodejs22.x, nodejs24.x - Python: python3.10, python3.11, python3.12, python3.13, python3.14 - Ruby: ruby3.3, ruby3.4, ruby4.0 example: "nodejs24.x" handler: type: string description: | The name of the function to invoke. Defaults to "handler" if not specified. Your code must export/define a function with this name: - Node.js: exports.handler (in index.js) - Python: def handler() (in main.py) - Ruby: def handler() (in main.rb) default: "handler" example: "handler" responses: '201': description: Function created and deployment workflow started content: application/json: schema: $ref: '#/components/schemas/Function' '200': description: Existing function updated; its deployment was started or queued content: application/json: schema: $ref: '#/components/schemas/Function' '400': description: Bad request (invalid file, too large, etc.) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Function limit exceeded for the project content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Function deletion is queued or running content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error (function deployment failed) content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/functions/{functionId}: get: tags: - Functions summary: Get function by ID operationId: getFunction security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Function' '404': description: Function not found content: application/json: schema: $ref: '#/components/schemas/Error' patch: tags: - Functions summary: Update function settings operationId: updateFunction security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateFunctionRequest' examples: makePublic: summary: Make function public (anon keys can invoke) value: is_public: true makePrivate: summary: Make function private (default behavior) value: is_public: false responses: '200': description: Function updated content: application/json: schema: $ref: '#/components/schemas/Function' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Function not found content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Functions summary: Delete a function description: | Schedules asynchronous function deletion. If another deployment is running, the function preserves its current status and exposes the queued deletion through `pending_deployment_id`. Its status changes to `deleting` when cleanup starts. After cleanup, it returns 404 and no longer appears in function lists. operationId: deleteFunction security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' responses: '202': description: Function deletion started or queued '404': description: Function not found content: application/json: schema: $ref: '#/components/schemas/Error' /functions/{functionId}/invoke: post: tags: - Functions summary: Invoke a function description: | Invoke a serverless function. **With Service Key** (admin/background operations): - Use for background jobs, webhooks, cron, admin operations - Function receives payload only (no user context) - Database queries bypass RLS (admin access) **With Auth User Token** (user-facing): - Use for user-initiated actions - Function receives payload + `__volcano_auth` context: ```javascript { user_id: "uuid", email: "user@example.com", project_id: "uuid", role: "authenticated" or "anonymous" } ``` - Database queries enforce RLS (user-scoped data) **With Anon Key** (public function only): - Requires anon key permission: `functions.invoke` - Function must have `is_public: true` - Function receives payload only (no `__volcano_auth`) **Transport and CORS:** - Direct invocation endpoint is intended for `http://api./functions/{functionId}/invoke` - DNS invocation endpoint is `https://{functionId}.functions./` - CORS preflight for invocation allows only `POST, OPTIONS` operationId: invokeFunction security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/FunctionId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FunctionInvocationRequest' examples: serviceCall: summary: Admin/background operation (service key) value: payload: action: "process_batch" items: [1, 2, 3] userCall: summary: User-initiated call (auth token) value: payload: action: "get_profile" anonCall: summary: Public function call (anon key) value: payload: action: "ping_public_endpoint" responses: '200': description: Function response (passthrough from function runtime) headers: X-Volcano-Version: description: Volcano API/runtime version that served this invocation (`` in production, `-` in non-production) schema: type: string X-Volcano-Region: description: Region the function ran in (for example `us-east-1`) schema: type: string content: application/json: schema: $ref: '#/components/schemas/FunctionInvocationResponse' default: description: Function response (passthrough; status code/body/headers come from the function) headers: X-Volcano-Version: description: Volcano API/runtime version that served this invocation (`` in production, `-` in non-production) schema: type: string X-Volcano-Region: description: Region the function ran in (for example `us-east-1`) schema: type: string content: application/json: schema: $ref: '#/components/schemas/FunctionInvocationResponse' '400': description: Bad request - invalid payload or function in failed state content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - CORS blocked, missing `functions.invoke`, or private function with anon key content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Function not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: | Rate limit exceeded (per-function or project-wide limit), or the owning platform user's billing-cycle bandwidth allowance (aggregate ingress + egress) was exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: | Function still provisioning or rate limiting service unavailable. A freshly deployed (or updated) function may briefly report `provisioning` and reject invocations until the background status reconciler observes its deployment workflow completing and transitions it to `active`. This is expected for a few seconds after deploy; clients should retry. content: application/json: schema: $ref: '#/components/schemas/Error' /functions/resolve: get: tags: - Functions summary: Resolve function name for invocation description: | Resolves a DNS-safe function name to its function ID within the caller's project. SDKs use this endpoint internally to invoke by function name while routing by function ID. **With Service Key**: - Allowed **With Auth User Token**: - Allowed **With Anon Key**: - Requires anon key permission: `functions.invoke` - Function must have `is_public: true` operationId: resolveFunctionForInvocation security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - name: name in: query required: true schema: type: string maxLength: 63 pattern: '^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$' description: DNS-safe function name (lowercase letters, numbers, hyphens; cannot start or end with hyphen) example: my-function responses: '200': description: Function resolved successfully content: application/json: schema: $ref: '#/components/schemas/ResolveFunctionResponse' '400': description: Bad request - missing or invalid function name content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - CORS blocked or missing `functions.invoke` permission for anon key content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Function not found (or private function with anon key) content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/logs/activity: post: tags: - Logs summary: Get project log activity description: | Retrieve bucketed log counts for one resource type in the project. Set `resource.type` to `function`, `frontend`, or `database`. Add `resource.ids` to filter to one or more resources, and add `resource.deployments.ids` to count deployment logs instead of runtime logs for functions and frontends. Deployment logs are not supported for databases. Database logs are a PRO-plan feature; `resource.type=database` from a FREE-plan project owner returns 403. The activity window is limited to the plan's retention window (FREE: 1 day, PRO: 30 days); older start times are clamped to that window. operationId: getProjectLogActivity security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LogActivityRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/LogActivityResponse' '400': description: Bad request - invalid query parameter content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or resource not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/logs/search: post: tags: - Logs summary: Search project logs description: | Search or filter logs for one resource type in the project. Set `resource.type` to `function`, `frontend`, or `database`. Add `resource.ids` to filter to one or more resources, and add `resource.deployments.ids` to read deployment logs instead of runtime logs for functions and frontends. Deployment logs are not supported for databases. Database logs are a PRO-plan feature; requests for `resource.type=database` from a FREE-plan project owner return 403. Log history (runtime and deployment) is limited to the plan's retention window (FREE: 1 day, PRO: 30 days); older time ranges are clamped to that window. operationId: searchProjectLogs security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LogSearchRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/LogSearchResponse' '400': description: Bad request - invalid query parameter content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or resource not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/logs/stream: post: tags: - Logs summary: Stream project logs description: | Live-tail project logs as Server-Sent Events. The request body uses the resource selector plus `q`, `start_time`, and `limit`, including runtime logs and function/frontend deployment logs selected with `resource.deployments`. Deployment logs are not supported for databases. Database logs are a PRO-plan feature; `resource.type=database` from a FREE-plan project owner returns 403. The `q` field uses the same syntax as search and activity requests. Do not send `cursor` or `end_time`; use `/logs/search` for range backfills. Explicit historical `start_time` values are limited to the plan's retention window (FREE: 1 day, PRO: 30 days). Resume with `Last-Event-ID` or the `last_event_id` query parameter. The cursor is bound to the request body: the resource selector and every filter must match the original request when reconnecting, otherwise the request is rejected with `400`. This is a live tail, not a gap-free backfill. On connect or reconnect the server delivers at most `limit` of the most recent matching events from the cursor position and then follows new events; events older than that window are not replayed. Use `/logs/search` to backfill a time range. operationId: streamProjectLogs security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: Last-Event-ID in: header required: false schema: type: string description: Opaque stream cursor from the most recent SSE `id` field. - name: last_event_id in: query required: false schema: type: string description: Opaque stream cursor fallback when setting `Last-Event-ID` is not practical. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LogStreamRequest' responses: '200': description: Server-Sent Events stream. `log` events contain a JSON `LogSearchEvent`; `warning` events contain a JSON object with an `error` field. content: text/event-stream: schema: type: string examples: log: summary: Log event value: | : connected id: STREAM_CURSOR event: log data: {"id":"LOG_EVENT_ID","timestamp":"2024-01-01T12:00:00Z","level":"info","message":"User logged in","resource":{"type":"function","id":"550e8400-e29b-41d4-a716-446655440000","name":"login"},"region":"us-east-1"} '400': description: Bad request - invalid selector, stream cursor, or unsupported stream field content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or resource not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error - log streaming setup failed content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/functions/batch: post: tags: - Functions summary: Deploy multiple functions in one request description: | Upload multiple function source archives in one multipart request. Each archive should contain source files plus dependency manifests/lockfiles, not installed dependency directories. ZIP and tar.gz uploads are accepted and normalized to tar.gz before storage. The API enforces `SOURCE_ARCHIVE_SIZE_LIMIT_MB` for each uploaded and normalized source archive. The server records a shared deployment batch ID for the resulting function deployments. Each function deployment runs its own compile/publish workflow concurrently, and each publish build enforces `LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB` for the final container image. One batch request can include up to 100 functions. Submit multiple batch requests for larger projects. If one function fails before its workflow starts, already-started function deployments are left running and the failed function is reported in the `failed` array. Failed new functions are deleted; failed updates are rolled back to their previous metadata/status where possible. operationId: createFunctionsBatch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: multipart/form-data: schema: type: object properties: functions: type: string description: JSON array of functions with `name`, `runtime`, optional `handler`, and `file_field`. Each `file_field` must name a multipart file field containing that function's ZIP or tar.gz source bundle. code_0: type: string format: binary description: Function ZIP or tar.gz archive referenced by the first manifest entry's `file_field`; additional code_N file fields may be included. Each archive is subject to SOURCE_ARCHIVE_SIZE_LIMIT_MB. required: - functions responses: '202': description: Batch deployment accepted content: application/json: schema: $ref: '#/components/schemas/BatchFunctionDeployResponse' '207': description: Batch deployment partially accepted; successful functions started deployment and failed functions were compensated where possible content: application/json: schema: $ref: '#/components/schemas/BatchFunctionDeployResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/schedulers: get: tags: [Functions] summary: List every function scheduler in a project description: | Project-scoped counterpart to `/projects/{id}/functions/{functionId}/schedulers`. Returns schedulers across all functions in the project, ordered by creation time descending, with standard page/limit pagination so clients don't have to fan out one request per function. operationId: listProjectSchedulers security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Project schedulers content: application/json: schema: $ref: '#/components/schemas/FunctionSchedulerListResponse' /projects/{id}/functions/{functionId}/schedulers: get: tags: [Functions] summary: List schedulers for a function operationId: listFunctionSchedulers security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' responses: '200': description: Function schedulers content: application/json: schema: $ref: '#/components/schemas/FunctionSchedulerListResponse' post: tags: [Functions] summary: Create a scheduler for a function description: Creates regional scheduled invocation jobs. Requested regions must be a subset of the function's deployed regions. operationId: createFunctionScheduler security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFunctionSchedulerRequest' responses: '201': description: Scheduler created content: application/json: schema: $ref: '#/components/schemas/FunctionScheduler' '400': description: Invalid schedule or geofenced region content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/functions/{functionId}/schedulers/{schedulerId}: get: tags: [Functions] summary: Get a function scheduler operationId: getFunctionScheduler security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' - $ref: '#/components/parameters/SchedulerId' responses: '200': description: Function scheduler content: application/json: schema: $ref: '#/components/schemas/FunctionScheduler' patch: tags: [Functions] summary: Update a function scheduler operationId: updateFunctionScheduler security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' - $ref: '#/components/parameters/SchedulerId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateFunctionSchedulerRequest' responses: '200': description: Scheduler updated content: application/json: schema: $ref: '#/components/schemas/FunctionScheduler' delete: tags: [Functions] summary: Delete a function scheduler operationId: deleteFunctionScheduler security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' - $ref: '#/components/parameters/SchedulerId' responses: '204': description: Scheduler deleted /projects/{id}/functions/{functionId}/deployments: get: tags: - Functions summary: List function deployments operationId: listFunctionDeployments security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FunctionId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFunctionDeployments' '404': description: Function not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends: get: tags: - Frontends summary: List all frontends in a project description: | Supports two mutually exclusive pagination modes. Offset mode uses `page` and `limit` and returns `next` (URL). Cursor mode uses `cursor` and `limit`, supports `search` (case-insensitive name match), and returns `next_cursor`. Sending both `page` and `cursor` (or `page` and `search`) returns 400. operationId: listFrontends security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFrontends' '400': description: Bad request - invalid project identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Frontends summary: Create a new frontend deployment description: | Creates and deploys a frontend for the project. If a frontend with the same name already exists in the project, this operation updates that frontend using the uploaded archive and starts a new deployment. A deployment that starts immediately returns `status: provisioning`, then transitions to `active`, `degraded`, or `failed`. If another deployment is running, the response preserves the frontend's current status and exposes the queued deployment through `pending_deployment_id`. Existing frontend traffic continues to use an available runtime while the new deployment builds and provisions. Each deployment publishes its own static assets before the runtimes switch to its build, and the live build's assets keep serving until the new deployment is live, so a page loaded mid-deployment resolves its assets whichever build served it. A failed redeploy puts the runtimes back on the build they were running, leaves the frontend `active` on the previous deployment, and records the attempted deployment as failed. `degraded` means the runtime remains available but edge synchronization requires recovery; Volcano retries the edge step without rebuilding. Only one deployment may run for a given frontend, while independent frontends and projects can deploy concurrently. For monorepos, provide `app_root` as a relative path from the uploaded archive root to the Next.js app that should be built. Omit it for single-app archives. Supported frontend environments are Next.js 15.x and 16.x with Node.js 22.x or 24.x. The Node.js runtime is inferred from `package.json` `engines.node`; if omitted, Volcano uses Node.js 22.x. The selected Node.js family must also satisfy the installed Next.js package's `engines.node` constraint. Volcano tests Next 15.5.24 (`^18.18.0 || ^19.8.0 || >=20.0.0`) and Next 16.3.3 (`>=20.9.0`). Source archive size is enforced by the API with `SOURCE_ARCHIVE_SIZE_LIMIT_MB`; the CLI does not apply its own source archive size limit. After the final container images are built, the publish build enforces `LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB` before pushing. This operation is limited by plan-based frontend deployment quotas (`FREE_FRONTEND_DEPLOYMENTS`, `PRO_FRONTEND_DEPLOYMENTS`). Each project can contain up to 10,000 frontends regardless of plan. operationId: createFrontend security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: multipart/form-data: schema: type: object required: - name - archive properties: name: type: string maxLength: 63 pattern: '^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$' description: DNS-safe frontend name framework: type: string enum: [nextjs] default: nextjs description: Next.js frontend. Supported Next.js majors are 15.x and 16.x. app_root: type: string maxLength: 1024 description: Optional relative POSIX path from the uploaded archive root to the Next.js app to build, for example `apps/web`. example: apps/web archive: type: string format: binary description: ZIP or tar.gz archive of the frontend project directory or monorepo workspace root. The API enforces SOURCE_ARCHIVE_SIZE_LIMIT_MB and stores a normalized tar.gz archive. responses: '200': description: Existing frontend updated; its deployment was started or queued content: application/json: schema: $ref: '#/components/schemas/Frontend' '201': description: Frontend created and deployment workflow started content: application/json: schema: $ref: '#/components/schemas/Frontend' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Frontend deployment limit exceeded for the current plan or project hard cap content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict - frontend deletion is queued or running content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service unavailable - frontend workflow or archive limit configuration missing content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends/{frontendId}: get: tags: - Frontends summary: Get frontend details operationId: getFrontend security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Frontend' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Frontends summary: Delete a frontend description: | Schedules asynchronous frontend deletion. If another deployment is running, the frontend preserves its current status and exposes the queued deletion through `pending_deployment_id`. Its status changes to `deleting` when cleanup starts. After cleanup, it returns 404 and no longer appears in frontend lists. operationId: deleteFrontend security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '202': description: Frontend deletion started or queued '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service unavailable - frontend workflow configuration missing content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends/{frontendId}/redeploy: post: tags: - Frontends summary: Redeploy frontend using latest uploaded artifact description: | Starts a new frontend workflow using the latest stored artifact. A deployment that starts immediately returns `status: provisioning`, then transitions to `active`, `degraded`, or `failed`. An overlapping deployment preserves the frontend's current status, is exposed through `pending_deployment_id`, and supersedes any older queued deployment. The previous runtime and its published static assets remain available during provisioning, and a failed redeploy restores the regional runtimes to that build and keeps it serving while the attempted deployment is recorded as failed. operationId: redeployFrontend security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '200': description: Frontend redeploy started or queued content: application/json: schema: $ref: '#/components/schemas/Frontend' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict - frontend deletion is queued or running content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service unavailable - frontend workflow configuration missing content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends/{frontendId}/domain: get: tags: - Frontends summary: Get frontend custom domain status operationId: getFrontendCustomDomain security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '200': description: | Frontend custom domain status, or null when the frontend has no custom domain configured (the common empty state). content: application/json: schema: nullable: true allOf: - $ref: '#/components/schemas/FrontendCustomDomainResponse' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Frontends summary: Configure frontend custom domain (PRO) description: | Configures one custom domain for a frontend. The default Volcano-generated frontend URL remains active. Wildcard Volcano frontend TLS remains valid and isolated from custom-domain certificate changes. operationId: createFrontendCustomDomain security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFrontendCustomDomainRequest' responses: '201': description: Custom domain provisioning started content: application/json: schema: $ref: '#/components/schemas/FrontendCustomDomainResponse' '200': description: Custom domain already configured with same hostname content: application/json: schema: $ref: '#/components/schemas/FrontendCustomDomainResponse' '400': description: Bad request - invalid domain content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - custom domains require PRO plan content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict - custom domain already in use or frontend already has a custom domain content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service unavailable - custom domain provisioning is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Frontends summary: Delete frontend custom domain operationId: deleteFrontendCustomDomain security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '204': description: Custom domain detach scheduled '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Frontend or custom domain not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends/{frontendId}/deployments: get: tags: - Frontends summary: List frontend deployments operationId: listFrontendDeployments security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedFrontendDeployments' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/frontends/{frontendId}/usage: get: tags: - Frontends summary: Per-day request and error counts for a single frontend description: | Returns a zero-filled daily series of request counts and 5xx error counts for one frontend, oldest first. Each entry is one UTC day; missing days (no traffic recorded) come back as `requests: 0, errors: 0` so the response always has exactly `days` entries. Backs the Monitoring section on the Frontend detail page in volcano-web. `days` defaults to 30 and is capped at 90 to keep the (frontend_id, day) index scan bounded. operationId: getFrontendUsageHistory security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' - name: days in: query description: Number of trailing days to return (1–90, default 30). required: false schema: type: integer minimum: 1 maximum: 90 default: 30 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/FrontendUsageHistoryResponse' '400': description: Bad request - invalid identifier content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - project ownership required content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Frontend not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/variables: get: tags: - Variables summary: List all variables for a project description: | Returns project-level environment variables used by deployed functions and frontends. operationId: listVariables security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedVariables' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Variables summary: Create or update a variable description: | Creates a project-level environment variable and triggers asynchronous propagation to deployed functions and frontends in the project's configured regions. operationId: createVariable security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVariableRequest' responses: '201': description: Variable created content: application/json: schema: $ref: '#/components/schemas/Variable' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases: get: tags: - Databases summary: List all databases for a project description: | Supports two mutually exclusive pagination modes. Offset mode uses `page` and `limit`. Cursor mode uses `cursor` and `limit`, supports `search` (case-insensitive name match), and returns `next_cursor`/`prev_cursor`. The optional `status` filter applies in both modes and is bound to the cursor. Sending both `page` and `cursor` (or `page` and `search`) returns 400. operationId: listDatabases security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedDatabases' post: tags: - Databases summary: Create a new serverless PostgreSQL database description: | Creates a serverless PostgreSQL database in the project. Each project can contain up to 100 databases. Requests over this cap return 403. operationId: createDatabase security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDatabaseRequest' responses: '201': description: Database created (provisioning) content: application/json: schema: $ref: '#/components/schemas/Database' '403': description: Database limit exceeded for the project content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}: get: tags: - Databases summary: Get database details operationId: getDatabase security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Database' delete: tags: - Databases summary: Delete a database description: | Deletes a database and the instance backing it. When the instance is removed synchronously the database row is deleted and the response is `204`. If the instance cannot be deleted right away, the database row is retained (status `deleting`) and its teardown is handed to the background reconciler, which retries the deletion and removes the row once the instance is gone; in that case the response is `202`. The database row is never dropped while its instance still exists, so an instance is never orphaned without a record to retry from. operationId: deleteDatabase security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' responses: '204': description: Database deleted (backing instance removed synchronously) '202': description: | Deletion accepted and in progress. The backing instance could not be removed synchronously, so the database is marked `deleting` and torn down asynchronously by the reconciler. content: application/json: schema: type: object properties: status: type: string example: deleting message: type: string example: database deletion in progress /projects/{id}/databases/{databaseName}/branches: get: tags: - Database Branches summary: List a database's branches description: | Returns every branch of the database, including those still provisioning and those that failed, since each still holds a name. Connection strings are omitted. Fetch a single branch to get its connection string. operationId: listDatabaseBranches security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DatabaseBranchList' '404': description: Project or database not found content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' post: tags: - Database Branches summary: Create a branch of a database description: | Forks the database into a new branch. The branch starts as an exact copy of the parent's data and diverges from there. Provisioning is asynchronous: the response is `202` with the branch in `provisioning` and no connection string. Poll the branch until it reports `active`, at which point it carries its own connection string. Retrying a create with a name that already exists returns `409` rather than a second branch, so a retried request cannot silently consume two slots of the branch allowance. operationId: createDatabaseBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDatabaseBranchRequest' responses: '202': description: Branch accepted and provisioning content: application/json: schema: $ref: '#/components/schemas/DatabaseBranch' '400': description: Invalid branch name or lifetime content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | The database has reached its branch allowance, or the owner's plan does not include branching. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or database not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: | A branch of that name already exists on this database, or the database cannot be branched right now because it is still provisioning, failed, or being deleted. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}/branches/{branchName}: get: tags: - Database Branches summary: Get a branch description: | Returns the branch, including its connection string once it is `active`. Poll this after creating a branch to learn when it is connectable. operationId: getDatabaseBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DatabaseBranch' '404': description: Project, database, or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' patch: tags: - Database Branches summary: Extend a branch's lifetime description: | Replaces the branch's lifetime and restarts the countdown from now, so a branch you are still working on is not swept mid-session. The new duration is remembered, so a later reset re-arms the same lifetime. operationId: updateDatabaseBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDatabaseBranchRequest' responses: '200': description: Lifetime updated content: application/json: schema: $ref: '#/components/schemas/DatabaseBranch' '400': description: Requested lifetime is outside the allowed range content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project, database, or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The branch is being deleted content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Database Branches summary: Delete a branch description: | Marks the branch for teardown and returns immediately. The branch stops accepting connections at once; its fork and its row are removed by a background job, so a provider outage cannot leave the call hanging or the branch half-deleted. Deleting a branch that is still provisioning is allowed and stops the build, and repeating the call while teardown is in progress is accepted again. Once the branch is gone the call returns `404`. operationId: deleteDatabaseBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' responses: '202': description: Deletion accepted and in progress content: application/json: schema: type: object properties: status: type: string example: deleting message: type: string example: branch deletion in progress required: - status - message '404': description: Project, database, or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}/branches/{branchName}/reset: post: tags: - Database Branches summary: Reset a branch to its parent's current state description: | Discards everything written on the branch and re-forks it from the parent as it is now. Returns immediately with the branch in `provisioning`. The rewind runs in the background; poll the branch until it reports `active` before connecting again. The branch keeps its name and its connection string, so anything holding that string keeps working once it is active again, and its lifetime is re-armed to the duration it was created with. The branch does not serve connections for the duration of the reset. operationId: resetDatabaseBranch security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' responses: '202': description: Branch reset accepted; the branch is provisioning content: application/json: schema: $ref: '#/components/schemas/DatabaseBranch' '404': description: Project, database, or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: | The branch is not active, or a reset is already in progress. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}/branches/{branchName}/reset-password: post: tags: - Database Branches summary: Rotate a branch's password description: | Issues a new password for the branch and invalidates the previous connection string. Existing connections are not interrupted; new ones must use the returned string. The parent database's credentials are untouched. operationId: resetDatabaseBranchPassword security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' responses: '200': description: Password rotated content: application/json: schema: $ref: '#/components/schemas/DatabaseBranch' '404': description: Project, database, or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The branch is not active content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Branching is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/databases/{databaseName}/reset-password: post: tags: - Databases summary: Reset database password description: | Rotates the Volcano-managed PostgreSQL password used by clients when connecting through pgproxy. This does not rotate or expose the internal owner password. The returned password and connection string are the only client credentials that will authenticate through pgproxy after reset. operationId: resetDatabasePassword security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' responses: '200': description: Password reset successful content: application/json: schema: type: object properties: message: type: string role_name: type: string description: Volcano-managed per-database client login (also the pgproxy routing username) example: volcano_client_11111111-1111-1111-1111-111111111111 new_password: type: string description: New Volcano-managed client password. Always starts with `vpg_`. connection_string: type: string description: Updated pgproxy connection string using Volcano-managed credentials. /projects/{id}/databases/{databaseName}/type: patch: tags: - Databases summary: Update database size description: | Change the size tier of a database. This may briefly interrupt active connections. **Available sizes:** - `volcano-db-xs`: Up to ~1GB RAM - Development, small apps - `volcano-db-s`: Up to ~4GB RAM - Production-ready, light traffic - `volcano-db-m`: Up to ~8GB RAM - Medium traffic applications - `volcano-db-l`: Up to ~16GB RAM - High traffic, larger datasets - `volcano-db-xl`: Up to ~32GB RAM - Heavy workloads - `volcano-db-2xl`: Up to ~64GB RAM - Enterprise-scale operationId: updateDatabaseType security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDatabaseTypeRequest' responses: '200': description: Database type updated content: application/json: schema: $ref: '#/components/schemas/Database' '400': description: Invalid database type '404': description: Database not found /projects/{id}/databases/{databaseName}/stats: get: tags: - Databases summary: Get database consumption metrics description: | Retrieve consumption metrics including storage, compute time, and data transfer. Metrics are aggregated at the project level. Defaults to last 24 hours. **Note:** Advanced metrics require an upgraded plan. operationId: getDatabaseStats security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' - name: from in: query required: false schema: type: string format: date-time description: Start time in RFC3339 format (e.g., "2024-01-01T00:00:00Z"). Defaults to 24 hours ago. - name: to in: query required: false schema: type: string format: date-time description: End time in RFC3339 format (e.g., "2024-01-02T00:00:00Z"). Defaults to now. - name: granularity in: query required: false schema: type: string enum: [hourly, daily, monthly] default: hourly description: Level of detail for metrics aggregation responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DatabaseStats' '400': description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Database metrics not available or requires upgraded plan content: application/json: schema: $ref: '#/components/schemas/Error' /databases/{databaseName}/query/ping: post: tags: - Database Queries summary: Database connectivity probe (REST API) description: | Connectivity probe that runs a fixed `SELECT 1` through pgproxy, using the same authentication, status/bandwidth gating, and metering as the other `/query/*` endpoints. Unlike those endpoints, ping takes **no request body** and performs **no table-name validation**, so it works on any database — including a freshly provisioned, empty one. It is a real committed round-trip through pgproxy, so a `200` means the database is reachable and queryable. Used by the dashboard's database connection test. operationId: queryDatabasePing security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' responses: '200': description: Database is reachable content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - "?column?": 1 count: 1 '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/query/select: post: tags: - Database Queries summary: Query database with SELECT (REST API) description: | Query your database using a simple REST API - no SQL required! **Authentication:** Requires auth user access token (from signup/signin) **Row-Level Security:** Automatically enforced - you see only data you have access to **Use Cases:** - Query from browser/mobile apps - Simple data retrieval - Filtered searches with sorting and pagination **Note:** For complex queries (JOINs, CTEs), use functions with direct SQL operationId: queryDatabaseSelect security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseSelectRequest' responses: '200': description: Query successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "uuid-123" title: "My Post" content: "Post content" status: "published" views: 150 created_at: "2026-01-13T10:00:00Z" count: 1 '400': description: Invalid query content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/query/insert: post: tags: - Database Queries summary: Insert data into database (REST API) description: | Insert new rows into your database using REST API. **Authentication:** Requires auth user access token **Auto-set user_id:** If your table has a trigger using `auth.uid()`, user_id will be automatically set to the authenticated user **Security:** Row-Level Security policies are enforced operationId: queryDatabaseInsert security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseInsertRequest' responses: '200': description: Insert successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "uuid-123" title: "My New Post" content: "This is the content" status: "draft" user_id: "user-uuid" created_at: "2026-01-13T10:00:00Z" count: 1 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/query/update: post: tags: - Database Queries summary: Update data in database (REST API) description: | Update existing rows in your database using REST API. **Security:** Row-Level Security ensures you can only update data you have access to **Safety:** Requires at least one filter to prevent accidental mass updates. A request with no `filters` is rejected with `400` (mirrors delete). This matters for service-key queries, which run with full access and bypass RLS. **Note:** If RLS blocks the update, an empty result is returned (not an error) operationId: queryDatabaseUpdate security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseUpdateRequest' responses: '200': description: Update successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "post-uuid" title: "Updated Title" status: "published" updated_at: "2026-01-13T10:05:00Z" count: 1 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/query/delete: post: tags: - Database Queries summary: Delete data from database (REST API) description: | Delete rows from your database using REST API. **Safety:** Requires at least one filter to prevent accidental mass deletions **Security:** Row-Level Security ensures you can only delete data you have access to **Note:** If RLS blocks the delete, an empty result is returned (not an error) operationId: queryDatabaseDelete security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseDeleteRequest' responses: '200': description: Delete successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "post-uuid" title: "Deleted Post" count: 1 '400': description: Invalid request or missing filters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/branches/{branchName}/query/ping: post: tags: - Database Queries summary: Database connectivity probe (REST API) description: | Connectivity probe that runs a fixed `SELECT 1` through pgproxy, using the same authentication, status/bandwidth gating, and metering as the other `/query/*` endpoints. Unlike those endpoints, ping takes **no request body** and performs **no table-name validation**, so it works on any database — including a freshly provisioned, empty one. It is a real committed round-trip through pgproxy, so a `200` means the database is reachable and queryable. Used by the dashboard's database connection test. **Branch-targeted.** Runs against the named branch instead of the parent database, using the branch's own credentials. The branch must be `active` and unexpired. Nothing about this request can reach the parent's data. operationId: queryDatabaseBranchPing security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' responses: '200': description: Database is reachable content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - "?column?": 1 count: 1 '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/branches/{branchName}/query/select: post: tags: - Database Queries summary: Query database with SELECT (REST API) description: | Query your database using a simple REST API - no SQL required! **Authentication:** Requires auth user access token (from signup/signin) **Row-Level Security:** Automatically enforced - you see only data you have access to **Use Cases:** - Query from browser/mobile apps - Simple data retrieval - Filtered searches with sorting and pagination **Note:** For complex queries (JOINs, CTEs), use Lambda functions with direct SQL **Branch-targeted.** Runs against the named branch instead of the parent database, using the branch's own credentials. The branch must be `active` and unexpired. Nothing about this request can reach the parent's data. operationId: queryDatabaseBranchSelect security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseSelectRequest' responses: '200': description: Query successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "uuid-123" title: "My Post" content: "Post content" status: "published" views: 150 created_at: "2026-01-13T10:00:00Z" count: 1 '400': description: Invalid query content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/branches/{branchName}/query/insert: post: tags: - Database Queries summary: Insert data into database (REST API) description: | Insert new rows into your database using REST API. **Authentication:** Requires auth user access token **Auto-set user_id:** If your table has a trigger using `auth.uid()`, user_id will be automatically set to the authenticated user **Security:** Row-Level Security policies are enforced **Branch-targeted.** Runs against the named branch instead of the parent database, using the branch's own credentials. The branch must be `active` and unexpired. Nothing about this request can reach the parent's data. operationId: queryDatabaseBranchInsert security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseInsertRequest' responses: '200': description: Insert successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "uuid-123" title: "My New Post" content: "This is the content" status: "draft" user_id: "user-uuid" created_at: "2026-01-13T10:00:00Z" count: 1 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/branches/{branchName}/query/update: post: tags: - Database Queries summary: Update data in database (REST API) description: | Update existing rows in your database using REST API. **Security:** Row-Level Security ensures you can only update data you have access to **Safety:** Requires at least one filter to prevent accidental mass updates. A request with no `filters` is rejected with `400` (mirrors delete). This matters for service-key queries, which run with full access and bypass RLS. **Note:** If RLS blocks the update, an empty result is returned (not an error) **Branch-targeted.** Runs against the named branch instead of the parent database, using the branch's own credentials. The branch must be `active` and unexpired. Nothing about this request can reach the parent's data. operationId: queryDatabaseBranchUpdate security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseUpdateRequest' responses: '200': description: Update successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "post-uuid" title: "Updated Title" status: "published" updated_at: "2026-01-13T10:05:00Z" count: 1 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/{databaseName}/branches/{branchName}/query/delete: post: tags: - Database Queries summary: Delete data from database (REST API) description: | Delete rows from your database using REST API. **Safety:** Requires at least one filter to prevent accidental mass deletions **Security:** Row-Level Security ensures you can only delete data you have access to **Note:** If RLS blocks the delete, an empty result is returned (not an error) **Branch-targeted.** Runs against the named branch instead of the parent database, using the branch's own credentials. The branch must be `active` and unexpired. Nothing about this request can reach the parent's data. operationId: queryDatabaseBranchDelete security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' - $ref: '#/components/parameters/BranchName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatabaseDeleteRequest' responses: '200': description: Delete successful content: application/json: schema: $ref: '#/components/schemas/DatabaseQueryResult' example: data: - id: "post-uuid" title: "Deleted Post" count: 1 '400': description: Invalid request or missing filters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Database or branch not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/DatabaseQueryCapExceeded' /databases/regions: get: tags: - Databases summary: List platform-supported regions for database provisioning operationId: listDatabaseRegions description: | Returns the regions enabled for database provisioning in this platform environment. This is a public endpoint that doesn't require authentication. responses: '200': description: List of platform-supported regions content: application/json: schema: type: array items: type: object properties: id: type: string example: "aws-us-east-1" description: Region identifier for API usage name: type: string example: "AWS US East 1 (N. Virginia)" description: Human-readable region name /databases/postgres-versions: get: tags: - Databases summary: List available PostgreSQL versions operationId: listPostgresVersions description: | Returns a list of supported PostgreSQL major versions for database provisioning. This is a public endpoint that doesn't require authentication. responses: '200': description: List of available PostgreSQL versions content: application/json: schema: type: array items: type: object properties: version: type: string example: "16" description: PostgreSQL major version number name: type: string example: "PostgreSQL 16" description: Human-readable version name default: type: boolean description: Whether this is the default version (recommended) deprecated: type: boolean description: Whether this version is deprecated (approaching EOL) /functions/runtimes: get: tags: - Functions summary: List supported function runtimes operationId: listFunctionRuntimes security: [] description: | Returns the public function runtime catalog used by CLI clients to select supported runtimes, language defaults, and local source packaging metadata for deployments. This is a public endpoint that doesn't require authentication. responses: '200': description: Supported function runtimes content: application/json: schema: $ref: '#/components/schemas/FunctionRuntimesResponse' /functions/regions: get: tags: - Functions summary: List available regions for function deployment operationId: listFunctionRegions security: [] description: | Returns the configured regions where functions can be deployed, each annotated with a human-readable label and country flag emoji for use in UI pickers. This is a public endpoint that doesn't require authentication. responses: '200': description: Available function deployment regions content: application/json: schema: type: array items: $ref: '#/components/schemas/FunctionRegion' /projects/{id}/variables/{name}: get: tags: - Variables summary: Get variable by name description: | Returns a project-level environment variable used by deployed functions and frontends. operationId: getVariable security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VariableName' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Variable' '404': description: Variable not found content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Variables summary: Update a variable description: | Updates a project-level environment variable and triggers asynchronous propagation to deployed functions and frontends in the project's configured regions. operationId: updateVariable security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VariableName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVariableRequest' responses: '200': description: Variable updated content: application/json: schema: $ref: '#/components/schemas/Variable' '404': description: Variable not found content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Variables summary: Delete a variable description: | Deletes a project-level environment variable and triggers asynchronous propagation of the removal to deployed functions and frontends in the project's configured regions. operationId: deleteVariable security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/VariableName' responses: '204': description: Variable deleted '404': description: Variable not found content: application/json: schema: $ref: '#/components/schemas/Error' # Authentication Endpoints /auth/password-policy: get: tags: - Authentication summary: Get the effective password policy description: | Returns the backend-enforced password bounds and compromised-password screening status for the project identified by the anon key. A valid anon key is required, but no route-specific auth permission is needed. operationId: authGetPasswordPolicy security: - AnonKey: [] responses: '200': description: Effective password policy content: application/json: schema: $ref: '#/components/schemas/AuthPasswordPolicy' '401': description: Invalid, missing, or revoked anon key content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project or auth configuration not found content: application/json: schema: $ref: '#/components/schemas/Error' /auth/signup: post: tags: - Authentication summary: Sign up a new auth user description: | Create a new end-user account. The project is determined from the anon key. Requires project-specific anon key in Authorization header. **Session-less**: signup never issues a session. On success it returns a uniform acknowledgement (`AuthSignupResponse`) with no tokens; the client obtains a session with a subsequent `POST /auth/signin`. If email confirmation is enabled for the project, a confirmation email is sent and `confirmation_required` is `true`. **Anti-enumeration**: a signup for an already-registered email returns the exact same `201` response as a fresh signup — it never returns `409` — so the response cannot be used to discover which emails are registered. operationId: authSignup security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string description: | Password validated after NFC normalization against the policy returned by GET /auth/password-policy. user_metadata: type: object additionalProperties: true responses: '201': description: | Signup acknowledged (session-less). Returned identically for a new account and for an already-registered email (anti-enumeration). content: application/json: schema: $ref: '#/components/schemas/AuthSignupResponse' '400': description: Invalid input (bad email/password format) '401': description: | Unauthorized - Invalid, tampered, revoked, or wrong-project anon key '403': description: | Forbidden - Signups disabled, anon key lacks signup permission, or the email domain is not in `allowed_email_domains`. The internal `anonymous.volcano.internal` domain is reserved for anonymous accounts and is refused whatever the project allows. '429': description: Rate limit exceeded '503': description: Compromised-password screening is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /auth/signin: post: tags: - Authentication summary: Sign in an auth user description: | Authenticate with email and password. Requires an anon key. Set `session_mode` to `cookie` to request HttpOnly refresh-token storage. Cookie mode is honored only for an exact, credentialed CORS origin on the same schemeful site as this API. Otherwise the response retains the refresh token in its body. operationId: authSignin security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string password: type: string session_mode: type: string enum: [cookie] responses: '200': description: Signin successful content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '400': description: Invalid input (missing email/password) '401': description: "Unauthorized - Invalid credentials, invalid/tampered/revoked anon key,\nor account banned/deleted\n" '403': description: | Forbidden - Anon key lacks signin permission, or the email domain is not in `allowed_email_domains` while `allowed_email_domains_mode` is `signup_and_signin`. The domain is taken from the account's canonical email (its primary identity), which is not necessarily the address in the request. '429': description: Rate limit exceeded /auth/refresh: post: tags: - Authentication summary: Refresh access token description: | Get a new access token using a refresh token. Requires an anon key. Send `refresh_token` in the body for the default flow. An eligible cookie-mode browser request may instead send `session_mode: cookie` with an empty token or omit the request body; the API reads and resets the project's HttpOnly cookie and omits `refresh_token` from the response. operationId: authRefresh security: - AnonKey: [] requestBody: required: false content: application/json: schema: type: object properties: refresh_token: type: string session_mode: type: string enum: [cookie] responses: '200': description: Token refreshed content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '401': description: Invalid or expired refresh token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | The account's email domain is not in `allowed_email_domains` while `allowed_email_domains_mode` is `signup_and_signin`, so the session cannot be extended content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' /auth/logout: post: tags: - Authentication summary: Logout (revoke refresh token) description: | Invalidate a refresh token. Requires an anon key. Send `refresh_token` for the default flow. An eligible cookie-mode browser request may instead send `session_mode: cookie` with an empty token; logout remains idempotent when the cookie is missing or expired. operationId: authLogout security: - AnonKey: [] requestBody: required: false content: application/json: schema: type: object properties: refresh_token: type: string session_mode: type: string enum: [cookie] responses: '204': description: Logged out successfully /auth/forgot-password: post: tags: - Authentication summary: Request password reset description: | Generates recovery token and stores it (email sending pending). Returns generic message to prevent email enumeration. Project is identified via the anon key. operationId: authForgotPassword security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email responses: '200': description: Generic success message (doesn't reveal if email exists) content: application/json: schema: type: object properties: message: type: string example: "If the email exists, a password reset link has been sent" '403': description: Password reset is disabled for this project content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded (10 requests per hour per IP) content: application/json: schema: $ref: '#/components/schemas/Error' /auth/reset-password: post: tags: - Authentication summary: Reset password with recovery token description: | Reset password using recovery token from forgot-password. Revokes all existing sessions for security. operationId: authResetPassword security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - token - new_password properties: token: type: string description: Recovery token from forgot-password new_password: type: string description: | Password validated after NFC normalization against the policy returned by GET /auth/password-policy. responses: '200': description: Password reset successful content: application/json: schema: type: object properties: message: type: string '401': description: Invalid or expired token '400': description: Password doesn't meet requirements '503': description: Compromised-password screening is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /auth/confirm: post: tags: - Authentication summary: Confirm email address description: | Confirm email address using token sent via email. Required if require_email_confirmation is enabled. operationId: authConfirmEmail security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - token properties: token: type: string description: Confirmation token from email responses: '200': description: Email confirmed or already confirmed content: application/json: schema: type: object properties: message: type: string enum: - Email confirmed successfully - Email already confirmed examples: confirmed: summary: Fresh confirmation value: message: Email confirmed successfully alreadyConfirmed: summary: Token belongs to already-confirmed user value: message: Email already confirmed '401': description: Invalid or expired token '400': description: Missing confirmation token in request body /auth/resend-confirmation: post: tags: - Authentication summary: Resend confirmation email description: | Resend email confirmation link. Returns generic message to prevent email enumeration. No email is sent when the account does not exist or is already confirmed. If the account exists and is unconfirmed, a new token is generated and any previous confirmation token is invalidated. operationId: authResendConfirmation security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email responses: '200': description: Generic success message content: application/json: schema: type: object properties: message: type: string '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' /auth/signup-anonymous: post: tags: - Authentication summary: Create anonymous user description: | Create guest user without email/password. User metadata (like display_name) can be included and will appear in realtime presence events. Requires enable_anonymous_signins to be true. operationId: authSignupAnonymous security: - AnonKey: [] requestBody: description: Optional user metadata content: application/json: schema: type: object properties: user_metadata: type: object additionalProperties: true description: Custom user metadata (e.g., display_name, avatar_url) example: display_name: "Alice" avatar_url: "https://example.com/alice.jpg" responses: '201': description: Anonymous user created content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '403': description: Anonymous signins disabled /auth/user/convert-anonymous: post: tags: - Authentication summary: Convert anonymous user to authenticated description: | Add email and password to anonymous user. Requires auth user access token. If require_email_confirmation is enabled for the project, the converted user remains unconfirmed until /auth/confirm succeeds. When email sending is enabled, a confirmation email is sent during conversion. operationId: authConvertAnonymous security: - AuthUserAccessToken: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string description: | Password validated after NFC normalization against the policy returned by GET /auth/password-policy. user_metadata: type: object additionalProperties: true responses: '200': description: User converted successfully content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/AuthUser' '400': description: Not an anonymous user '403': description: | The chosen email domain is not in `allowed_email_domains` '409': description: Email already in use '503': description: Compromised-password screening is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/change-email: post: tags: - Authentication summary: Request email change description: | Request to change user's email address. Sends confirmation token to new email address. operationId: authRequestEmailChange security: - AuthUserAccessToken: [] requestBody: required: true content: application/json: schema: type: object required: - new_email properties: new_email: type: string format: email responses: '200': description: Confirmation email sent content: application/json: schema: type: object properties: message: type: string new_email: type: string '400': description: Invalid email format or same as current email content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | The requested email domain is not in `allowed_email_domains` content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Email already in use content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded (10 requests per hour per IP) content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/confirm-email-change: post: tags: - Authentication summary: Confirm email change description: Confirm email change with token sent to new address operationId: authConfirmEmailChange security: - AuthUserAccessToken: [] requestBody: required: true content: application/json: schema: type: object required: - email_change_token properties: email_change_token: type: string responses: '200': description: Email changed successfully content: application/json: schema: type: object properties: message: type: string user: $ref: '#/components/schemas/AuthUser' '400': description: Invalid or expired token, or no pending email change content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | The pending email domain is no longer in `allowed_email_domains`. Re-checked here because the allowlist can narrow between the request and the confirmation. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Email is now in use by another user content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/cancel-email-change: delete: tags: - Authentication summary: Cancel pending email change operationId: authCancelEmailChange security: - AuthUserAccessToken: [] responses: '200': description: Email change cancelled content: application/json: schema: type: object properties: message: type: string '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/sessions: get: tags: - Authentication summary: Get current user's sessions description: | Returns paginated sessions for the currently authenticated user. Each session includes device info, IP addresses, and activity timestamps. The current session is marked with `is_current: true`. **Ordering and pagination.** Without `sort`, results are ordered by most recent activity and paged with `page`/`limit`, returning the `sessions`/`total`/`page`/`limit`/`total_pages` body below. This is the legacy default and is preserved for existing clients. Send `sort=created_at` to opt into the standard list contract: results are ordered by session start (newest first) and may be paged either with `page`/`limit` or by cursor with `cursor`/`ending_before` plus a bounded `offset` past the cursor anchor. Cursor responses use the shared `data` envelope with `next_cursor`/`prev_cursor`. Unlike other list endpoints, sending `limit` without `page` does **not** select cursor mode here; `sort=created_at` is the only opt-in. Cursor pagination is rejected with 400 for the activity order, because `last_activity_at` changes whenever a session refreshes its token: a row that crosses the cursor anchor between two requests would be skipped and never shown. The `status=expired` filter is also offset-only because a session can expire above the cursor anchor during a walk. Sending that filter in cursor mode, `page` with `cursor` or `ending_before`, or both cursor directions returns 400. operationId: authGetMySessions security: - AuthUserAccessToken: [] parameters: - name: page in: query description: Page number (1-indexed) schema: type: integer minimum: 1 default: 1 - name: limit in: query description: Number of sessions per page (max 100) schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort in: query description: | Sort key. `last_activity` (default) orders by most recent activity and supports offset pagination only. `created_at` orders by session start and supports both offset and cursor pagination. schema: type: string enum: [last_activity, created_at] default: last_activity - name: status in: query description: | Filter by whether the session can still be refreshed. Omit for every stored session, including expired ones. `expired` is not supported with cursor pagination. schema: type: string enum: [active, expired] - name: cursor in: query description: | Opaque keyset cursor from a previous response's `next_cursor`. Requires `sort=created_at`; mutually exclusive with `page` and `ending_before`. schema: type: string - name: ending_before in: query description: | Opaque keyset cursor from a previous response's `prev_cursor`, paging backward. Requires `sort=created_at`; mutually exclusive with `page` and `cursor`. schema: type: string - name: offset in: query description: | Bounded number of rows to skip past the cursor anchor (the hybrid jump, maximum 100000). Ignored unless `cursor` or `ending_before` is supplied. schema: type: integer minimum: 0 maximum: 100000 responses: '200': description: Paginated list of user sessions content: application/json: schema: type: object properties: sessions: type: array items: $ref: '#/components/schemas/AuthSession' total: type: integer description: Total number of sessions page: type: integer description: Current page number limit: type: integer description: Number of sessions per page total_pages: type: integer description: Total number of pages data: type: array description: Sessions for this page (cursor pagination only) items: $ref: '#/components/schemas/AuthSession' has_more: type: boolean description: Whether a further page exists (cursor pagination only) next_cursor: type: string description: Opaque cursor for the next page (cursor pagination only) prev_cursor: type: string description: Opaque cursor for the previous page (cursor pagination only). Send as `ending_before`. '400': description: Invalid or conflicting pagination parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Authentication summary: Sign out from all other devices description: | Deletes all sessions except the current one. Use this to log out from all other devices while keeping the current session active. operationId: authDeleteAllMySessions security: - AuthUserAccessToken: [] responses: '204': description: All other sessions deleted '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/sessions/{sessionId}: delete: tags: - Authentication summary: Sign out from specific device description: | Deletes a specific session, logging out that device. You can get session IDs from the list sessions endpoint. operationId: authDeleteMySession security: - AuthUserAccessToken: [] parameters: - name: sessionId in: path required: true description: The session ID to delete schema: type: string format: uuid responses: '204': description: Session deleted '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Session not found content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user: get: tags: - Authentication summary: Get current user profile description: Returns authenticated user's profile. Requires access token. operationId: authGetUser security: - AuthUserAccessToken: [] responses: '200': description: User profile content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/AuthUser' '401': description: Not authenticated - access token missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Authentication summary: Update user profile description: Update password or metadata. Requires access token. operationId: authUpdateUser security: - AuthUserAccessToken: [] requestBody: content: application/json: schema: type: object properties: password: type: string description: | Password validated after NFC normalization against the policy returned by GET /auth/password-policy. user_metadata: type: object additionalProperties: true description: | Metadata keys to merge into the current user metadata. Omitted keys remain unchanged; set a key to null to remove it. Merging is shallow; nested objects replace the stored value for that top-level key. responses: '200': description: Profile updated content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/AuthUser' '400': description: Bad request - invalid password or metadata format content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated - access token missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Compromised-password screening is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/identities: get: tags: - Authentication summary: List the current user's identities description: | Returns every real email identity the account owns. An account can own multiple identities (for example a password identity plus one or more OAuth identities on different emails). Anonymous accounts have no real identity and return an empty list. operationId: authListIdentities security: - AuthUserAccessToken: [] responses: '200': description: List of identities content: application/json: schema: $ref: '#/components/schemas/AuthIdentitiesResponse' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/identities/{identityId}: delete: tags: - Authentication summary: Unlink an identity from the current user description: | Removes a non-primary identity and its attached sign-in methods. Refused when the identity is the account's primary, its only identity, or when removing it would leave the account with no way to sign in. operationId: authUnlinkIdentity security: - AuthUserAccessToken: [] parameters: - name: identityId in: path required: true description: The identity ID to unlink schema: type: string format: uuid responses: '204': description: Identity unlinked '400': description: Identity cannot be unlinked (primary, last, or would remove last sign-in method), or the identity id is malformed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Identity not found content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/methods: get: tags: - Authentication summary: List the current user's sign-in methods description: | Returns a flat list of every sign-in method the account owns (password, each OAuth provider, and any active anonymous method), with the primary method flagged. Password stubs and converted anonymous methods are excluded. operationId: authListMethods security: - AuthUserAccessToken: [] responses: '200': description: List of sign-in methods content: application/json: schema: $ref: '#/components/schemas/AuthMethodsResponse' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/user/methods/{methodId}/promote: post: tags: - Authentication summary: Set a method as the account's primary description: | Promotes the given method to the account's primary sign-in method. The account's canonical email is re-derived from the promoted method's identity. Refused for password stubs and converted anonymous methods, and for an identity whose domain is outside the project's `allowed_email_domains`. operationId: authPromoteMethod security: - AuthUserAccessToken: [] parameters: - name: methodId in: path required: true description: The method ID to promote schema: type: string format: uuid responses: '200': description: The promoted method content: application/json: schema: $ref: '#/components/schemas/AuthMethodSummary' '400': description: This method cannot be set as primary (password stub, converted anonymous method, or unverified email), or the method id is malformed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The promoted identity's email domain is not in the project's allowed_email_domains content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Method not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/insights: get: tags: - Auth Admin summary: Get auth user insights description: | Returns current auth-user totals, rolling 30-day active users, and zero-filled signup and successful sign-in counts for an inclusive UTC date range. Weeks start on Monday. Sign-in counts and active-user activity begin when collection is deployed. Historical signup counts are backfilled from users present at deployment. Token refreshes affect active users but not the sign-in series. operationId: getAuthInsights security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: from in: query description: Inclusive UTC start date. Defaults to 29 days before `to`. schema: type: string format: date - name: to in: query description: Inclusive UTC end date. Defaults to today. schema: type: string format: date - name: interval in: query description: Chart bucket size. Defaults to `day`. schema: $ref: '#/components/schemas/AuthInsightsInterval' responses: '200': description: Auth insights retrieved content: application/json: schema: $ref: '#/components/schemas/AuthInsightsResponse' example: project_id: 4f165080-a931-4e03-b3bd-41c45c3f0058 observed_at: '2026-07-20T18:00:00Z' window: from: '2026-06-21' to: '2026-07-20' interval: day summary: total_users: 1234 active_users_30d: 418 series: - bucket_start: '2026-07-20' signups: 12 signins: 97 is_partial: true '400': description: Invalid date range or interval content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - invalid or missing token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/users: get: tags: - Auth Admin summary: List all auth users (admin) description: List auth users in project. Requires platform token. operationId: listAuthUsers security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' - name: status in: query required: false description: >- Filter by effective status. `banned` returns only currently-banned users; an expired temporary ban lists as `active`. schema: type: string enum: [active, banned] responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedAuthUsers' '400': description: Invalid status or pagination parameters content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/users/{userId}: get: tags: - Auth Admin summary: Get specific auth user (admin) operationId: getAuthUser security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: Auth user details content: application/json: schema: $ref: '#/components/schemas/AuthUser' delete: tags: - Auth Admin summary: Delete auth user (admin) description: Soft-deletes user and revokes all sessions operationId: deleteAuthUser security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid responses: '204': description: User deleted /projects/{id}/auth/users/{userId}/sessions: get: tags: - Auth Admin summary: List user sessions description: | List paginated sessions for a specific auth user. Returns session details including device info, IP address, and activity timestamps. Ordering and pagination match `GET /auth/user/sessions`: the default is activity order with `page`/`limit` and the legacy `sessions` body, and `sort=created_at` opts into the standard cursor/offset hybrid with the shared `data` envelope. Cursor pagination is only available for `sort=created_at`, because the activity timestamp changes under paging. The `status=expired` filter is offset-only because sessions can expire above a cursor anchor during a walk. operationId: listUserSessions security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid - name: page in: query description: Page number (1-indexed) schema: type: integer minimum: 1 default: 1 - name: limit in: query description: Number of sessions per page (max 100) schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort in: query description: | Sort key. `last_activity` (default) orders by most recent activity and supports offset pagination only. `created_at` orders by session start and supports both offset and cursor pagination. schema: type: string enum: [last_activity, created_at] default: last_activity - name: status in: query description: | Filter by whether the session can still be refreshed. Omit for every stored session, including expired ones. `expired` is not supported with cursor pagination. schema: type: string enum: [active, expired] - name: cursor in: query description: | Opaque keyset cursor from a previous response's `next_cursor`. Requires `sort=created_at`; mutually exclusive with `page` and `ending_before`. schema: type: string - name: ending_before in: query description: | Opaque keyset cursor from a previous response's `prev_cursor`, paging backward. Requires `sort=created_at`; mutually exclusive with `page` and `cursor`. schema: type: string - name: offset in: query description: | Bounded number of rows to skip past the cursor anchor (the hybrid jump, maximum 100000). Ignored unless `cursor` or `ending_before` is supplied. schema: type: integer minimum: 0 maximum: 100000 responses: '200': description: Paginated list of user sessions content: application/json: schema: type: object properties: sessions: type: array items: $ref: '#/components/schemas/AuthSession' total: type: integer description: Total number of sessions page: type: integer description: Current page number limit: type: integer description: Number of sessions per page total_pages: type: integer description: Total number of pages data: type: array description: Sessions for this page (cursor pagination only) items: $ref: '#/components/schemas/AuthSession' has_more: type: boolean description: Whether a further page exists (cursor pagination only) next_cursor: type: string description: Opaque cursor for the next page (cursor pagination only) prev_cursor: type: string description: Opaque cursor for the previous page (cursor pagination only). Send as `ending_before`. '400': description: Invalid or conflicting pagination parameters content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: User not found delete: tags: - Auth Admin summary: Delete all user sessions description: | Revokes all sessions for a user, forcing them to re-authenticate on all devices. Use this to log out a user from everywhere. operationId: deleteAllUserSessions security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid responses: '204': description: All sessions deleted '404': description: User not found /projects/{id}/auth/users/{userId}/sessions/{sessionId}: delete: tags: - Auth Admin summary: Delete specific session description: | Revokes a specific session for a user. Use this to log out a user from a single device. operationId: deleteUserSession security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid - name: sessionId in: path required: true schema: type: string format: uuid responses: '204': description: Session deleted '404': description: Session or user not found /projects/{id}/auth/users/{userId}/ban: post: tags: - Auth Admin summary: Ban a user description: | Bans a user temporarily or permanently. Banned users cannot sign in and all their active sessions are immediately revoked. - Omit `banned_until` for a permanent ban - Provide `banned_until` ISO timestamp for a temporary ban operationId: banAuthUser security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: banned_until: type: string format: date-time description: When the ban expires (omit for permanent ban) example: "2026-12-31T23:59:59Z" responses: '200': description: User banned successfully content: application/json: schema: $ref: '#/components/schemas/BanUserResponse' '404': description: User not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/users/{userId}/unban: post: tags: - Auth Admin summary: Unban a user description: | Removes a ban from a user, restoring their ability to sign in. The user's status is set back to 'active'. operationId: unbanAuthUser security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: User unbanned successfully content: application/json: schema: $ref: '#/components/schemas/UnbanUserResponse' '404': description: User not found content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/email-templates: get: tags: - Auth Configuration summary: List email templates description: Returns all custom email templates for this project. operationId: listEmailTemplates security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Email templates list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/EmailTemplate' post: tags: - Auth Configuration summary: Create email template description: | Creates a custom email template for the project. Custom email templates are a PRO-plan feature: requests from a FREE-plan project owner are rejected with 403, and FREE projects always send the built-in default templates regardless of any previously saved custom rows. Every project is created with one template per type, so customizing one is usually a PUT; creating a type the project already has returns 409. Valid template types: welcome, confirmation, password_reset, password_changed operationId: createEmailTemplate security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEmailTemplateRequest' responses: '201': description: Template created content: application/json: schema: $ref: '#/components/schemas/EmailTemplate' '400': description: Invalid template type content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Custom email templates require the PRO plan content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The project already has a template of this type content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/email-templates/{type}: get: tags: - Auth Configuration summary: Get email template operationId: getEmailTemplate security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: type in: path required: true schema: type: string enum: [welcome, confirmation, password_reset, password_changed] responses: '200': description: Email template content: application/json: schema: $ref: '#/components/schemas/EmailTemplate' '404': description: Template not found put: tags: - Auth Configuration summary: Update email template description: | Updates a custom email template. Custom email templates are a PRO-plan feature: requests from a FREE-plan project owner are rejected with 403 (including after a PRO→FREE downgrade), so a FREE project cannot modify templates and always sends the built-in defaults. operationId: updateEmailTemplate security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: type in: path required: true schema: type: string enum: [welcome, confirmation, password_reset, password_changed] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateEmailTemplateRequest' responses: '200': description: Template updated content: application/json: schema: $ref: '#/components/schemas/EmailTemplate' '403': description: Custom email templates require the PRO plan content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Template not found delete: tags: - Auth Configuration summary: Delete email template description: | Deletes a custom template, reverting to the default. Custom email templates are a PRO-plan feature: requests from a FREE-plan project owner are rejected with 403. operationId: deleteEmailTemplate security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: type in: path required: true schema: type: string enum: [welcome, confirmation, password_reset, password_changed] responses: '204': description: Template deleted '403': description: Custom email templates require the PRO plan content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Template not found /email-templates/defaults: get: tags: - Auth Configuration summary: Get default email templates description: Returns the default email templates used when no custom template is configured. operationId: getDefaultEmailTemplates responses: '200': description: Default templates content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/EmailTemplate' /email-templates/defaults/{type}: get: tags: - Auth Configuration summary: Get default email template by type operationId: getDefaultEmailTemplate parameters: - name: type in: path required: true schema: type: string enum: [welcome, confirmation, password_reset, password_changed] responses: '200': description: Default template content: application/json: schema: $ref: '#/components/schemas/EmailTemplate' '404': description: Template type not found /projects/{id}/auth/config: get: tags: - Auth Configuration summary: Get auth configuration operationId: getAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Auth configuration content: application/json: schema: $ref: '#/components/schemas/AuthConfig' put: tags: - Auth Configuration summary: Update auth configuration description: | Updates the project's auth configuration. Only the fields present in the body are changed. operationId: updateAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAuthConfigRequest' responses: '200': description: Configuration updated content: application/json: schema: $ref: '#/components/schemas/AuthConfig' '403': description: | The update would turn on, widen, or otherwise edit the email domain allowlist (`allowed_email_domains`, `allowed_email_domains_mode`) for a project that is not on the PRO plan. A FREE project keeps whatever allowlist it already has — parked, enforcing nothing until it upgrades — and may still remove it, so a downgrade never leaves a project locked out of its own signups. content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/config/test-email: post: tags: - Auth Configuration summary: Send a test email using the project's saved SMTP config description: | Sends a diagnostic email to `to_email` using the project's persisted `auth_config` SMTP credentials. If `html_body` or `text_body` is supplied, the override path is taken: those values (plus optional `subject`) are rendered through html/text templates against the project's `Data` and used as the body — used by the template editor's "Send Test" affordance to preview an unsaved template. With both bodies omitted, a hardcoded diagnostic message is sent and any `subject` field is ignored. Sending `subject` alone (no bodies) is rejected with 400 to avoid a silently-dropped subject or a blank message. Also rejects with 400 if `email_enabled=false` or `smtp_host` is empty. operationId: testEmailConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestEmailRequest' responses: '200': description: Test email sent content: application/json: schema: $ref: '#/components/schemas/TestEmailResponse' '400': description: Invalid request or email delivery not configured '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found '502': description: Template render failure or SMTP delivery failed /projects/{id}/auth/hosted-pages/{pageType}: get: tags: - Auth Configuration summary: Get hosted auth page description: | Returns the saved HTML/CSS for the page type, or `page: null` when the project has not customized it yet. Always returns `defaults` (the theme shell to seed an editor with, which is valid input to the update endpoint) and `runtime` (the script the rendered page runs, plus a preview harness). operationId: getAuthHostedPage security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedAuthPageType' responses: '200': description: Hosted page loaded content: application/json: schema: $ref: '#/components/schemas/AuthHostedPageResponse' put: tags: - Auth Configuration summary: Update hosted auth page description: | Saves the current HTML/CSS for this page type. Security validation rejects script tags, javascript: URLs, inline event handlers, iframe/object/embed/meta/link tags in HTML, and closing style/head tags in CSS. operationId: updateAuthHostedPage security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedAuthPageType' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthHostedPageRequest' responses: '200': description: Hosted page updated content: application/json: schema: $ref: '#/components/schemas/AuthHostedPageResponse' '400': description: Invalid input or unsafe markup '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found /projects/{id}/auth/pages/appearance: get: tags: [Auth Configuration] summary: Get managed auth page appearance operationId: getAuthPageAppearance security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Saved appearance and effective plan state content: application/json: schema: $ref: '#/components/schemas/AuthPageAppearanceResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Appearance could not be read content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/pages/theme: put: tags: [Auth Configuration] summary: Save the managed auth page theme operationId: updateAuthPageTheme security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthPageThemeRequest' responses: '200': description: Theme saved content: application/json: schema: $ref: '#/components/schemas/UpdateAuthPageThemeRequest' '400': description: Invalid or unreadable theme content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Plan does not permit customisation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Theme could not be saved content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: [Auth Configuration] summary: Clear the managed auth page theme operationId: deleteAuthPageTheme security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '204': description: Theme cleared '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Plan does not permit customisation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Theme could not be cleared content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/pages/{pageType}/layout: parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedAuthPageType' put: tags: [Auth Configuration] summary: Save one managed auth page layout operationId: updateAuthPageLayout security: - UserToken: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAuthPageLayoutRequest' responses: '200': description: Layout saved content: application/json: schema: $ref: '#/components/schemas/UpdateAuthPageLayoutRequest' '400': description: Invalid page type or layout content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Plan does not permit customisation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Layout could not be saved content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: [Auth Configuration] summary: Clear one managed auth page layout operationId: deleteAuthPageLayout security: - UserToken: [] responses: '204': description: Layout cleared '400': description: Invalid page type content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Plan does not permit customisation content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Layout could not be cleared content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/pages/{pageType}/preview: get: tags: [Auth Configuration] summary: Render a short-lived managed auth page preview description: | Public HTML endpoint for a preview URL returned by the POST operation. The signed ticket contains the unsaved appearance, expires shortly, and runs the production page runtime against mocked authentication responses. operationId: renderAuthPagePreview security: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedAuthPageType' - name: ticket in: query required: true schema: type: string minLength: 1 maxLength: 4096 description: Short-lived signed preview ticket returned by the POST operation. responses: '200': description: Rendered preview document content: text/html: schema: type: string '404': description: Ticket is invalid or expired, its path does not match, or managed authentication is disabled content: text/plain: schema: type: string '500': description: Preview could not be rendered content: text/plain: schema: type: string post: tags: [Auth Configuration] summary: Preview an unsaved managed auth page appearance operationId: previewAuthPage security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedAuthPageType' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreviewAuthPageRequest' responses: '200': description: Short-lived URL for the rendered preview document content: application/json: schema: $ref: '#/components/schemas/PreviewAuthPageResponse' '400': description: Invalid page type or draft content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found or managed authentication is disabled content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Preview could not be rendered content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/auth/hosted/{pageType}: get: tags: - Auth Configuration summary: Render a managed auth page description: | Public HTML endpoint for signup, forgot-password, device approval, verify-email, and reset-password pages. Login uses the path without a page type. Requires `Accept: text/html`. Returns 404 when managed hosted pages are disabled for the project. security: [] operationId: renderManagedAuthPage parameters: - $ref: '#/components/parameters/ProjectId' - name: pageType in: path required: true schema: $ref: '#/components/schemas/HostedRenderablePageType' responses: '200': description: Hosted auth page HTML content: text/html: schema: type: string '400': description: Invalid project id or unsupported Accept header '404': description: Managed pages disabled or page type not found /projects/{id}/auth/hosted: get: tags: - Auth Configuration summary: Render default managed auth page description: | Public HTML endpoint for the managed login page. Requires `Accept: text/html`. security: [] operationId: renderDefaultManagedAuthPage parameters: - $ref: '#/components/parameters/ProjectId' - name: action in: query required: false schema: type: string enum: [login, signup, forgot-password, device] description: | Optional deep-link action for the unified hosted page. Ignored when a custom login page is configured. `action=device` renders the device authorization approval UI inline (no redirect to any external app); it signs the user in and calls `POST /auth/device/verify`. - name: user_code in: query required: false schema: type: string description: Device user code (from `POST /auth/device/authorize`) used with `action=device`. - name: anon_key in: query required: false schema: type: string description: Project anon key used by built-in managed auth flows (required for login/signup/device actions). - name: state in: query required: false schema: type: string description: | Opaque one-time nonce generated by the client SDK before redirecting here. On successful login/signup it is echoed back in the post-auth redirect fragment as `state`, so the SDK can bind the returned session to the flow it initiated (login-CSRF / session-fixation defense). The SDK rejects a returned session whose `state` does not match. responses: '200': description: Hosted auth page HTML content: text/html: schema: type: string '400': description: Invalid project id or unsupported Accept header '404': description: Managed pages disabled /projects/{id}/auth/hosted/login/options: get: tags: - Auth Configuration summary: Get hosted login runtime options description: | Returns runtime options for the built-in managed login flow. Requires `anon_key` query parameter. Rate limited per project and client IP. Excess requests return `429` and `Retry-After`. security: [] operationId: getHostedLoginOptions parameters: - $ref: '#/components/parameters/ProjectId' - name: anon_key in: query required: true schema: type: string responses: '200': description: Hosted login options returned content: application/json: schema: $ref: '#/components/schemas/HostedLoginOptionsResponse' '401': description: Invalid or missing anon key '429': description: Rate limit exceeded '404': description: Managed pages disabled /projects/{id}/auth/hosted/login/check-email: post: tags: - Auth Configuration summary: Check whether email exists for hosted login flow description: | Used by the built-in managed login page to branch UI between signin and signup. Requires anon key in Authorization header. Rate limited per project and client IP. Excess requests return `429` and `Retry-After`. security: [] operationId: hostedLoginCheckEmail parameters: - $ref: '#/components/parameters/ProjectId' - name: Authorization in: header required: true schema: type: string description: Bearer anon key (`Bearer `) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HostedLoginEmailCheckRequest' responses: '200': description: Email existence evaluated content: application/json: schema: $ref: '#/components/schemas/HostedLoginEmailCheckResponse' '401': description: Invalid or missing anon key '429': description: Rate limit exceeded /projects/{id}/auth/methods: get: tags: - Auth Configuration summary: Get all authentication methods description: | Returns all configured authentication methods for this project, including email/password, anonymous, device authorization, and OAuth providers. operationId: getAuthMethods security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Authentication methods configuration content: application/json: schema: type: object properties: email_password: type: object properties: enabled: type: boolean method: type: string name: type: string anonymous: type: object properties: enabled: type: boolean method: type: string name: type: string oauth_providers: type: array items: type: object properties: enabled: type: boolean method: type: string provider: type: string name: type: string redirect_url: type: string scopes: type: array items: type: string available_methods: type: array items: type: string example: ["email_password", "oauth_google", "oauth_github"] put: tags: - Auth Configuration summary: Configure authentication methods (unified) description: | Configure all authentication methods in a single request. At least one method must remain enabled. operationId: configureAuthMethods security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: content: application/json: schema: type: object properties: enable_email_password: type: boolean enable_anonymous: type: boolean oauth_providers: type: array items: type: object properties: provider: type: string enabled: type: boolean responses: '200': description: Methods configured '400': description: At least one method must be enabled # OAuth Configuration Endpoints /projects/{id}/oauth/configs: get: tags: - OAuth Configuration summary: List OAuth configurations description: List all OAuth provider configurations for this project operationId: listOAuthConfigs security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: List of OAuth configurations content: application/json: schema: type: object properties: configs: type: array items: $ref: '#/components/schemas/OAuthConfig' post: tags: - OAuth Configuration summary: Create OAuth configuration description: Configure OAuth provider (Google, GitHub, Microsoft, Apple, Device) operationId: createOAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOAuthConfigRequest' responses: '201': description: OAuth config created content: application/json: schema: $ref: '#/components/schemas/OAuthConfig' '409': description: Provider already configured /projects/{id}/oauth/configs/{provider}: get: tags: - OAuth Configuration summary: Get OAuth configuration operationId: getOAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple, device] - name: client_id in: query required: false schema: type: string description: Required when `provider=device` to select a specific device client. responses: '200': description: OAuth configuration content: application/json: schema: $ref: '#/components/schemas/OAuthConfig' put: tags: - OAuth Configuration summary: Update OAuth configuration operationId: updateOAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple, device] - name: client_id in: query required: false schema: type: string description: Required when `provider=device` to select a specific device client. requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateOAuthConfigRequest' responses: '200': description: OAuth config updated content: application/json: schema: $ref: '#/components/schemas/OAuthConfig' delete: tags: - OAuth Configuration summary: Delete OAuth configuration operationId: deleteOAuthConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple, device] - name: client_id in: query required: false schema: type: string description: Required when `provider=device` to select a specific device client. responses: '204': description: OAuth config deleted /projects/{id}/oauth/providers: get: tags: - OAuth Configuration summary: List available OAuth providers description: Get list of supported OAuth providers and their default scopes operationId: listAvailableOAuthProviders security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Available providers content: application/json: schema: type: object properties: providers: type: array items: type: object properties: id: type: string name: type: string default_scopes: type: array items: type: string # OAuth Authentication Endpoints /auth/oauth/{provider}/authorize: get: tags: - OAuth Authentication summary: Start OAuth authorization description: | Redirects user to OAuth provider for authorization. Handles CSRF protection with state parameter. Project is identified via the anon_key query parameter. operationId: authOAuthAuthorize parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] - name: anon_key in: query required: true schema: type: string description: Project anon key (required - identifies the project) - name: redirect_url in: query schema: type: string description: | URL to redirect to after the OAuth flow (optional). Must exactly match an entry in the project's `allowed_redirect_urls`, including its query string, or be the project's own managed hosted-auth page URL. - name: client_state in: query schema: type: string maxLength: 255 description: | Optional application nonce. It is stored with the server-generated provider state and echoed to redirect_url as `state`. - name: response_mode in: query schema: type: string enum: [code] description: | Set to `code` to receive a short-lived authorization code at redirect_url, then use POST /auth/oauth/exchange to obtain the session. `redirect_url` is required in this mode. When omitted, the established session-fragment response is retained for compatibility with existing clients. responses: '307': description: Redirect to OAuth provider '400': description: | OAuth provider is disabled for this project, or `redirect_url` is not registered in `allowed_redirect_urls` '404': description: OAuth provider not configured /auth/oauth/{provider}/callback: get: tags: - OAuth Authentication summary: OAuth callback handler description: | Handles OAuth provider callback with authorization code. Exchanges code for tokens and creates/signs in user. operationId: authOAuthCallback parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] - name: code in: query required: true schema: type: string - name: state in: query required: true schema: type: string - name: error in: query schema: type: string responses: '200': description: Existing user signed in (when redirect_url was omitted) content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '201': description: New user created and signed in (when redirect_url was omitted) content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '400': description: | Missing/invalid code or state, the state parameter expired, or the flow's stored redirect_url is no longer registered in allowed_redirect_urls (re-checked at callback time) '403': description: | The provider's email domain is not in `allowed_email_domains`. Creating an account is refused under `signup` and `signup_and_signin`; signing in an already-linked account is refused under `signup_and_signin`. '409': description: Email already exists (requires linking) '303': description: | Redirect to the exact registered redirect_url. Flows that requested response_mode=code receive a short-lived, single-use `code` and optional application `state`; compatibility flows receive the established session fragment. /auth/oauth/exchange: post: tags: - OAuth Authentication summary: Exchange OAuth authorization code description: | Atomically consumes a short-lived callback code and returns the user's session. The request must use the same project anon key and exact redirect_url that initiated the flow. operationId: authOAuthExchange security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: [code, redirect_url] properties: code: type: string redirect_url: type: string format: uri responses: '200': description: Authorization code consumed and session created content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '400': description: Invalid, expired, consumed, or redirect-mismatched code '401': description: Missing or invalid project anon key '403': description: | Email confirmation is now required, or the account's email domain is not in `allowed_email_domains` while `allowed_email_domains_mode` is `signup_and_signin`. Both are re-checked here because the code outlives the callback that issued it. '429': description: Too many exchange attempts from this client /auth/device/authorize: post: tags: - OAuth Authentication summary: Start RFC8628 device authorization description: | Starts OAuth 2.0 Device Authorization Grant (RFC 8628). Returns `device_code` for the CLI and `user_code` for browser verification. By default the returned `verification_uri` / `verification_uri_complete` point at the project's managed device-approval page served by this API (`/projects/{projectId}/auth/hosted?action=device&user_code=...&anon_key=...`), which requires managed auth enabled and a default anon key for the project. Projects can override this by setting `device_verification_url` on the auth config (`PATCH /auth/config`). When set, that URL is returned as-is with the `user_code` appended (no `action=device` hint and no embedded anon key — the page brings its own), so a CLI's `login` command surfaces the project's own RFC 8628 approval page. With a custom URL, device login does **not** require managed auth to be enabled; the custom page's origin must be in the project's auth CORS allowlist to call `POST /auth/device/verify`. Either way the verification page must authenticate the end user and call `POST /auth/device/verify` with the `user_code`. See the device-auth guide for both approaches. operationId: authDeviceAuthorize requestBody: required: true content: application/json: schema: type: object required: [client_id] properties: client_id: type: string description: Enabled `device` OAuth client ID for the target project responses: '200': description: Device authorization started content: application/json: schema: $ref: '#/components/schemas/DeviceAuthorizationResponse' '400': description: Invalid request or unauthorized client content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' /auth/device/token: post: tags: - OAuth Authentication summary: Poll device token endpoint description: | RFC8628 token polling endpoint. Returns OAuth errors such as `authorization_pending`, `slow_down`, `access_denied`, and `expired_token`. operationId: authDeviceToken requestBody: required: true content: application/json: schema: type: object required: [grant_type, device_code, client_id] properties: grant_type: type: string enum: ["urn:ietf:params:oauth:grant-type:device_code"] device_code: type: string client_id: type: string responses: '200': description: Device flow completed, auth-user session minted content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '400': description: Polling state/error response content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' '403': description: | `access_denied` - the approving account's email domain is not in `allowed_email_domains` while `allowed_email_domains_mode` is `signup_and_signin`. Re-checked here because approval and redemption are separate requests. content: application/json: schema: $ref: '#/components/schemas/OAuthErrorResponse' /auth/device/verify: post: tags: - OAuth Authentication summary: Approve or deny a device code description: | Browser-side endpoint for authenticated auth-users to approve (`approve`) or deny (`deny`) a `user_code`. Called by the verification page after the end user signs in. The grant is scoped to the project the auth-user token belongs to: approving a `user_code` issued for a different project returns `403`. This endpoint does not require managed auth to be enabled, so a custom verification page (hosted anywhere) can drive approval — it just needs an authenticated project auth-user access token and, for cross-origin browser calls, the page origin allowed in the project's auth CORS settings. operationId: authDeviceVerify security: - AuthUserAccessToken: [] requestBody: required: true content: application/json: schema: type: object required: [user_code] properties: user_code: type: string action: type: string enum: [approve, deny] default: approve responses: '200': description: Verification action accepted content: application/json: schema: type: object properties: success: type: boolean status: type: string '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/platform/exchange: post: tags: - OAuth Authentication summary: Exchange auth-user device session for platform token description: | Exchanges a verified auth-user device-flow session into a platform token for CLI usage. The target platform user is derived from authenticated auth-user mapping; client cannot select another user. operationId: authPlatformExchange security: - AuthUserAccessToken: [] requestBody: required: true content: application/json: schema: type: object required: [client_id] properties: client_id: type: string responses: '200': description: Platform token minted content: application/json: schema: $ref: '#/components/schemas/PlatformExchangeResponse' '403': description: | Exchange not allowed for this session/client/project, or the account's email domain is not in `allowed_email_domains` while `allowed_email_domains_mode` is `signup_and_signin`. The domain is re-checked here because the minted platform token outlives the session it is exchanged from. content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/providers: get: tags: - OAuth Authentication summary: List user's linked providers description: Get list of OAuth providers linked to current user operationId: authListOAuthProviders security: - AuthUserAccessToken: [] responses: '200': description: Linked providers content: application/json: schema: type: object properties: providers: type: array items: type: object properties: provider: type: string linked_at: type: string format: date-time updated_at: type: string format: date-time '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/{provider}/link: post: tags: - OAuth Authentication summary: Link OAuth provider to current user description: | Generates authorization URL to link OAuth provider to existing account. User must be authenticated. operationId: authLinkOAuthProvider security: - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] - name: redirect_url in: query schema: type: string description: | URL to redirect to after linking completes (optional). Same allowed_redirect_urls requirement as GET /auth/oauth/{provider}/authorize. - name: client_state in: query schema: type: string maxLength: 255 description: | Optional application nonce echoed to redirect_url as `state`. - name: response_mode in: query schema: type: string enum: [code] description: | Set to `code` to receive a short-lived authorization code at redirect_url. `redirect_url` is required in this mode. When omitted, the established session-fragment response is retained for compatibility with existing clients. responses: '200': description: Authorization URL generated content: application/json: schema: type: object properties: authorization_url: type: string '400': description: redirect_url is not registered in allowed_redirect_urls content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: OAuth provider not configured content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Provider already linked content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/{provider}/unlink: delete: tags: - OAuth Authentication summary: Unlink OAuth provider description: | Remove OAuth provider from user's account. Cannot unlink if it's the only authentication method. operationId: authUnlinkOAuthProvider security: - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] responses: '204': description: Provider unlinked '400': description: Cannot unlink last authentication method content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Provider not linked content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/{provider}/refresh-token: post: tags: - OAuth Authentication summary: Refresh OAuth provider token description: | Refresh the access token for an OAuth provider using its refresh token. Allows calling provider APIs on user's behalf (e.g., Google Drive, GitHub repos). operationId: refreshOAuthProviderToken security: - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] responses: '200': description: Token refreshed successfully content: application/json: schema: type: object properties: message: type: string provider: type: string expires_in: type: integer '400': description: No refresh token available or refresh failed content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Provider not linked content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/{provider}/token: get: tags: - OAuth Authentication summary: Get current provider access token description: | Get valid access token for OAuth provider. Automatically refreshes if expired. operationId: getOAuthProviderToken security: - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] responses: '200': description: Current access token content: application/json: schema: type: object properties: message: type: string provider: type: string expires_in: type: integer '401': description: Not authenticated content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Provider not linked content: application/json: schema: $ref: '#/components/schemas/Error' /auth/oauth/{provider}/call-api: post: tags: - OAuth Authentication summary: Call OAuth provider API description: | Make an authenticated request to an OAuth provider's API on behalf of the user. The user's stored access token is automatically used and refreshed if needed. The request is always sent to the provider's fixed API base URL joined with the caller-supplied `endpoint`. `endpoint` must be a relative path beginning with `/` (optionally with a query string); it cannot change the target host. Absolute URLs, protocol-relative `//host` values, or userinfo (`@host`) are rejected with `400` so the request can never be redirected to another host. Examples of `endpoint`: - Google userinfo: `/oauth2/v1/userinfo` - GitHub repositories: `/user/repos` - Microsoft Graph profile: `/me` The response wraps the provider's raw JSON value with request metadata. An empty provider body is represented as `data: null`; the envelope preserves the provider's HTTP status in `status_code`, including errors. Provider response bodies are limited to 8 MiB after decompression. Transport failures, invalid JSON, and oversized bodies return `502`. operationId: callOAuthProviderAPI security: - AuthUserAccessToken: [] parameters: - name: provider in: path required: true schema: type: string enum: [google, github, microsoft, apple] requestBody: required: true content: application/json: schema: type: object required: - endpoint properties: endpoint: type: string description: | Relative path on the provider's API, beginning with `/`. It is joined with the provider's fixed base URL; it must not contain a scheme, host, userinfo, or a leading `//`. example: "/user/repos" method: type: string enum: [GET, POST] default: GET description: HTTP method to use body: type: object additionalProperties: true description: Request body for POST requests responses: '200': description: Provider API response content: application/json: schema: type: object description: OAuth provider API response envelope required: - provider - endpoint - status_code - data properties: provider: type: string enum: [google, github, microsoft, apple] endpoint: type: string status_code: type: integer minimum: 100 maximum: 599 data: description: Raw provider JSON value, or null when the provider returns no body nullable: true '400': description: | Invalid request (for example: missing `endpoint`, an `endpoint` that is not a relative path, or an unsupported HTTP method). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Not authenticated or provider not linked content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: OAuth provider configuration not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Failed to create the provider API request content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: Provider transport failure, invalid JSON, or response body larger than 8 MiB content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/anon-keys: get: tags: - Anon Keys summary: List anon keys description: | Supports two mutually exclusive pagination modes. Offset mode uses `page` and `limit` and is the default when neither `cursor` nor `search` is supplied (first page, default `limit`). Cursor mode uses `cursor` and `limit`, supports `search` (case-insensitive name match), and returns `next_cursor`. Sending both `page` and `cursor` (or `page` and `search`) returns 400. operationId: listAnonKeys security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: List of anon keys content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AnonKey' total: type: integer description: Total number of items matching the query (so the UI can render numbered pages). has_more: type: boolean description: Whether a next page exists. next_cursor: type: string description: Opaque cursor for the next page (cursor pagination only) prev_cursor: type: string description: Opaque cursor for the previous page (cursor pagination only). Send as `ending_before`. post: tags: - Anon Keys summary: Create anon key operationId: createAnonKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: | Key name for identification. Can only contain letters, numbers, underscores, and hyphens. pattern: "^[A-Za-z0-9_-]+$" minLength: 1 maxLength: 255 example: "frontend-app" permissions: type: array items: type: string enum: # Auth permissions - auth.signup - auth.signin - auth.refresh - auth.logout - auth.password_reset - auth.confirm_email - auth.resend_confirmation # Storage permissions - storage.upload - storage.download - storage.list - storage.delete # Realtime permissions - realtime.connect - realtime.subscribe - realtime.publish # Functions permissions - functions.invoke description: | Optional list of permissions for this key. If not provided, defaults to auth-only permissions: auth.signup, auth.signin, auth.refresh, auth.logout, auth.password_reset, auth.confirm_email, auth.resend_confirmation. Storage, realtime, and functions permissions must be explicitly added if needed. example: ["auth.signup", "auth.signin", "auth.refresh", "auth.logout"] responses: '201': description: Anon key created content: application/json: schema: $ref: '#/components/schemas/AnonKey' /projects/{id}/anon-keys/{keyId}: get: tags: - Anon Keys summary: Get anon key description: Get details of a specific anon key operationId: getAnonKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '200': description: Anon key details content: application/json: schema: $ref: '#/components/schemas/AnonKey' '404': description: Key not found delete: tags: - Anon Keys summary: Revoke anon key description: Revokes key - it will immediately stop working operationId: revokeAnonKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '204': description: Key revoked '401': description: Unauthorized '403': description: Forbidden '404': description: Key not found '409': description: Cannot delete the project's default anon key content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/anon-keys/{keyId}/regenerate: post: tags: - Anon Keys summary: Regenerate anon key description: Generate new JWT value for existing key operationId: regenerateAnonKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '200': description: Key regenerated content: application/json: schema: $ref: '#/components/schemas/AnonKey' /projects/{id}/anon-keys/{keyId}/set-default: post: tags: - Anon Keys summary: Set default anon key description: Promotes the given key to the project's configured default. At most one key per project can be default. operationId: setDefaultAnonKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '200': description: Key set as default content: application/json: schema: $ref: '#/components/schemas/AnonKey' '401': description: Unauthorized '403': description: Forbidden '404': description: Anon key not found '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/service-keys: get: tags: - Service Keys summary: List service keys (paginated) description: | List all service role keys for a project with pagination. **WARNING:** Service keys bypass RLS - for backend/admin use only! operationId: listServiceKeys security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Paginated list of service keys content: application/json: schema: $ref: '#/components/schemas/PaginatedServiceKeys' post: tags: - Service Keys summary: Create service key description: "Create a new service role key for admin operations.\n\n**WARNING:** Service keys bypass all RLS policies!\nStore securely and NEVER expose in frontend code.\n" operationId: createServiceKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: | Descriptive name for the key (e.g., "admin-dashboard", "background-jobs"). Can only contain letters, numbers, underscores, and hyphens. pattern: "^[A-Za-z0-9_-]+$" minLength: 1 maxLength: 255 example: "admin-dashboard" permissions: type: array items: type: string description: | Optional least-privilege scope for the key. When omitted, empty, or containing only blank strings, the key is granted full access (["*"]) for backward compatibility. Provide an explicit list (e.g. ["functions.invoke", "locks.manage"]) to restrict the key; "*" grants everything. Scope enforcement applies to function invocation, storage object operations, and project locks. example: ["functions.invoke", "locks.manage"] responses: '201': description: Service key created - save the key_value immediately! content: application/json: schema: $ref: '#/components/schemas/ServiceKey' '409': description: Key with this name already exists /projects/{id}/service-keys/{keyId}: get: tags: - Service Keys summary: Get service key description: Get details of a specific service key operationId: getServiceKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '200': description: Service key details content: application/json: schema: $ref: '#/components/schemas/ServiceKey' '404': description: Key not found delete: tags: - Service Keys summary: Delete service key description: "Permanently delete a service key.\nAny services using this key will immediately lose access.\n" operationId: deleteServiceKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '204': description: Key deleted /projects/{id}/service-keys/{keyId}/regenerate: post: tags: - Service Keys summary: Regenerate service key description: | Generate new JWT value for existing key. The old key is immediately invalidated. Update your backend services with the new key before regenerating in production. operationId: regenerateServiceKey security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: keyId in: path required: true schema: type: string format: uuid responses: '200': description: Key regenerated - save the new key_value immediately! content: application/json: schema: $ref: '#/components/schemas/ServiceKey' # ============================================================================ # Storage Bucket Management (Platform Admin) # ============================================================================ /projects/{id}/storage/buckets: get: tags: - Storage Buckets summary: List all storage buckets in a project description: | With no pagination params, returns the full bucket list as a bare array (legacy). Supplying `cursor`, `ending_before`, `search`, or `limit` switches to keyset (cursor) pagination and returns a paginated envelope with `next_cursor`/`prev_cursor` and a filtered `total`. operationId: listStorageBuckets security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: | Either the full bucket list (bare array, legacy) or a paginated envelope when cursor pagination is requested. content: application/json: schema: oneOf: - type: array items: $ref: '#/components/schemas/StorageBucket' - $ref: '#/components/schemas/PaginatedStorageBuckets' post: tags: - Storage Buckets summary: Create a new storage bucket operationId: createStorageBucket security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStorageBucketRequest' responses: '201': description: Bucket created content: application/json: schema: $ref: '#/components/schemas/StorageBucket' '409': description: Bucket already exists /projects/{id}/storage/buckets/{bucketName}: get: tags: - Storage Buckets summary: Get storage bucket by name operationId: getStorageBucket security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' responses: '200': description: Bucket details content: application/json: schema: $ref: '#/components/schemas/StorageBucket' '404': description: Bucket not found patch: tags: - Storage Buckets summary: Update storage bucket settings operationId: updateStorageBucket security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateStorageBucketRequest' responses: '200': description: Bucket updated content: application/json: schema: $ref: '#/components/schemas/StorageBucket' delete: tags: - Storage Buckets summary: Delete storage bucket and all objects operationId: deleteStorageBucket security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' responses: '200': description: Bucket deleted # ============================================================================ # Storage Policy Management (Platform Admin) # ============================================================================ /projects/{id}/storage/buckets/{bucketName}/policies: get: tags: - Storage Policies summary: List storage policies for a bucket operationId: listStoragePolicies security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' responses: '200': description: List of policies content: application/json: schema: type: array items: $ref: '#/components/schemas/StoragePolicy' post: tags: - Storage Policies summary: Create a storage policy operationId: createStoragePolicy security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoragePolicyRequest' responses: '201': description: Policy created content: application/json: schema: $ref: '#/components/schemas/StoragePolicy' /projects/{id}/storage/buckets/{bucketName}/policies/{policyId}: delete: tags: - Storage Policies summary: Delete a storage policy operationId: deleteStoragePolicy security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/BucketName' - name: policyId in: path required: true schema: type: string format: uuid responses: '200': description: Policy deleted # ============================================================================ # Storage Admin Endpoints (Platform Admin) # ============================================================================ /projects/{id}/storage/objects: get: tags: - Storage Admin summary: List all storage objects in a project description: | Returns a paginated list of all storage objects across all buckets in the project. Supports filtering by owner and pagination. operationId: listStorageObjectsAdmin security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - name: owner_id in: query description: Filter by owner user ID schema: type: string format: uuid - name: page in: query description: Page number (1-based) schema: type: integer default: 1 minimum: 1 - name: limit in: query description: Items per page schema: type: integer default: 50 minimum: 1 maximum: 100 - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/EndingBefore' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Search' responses: '200': description: Paginated list of storage objects content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/StorageObjectWithBucket' page: type: integer limit: type: integer total: type: integer has_more: type: boolean next_cursor: type: string description: Opaque cursor for the next page (cursor pagination only) prev_cursor: type: string description: Opaque cursor for the previous page (cursor pagination only). Send as `ending_before`. /projects/{id}/storage/stats: get: tags: - Storage Admin summary: Get storage statistics for a project description: Returns aggregate storage statistics including bucket count, object count, and total size. operationId: getStorageStats security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Storage statistics content: application/json: schema: $ref: '#/components/schemas/StorageStats' # ============================================================================ # Realtime WebSocket (SDK/Client) # ============================================================================ # # WebSocket Endpoint: GET /realtime/v1/websocket # # This endpoint upgrades HTTP to WebSocket for realtime communication. # It is not documented as an OpenAPI path because it's a WebSocket upgrade. # # Authentication Options: # # Option 1: User Token (Frontend) # - Query param: apikey={anon_key} # - WebSocket handshake: token={user_access_token} # - Use case: End-user applications # # Option 2: Service Role Key (Backend) # - Query param: apikey={anon_key} (optional) # - WebSocket handshake: token={service_role_key} # - Use case: Server-to-server, bots, admin tools # - Note: Project ID inferred from service key if anon key not provided # # Example connection URLs: # ws://api.example.com/realtime/v1/websocket?apikey=ak-... # wss://api.example.com/realtime/v1/websocket?apikey=ak-... # # The Centrifuge protocol is used for WebSocket communication. # See: https://centrifugal.dev/docs/transports/client_protocol # # ============================================================================ # ============================================================================ # Realtime Configuration (Platform Admin) # ============================================================================ /projects/{id}/realtime/config: get: tags: - Realtime summary: Get realtime configuration for a project description: Returns the realtime configuration including enabled features and limits. operationId: getRealtimeConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Realtime configuration content: application/json: schema: $ref: '#/components/schemas/RealtimeConfig' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' put: tags: - Realtime summary: Update realtime configuration for a project description: Updates realtime settings including feature toggles and limits. operationId: updateRealtimeConfig security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRealtimeConfigRequest' responses: '200': description: Updated realtime configuration content: application/json: schema: $ref: '#/components/schemas/RealtimeConfig' '400': description: Invalid configuration values content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/realtime/stats: get: tags: - Realtime summary: Get realtime statistics for a project description: Returns realtime usage statistics including connection counts and subscribed tables. operationId: getRealtimeStats security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: Realtime statistics content: application/json: schema: $ref: '#/components/schemas/RealtimeStats' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' # ============================================================================ # Storage Object Operations (SDK-facing - auth in header) # ============================================================================ /storage/{bucketName}: get: tags: - Storage Objects summary: List objects in a bucket operationId: listStorageObjects security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: prefix in: query description: Filter objects by path prefix schema: type: string - name: limit in: query description: Maximum objects to return schema: type: integer default: 50 maximum: 1000 - name: cursor in: query description: Pagination cursor schema: type: string responses: '200': description: List of objects content: application/json: schema: $ref: '#/components/schemas/StorageListResponse' '403': description: Access denied by storage policy '429': $ref: '#/components/responses/BandwidthCapExceeded' /locks/{key}/lease: post: tags: - Locks summary: Acquire a project lock description: | Acquires a project-scoped lease using the project embedded in the service-role key. The caller must hold the `locks.manage` permission. Repeating the request with the same lock token is idempotent and resets that lease to the requested TTL. A different live owner receives `409 lock_held`; a caller whose own lease already lapsed receives `409 lock_ownership_lost`. operationId: acquireProjectLock security: - ServiceRoleKey: [] parameters: - $ref: '#/components/parameters/LockKey' - $ref: '#/components/parameters/LockToken' - $ref: '#/components/parameters/LockRequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectLockLeaseRequest' responses: '201': description: Lease acquired content: application/json: schema: $ref: '#/components/schemas/ProjectLockLease' '400': description: Invalid lock key, token, or TTL content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A non-service credential was supplied or the service key lacks `locks.manage` content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: | The lock is held by another live lease (`lock_held`), or the caller's own lease lapsed and is not yet reclaimable (`lock_ownership_lost`). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Project lock request limit exceeded headers: Retry-After: description: Seconds until the current fixed-minute window ends. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Lock service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' patch: tags: - Locks summary: Renew a project lock description: | Renews a lease owned by the supplied lock token. The request must arrive more than one second before `expires_at`; this safety margin prevents clock skew between regional API instances from resurrecting an expired lease. operationId: renewProjectLock security: - ServiceRoleKey: [] parameters: - $ref: '#/components/parameters/LockKey' - $ref: '#/components/parameters/LockToken' - $ref: '#/components/parameters/LockRequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectLockLeaseRequest' responses: '200': description: Lease renewed content: application/json: schema: $ref: '#/components/schemas/ProjectLockLease' '400': description: Invalid lock key, token, or TTL content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A non-service credential was supplied or the service key lacks `locks.manage` content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The lease expired or is owned by another token content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Project lock request limit exceeded headers: Retry-After: description: Seconds until the current fixed-minute window ends. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Lock service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Locks summary: Release a project lock description: Releases a lease only when the supplied lock token still owns it. operationId: releaseProjectLock security: - ServiceRoleKey: [] parameters: - $ref: '#/components/parameters/LockKey' - $ref: '#/components/parameters/LockToken' - $ref: '#/components/parameters/LockRequestId' responses: '204': description: Lease released '400': description: Invalid lock key or token content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A non-service credential was supplied or the service key lacks `locks.manage` content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The lease is owned by another token content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Project lock request limit exceeded headers: Retry-After: description: Seconds until the current fixed-minute window ends. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Lock service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /locks/{key}: get: tags: - Locks summary: Read a project lock description: | Reports whether the lock is currently held, when its lease expires, and the holder's fencing token. `held` follows takeover eligibility rather than raw expiry, so `held: false` means an acquire would succeed now. No lock token is required, making this usable for monitoring and recovery. operationId: getProjectLock security: - ServiceRoleKey: [] parameters: - $ref: '#/components/parameters/LockKey' - $ref: '#/components/parameters/LockRequestId' responses: '200': description: Current lock state content: application/json: schema: $ref: '#/components/schemas/ProjectLockState' '400': description: Invalid lock key content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A non-service credential was supplied or the service key lacks `locks.manage` content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Project lock request limit exceeded headers: Retry-After: description: Seconds until the current fixed-minute window ends. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Lock service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Locks summary: Force release a project lock description: | Drops the lease whatever token holds it, for recovering a lock whose holder died without releasing. Use `DELETE /locks/{key}/lease` for normal release. This breaks mutual exclusion by itself: the previous holder keeps working until its own renewal fails. Guard the protected resource with the lease's `fencing_token`, which the next acquisition raises, so a write from the displaced holder can be rejected. Succeeds when the lock is already absent. operationId: forceReleaseProjectLock security: - ServiceRoleKey: [] parameters: - $ref: '#/components/parameters/LockKey' - $ref: '#/components/parameters/LockRequestId' responses: '204': description: Lock released '400': description: Invalid lock key content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A non-service credential was supplied or the service key lacks `locks.manage` content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Project lock request limit exceeded headers: Retry-After: description: Seconds until the current fixed-minute window ends. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Lock service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' /storage/{bucketName}/move: post: tags: - Storage Objects summary: Move/rename an object operationId: moveStorageObject security: - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StorageMoveRequest' responses: '200': description: Object moved content: application/json: schema: $ref: '#/components/schemas/StorageObject' '403': description: Access denied by storage policy '429': $ref: '#/components/responses/BandwidthCapExceeded' /storage/{bucketName}/copy: post: tags: - Storage Objects summary: Copy an object operationId: copyStorageObject security: - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StorageCopyRequest' responses: '201': description: Object copied content: application/json: schema: $ref: '#/components/schemas/StorageObject' '403': description: Access denied by storage policy '429': $ref: '#/components/responses/BandwidthCapExceeded' /storage/{bucketName}/{path}: post: tags: - Storage Objects summary: Upload a file or create resumable session description: | Unified endpoint for file uploads. Behavior depends on Content-Type and headers: **Simple Upload (multipart/form-data):** Upload a complete file in a single request. Best for files under 100MB. **Create Resumable Session (application/json):** Create a session for chunked uploads. Best for large files or unreliable networks. Requires: `Content-Type: application/json` with body `{"filename": "...", "content_type": "...", "total_size": ...}` **Complete Resumable Session:** Complete a session after all parts are uploaded. Requires: `X-Upload-Session` header with session ID and `X-Upload-Complete: true` header. operationId: uploadStorageObject security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string - name: X-Upload-Session in: header required: false description: Upload session ID (for completing resumable uploads) schema: type: string - name: X-Upload-Complete in: header required: false description: Set to "true" to complete a resumable upload session schema: type: string enum: ["true"] requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: File to upload (simple upload) application/json: schema: $ref: '#/components/schemas/CreateUploadSessionRequest' responses: '201': description: File uploaded or session created content: application/json: schema: oneOf: - $ref: '#/components/schemas/StorageObject' - $ref: '#/components/schemas/CreateUploadSessionResponse' '200': description: Resumable upload completed (when X-Upload-Complete=true) content: application/json: schema: $ref: '#/components/schemas/CompleteUploadSessionResponse' '400': description: | Bad request. This can occur when: - MIME type is not in the bucket's allowed_mime_types list - File exceeds the bucket's configured file_size_limit - File exceeds the global maximum upload size (5GB) - Invalid request body or missing required fields '403': description: Access denied by storage policy '413': description: | File size exceeds plan-based limits. This occurs when: - File exceeds the plan-based maximum file size (FREE or PRO tier) - Upload would exceed the project's total storage quota '429': $ref: '#/components/responses/BandwidthCapExceeded' put: tags: - Storage Objects summary: Upload a part of a resumable upload description: | Upload a single part of a resumable upload session. **Requirements:** - Part numbers start at 1 - All parts except the last must be at least 5MB - Maximum part size is 25MB - Parts can be uploaded in any order - Re-uploading a part overwrites the previous upload operationId: uploadPart security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string - name: X-Upload-Session in: header required: true description: Upload session ID schema: type: string - name: X-Part-Number in: header required: true description: Part number (1 to 10000) schema: type: integer minimum: 1 maximum: 10000 requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '200': description: Part uploaded content: application/json: schema: $ref: '#/components/schemas/UploadSessionPart' '400': description: Invalid part number or part data '403': description: Access denied '404': description: Session not found get: tags: - Storage Objects summary: Download a file or get upload session status description: | Download a file, or get the status of a resumable upload session. **File Download (default):** Downloads the file at the specified path. **Session Status (with X-Upload-Session header):** Returns the status of a resumable upload session, including which parts have been uploaded. operationId: downloadStorageObject security: - AnonKey: [] - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string - name: Range in: header required: false description: | HTTP Range header for partial downloads. Format: bytes=start-end or bytes=start- Examples: bytes=0-1023, bytes=1000- schema: type: string pattern: '^bytes=\d+-\d*$' - name: X-Upload-Session in: header required: false description: Upload session ID (to get session status instead of downloading) schema: type: string responses: '200': description: File content or session status headers: Content-Type: schema: type: string Content-Length: schema: type: integer ETag: schema: type: string content: application/octet-stream: schema: type: string format: binary application/json: schema: $ref: '#/components/schemas/UploadSessionStatusResponse' '206': description: Partial content (range request) '400': description: Invalid Range header format '403': description: Access denied by storage policy '404': description: Object or session not found '429': $ref: '#/components/responses/BandwidthCapExceeded' delete: tags: - Storage Objects summary: Delete a file or abort upload session description: | Delete a file, or abort a resumable upload session. **File Delete (default):** Deletes the file at the specified path. **Abort Session (with X-Upload-Session header):** Aborts a resumable upload session and cleans up any uploaded parts. operationId: deleteStorageObject security: - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string - name: X-Upload-Session in: header required: false description: Upload session ID (to abort session instead of deleting file) schema: type: string responses: '200': description: Object deleted or session aborted '403': description: Access denied by storage policy '404': description: Object or session not found '429': $ref: '#/components/responses/BandwidthCapExceeded' /storage/{bucketName}/{path}/visibility: patch: tags: - Storage Objects summary: Update file visibility (public/private) description: | Change whether a file is publicly accessible. Only the file owner or a service key can change visibility. If the bucket defines UPDATE policies, the owner must also satisfy one of them. - Public files can be downloaded with just an anon key (no user authentication required) - Private files (default) require authentication and must pass policy checks - All downloads go through the Volcano API - there is no direct access to the underlying store operationId: updateStorageObjectVisibility security: - ServiceRoleKey: [] - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StorageVisibilityRequest' responses: '200': description: Visibility updated content: application/json: schema: $ref: '#/components/schemas/StorageObject' '403': description: Not the file owner or denied by the bucket's UPDATE policies '404': description: Object not found # ============================================================================ # Public File Access (no authentication required) # ============================================================================ /public/{projectId}/{bucketName}/{path}: get: tags: - Storage Objects summary: Download a public file (no authentication required) description: | Download a file that has been marked as public. This endpoint requires NO authentication. **Access Requirements:** - The file must have `is_public: true` set via the visibility endpoint - Private files will return 403 Forbidden **Use Cases:** - Shareable public URLs for profile pictures, public documents, etc. - Embedding public files on external websites - Direct linking without requiring SDK or authentication **URL Format:** ``` GET /public/{projectId}/{bucketName}/{path} ``` **Example:** ``` https://api.volcano.dev/public/abc123/avatars/user-photo.jpg ``` **CORS:** This endpoint allows all origins since the file is already public. operationId: downloadPublicFile parameters: - name: projectId in: path required: true description: Project ID schema: type: string format: uuid - $ref: '#/components/parameters/BucketName' - name: path in: path required: true description: Object path within bucket schema: type: string responses: '200': description: File content content: '*/*': schema: type: string format: binary '206': description: Partial content (range request) '404': description: Not found (file doesn't exist or is not public) '429': $ref: '#/components/responses/BandwidthCapExceeded' # ============================================================================ # Health Check # ============================================================================ /health: get: tags: - System summary: Health check endpoint description: Returns server health status. Used for load balancer and monitoring checks. operationId: healthCheck responses: '200': description: Server is healthy content: text/plain: schema: type: string example: OK components: securitySchemes: AnonKey: $ref: ./components/common/security-schemes.yaml#/components/securitySchemes/AnonKey AuthUserAccessToken: $ref: ./components/common/security-schemes.yaml#/components/securitySchemes/AuthUserAccessToken ServiceRoleKey: $ref: ./components/common/security-schemes.yaml#/components/securitySchemes/ServiceRoleKey UserToken: $ref: ./components/common/security-schemes.yaml#/components/securitySchemes/UserToken parameters: BranchName: $ref: ./components/common/parameters.yaml#/components/parameters/BranchName BucketName: $ref: ./components/common/parameters.yaml#/components/parameters/BucketName Cursor: $ref: ./components/common/parameters.yaml#/components/parameters/Cursor EndingBefore: $ref: ./components/common/parameters.yaml#/components/parameters/EndingBefore DatabaseName: $ref: ./components/common/parameters.yaml#/components/parameters/DatabaseName DeploymentId: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentId FrontendId: $ref: ./components/common/parameters.yaml#/components/parameters/FrontendId FunctionId: $ref: ./components/common/parameters.yaml#/components/parameters/FunctionId Limit: $ref: ./components/common/parameters.yaml#/components/parameters/Limit LockKey: name: key in: path required: true description: Project-local lock name. schema: type: string minLength: 1 maxLength: 128 pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$' LockToken: name: X-Volcano-Lock-Token in: header required: true description: Opaque UUID generated once by the caller and retained for the lease lifetime. schema: type: string format: uuid LockRequestId: name: X-Volcano-Request-Id in: header required: true description: | UUID correlating this request across client and server logs. Repeat safety comes from the lock token, so a retry under a reused request ID still counts against the quota. schema: type: string format: uuid DeploymentOperation: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentOperation DeploymentOwnerId: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentOwnerId DeploymentOrder: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentOrder DeploymentResourceType: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentResourceType DeploymentStatus: $ref: ./components/common/parameters.yaml#/components/parameters/DeploymentStatus Offset: $ref: ./components/common/parameters.yaml#/components/parameters/Offset Page: $ref: ./components/common/parameters.yaml#/components/parameters/Page ProjectId: $ref: ./components/common/parameters.yaml#/components/parameters/ProjectId Search: $ref: ./components/common/parameters.yaml#/components/parameters/Search SchedulerId: $ref: ./components/common/parameters.yaml#/components/parameters/SchedulerId VariableName: $ref: ./components/common/parameters.yaml#/components/parameters/VariableName responses: BandwidthCapExceeded: description: | The platform user exceeded their billing-cycle bandwidth allowance (aggregate ingress + egress across owned projects). Enforcement is eventual: requests are rejected until the allowance increases or the next anniversary cycle begins. content: application/json: schema: $ref: '#/components/schemas/Error' DatabaseQueryCapExceeded: description: | The query was rejected by a billing-cycle allowance: either the owning platform user's bandwidth allowance (aggregate ingress + egress across owned projects) or their database-request allowance. Enforcement is eventual: queries are rejected until the allowance increases or the next anniversary cycle begins. The error message identifies the resource. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: AnonKey: $ref: ./components/common/schemas.yaml#/components/schemas/AnonKey AuthConfig: $ref: ./components/common/schemas.yaml#/components/schemas/AuthConfig AuthInsightsInterval: $ref: ./components/common/schemas.yaml#/components/schemas/AuthInsightsInterval AuthInsightsResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthInsightsResponse AuthInsightsSeriesPoint: $ref: ./components/common/schemas.yaml#/components/schemas/AuthInsightsSeriesPoint AuthInsightsSummary: $ref: ./components/common/schemas.yaml#/components/schemas/AuthInsightsSummary AuthInsightsWindow: $ref: ./components/common/schemas.yaml#/components/schemas/AuthInsightsWindow AuthHostedPage: $ref: ./components/common/schemas.yaml#/components/schemas/AuthHostedPage AuthPageAppearanceResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageAppearanceResponse AuthPageDensity: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageDensity AuthPageFont: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageFont AuthPageLayout: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageLayout AuthPageRadius: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageRadius AuthPageScale: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageScale AuthPageTheme: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPageTheme AuthHostedPageResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthHostedPageResponse AuthIdentity: $ref: ./components/common/schemas.yaml#/components/schemas/AuthIdentity AuthIdentitiesResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthIdentitiesResponse AuthMethodSummary: $ref: ./components/common/schemas.yaml#/components/schemas/AuthMethodSummary AuthMethodsResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthMethodsResponse AuthPasswordPolicy: $ref: ./components/common/schemas.yaml#/components/schemas/AuthPasswordPolicy AuthSession: $ref: ./components/common/schemas.yaml#/components/schemas/AuthSession AuthSignupResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthSignupResponse AuthTokenResponse: $ref: ./components/common/schemas.yaml#/components/schemas/AuthTokenResponse AuthUser: $ref: ./components/common/schemas.yaml#/components/schemas/AuthUser BanUserResponse: $ref: ./components/common/schemas.yaml#/components/schemas/BanUserResponse BatchFunctionDeployFailure: $ref: ./components/common/schemas.yaml#/components/schemas/BatchFunctionDeployFailure BatchFunctionDeployResponse: $ref: ./components/common/schemas.yaml#/components/schemas/BatchFunctionDeployResponse CompleteUploadSessionResponse: $ref: ./components/common/schemas.yaml#/components/schemas/CompleteUploadSessionResponse CreateDatabaseBranchRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateDatabaseBranchRequest CreateDatabaseRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateDatabaseRequest CreateEmailTemplateRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateEmailTemplateRequest CreateFrontendCustomDomainRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateFrontendCustomDomainRequest CreateFunctionSchedulerRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateFunctionSchedulerRequest CreateOAuthConfigRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateOAuthConfigRequest CreateProjectRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateProjectRequest CreateStorageBucketRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateStorageBucketRequest CreateStoragePolicyRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateStoragePolicyRequest CreateUploadSessionRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateUploadSessionRequest CreateUploadSessionResponse: $ref: ./components/common/schemas.yaml#/components/schemas/CreateUploadSessionResponse CreateVariableRequest: $ref: ./components/common/schemas.yaml#/components/schemas/CreateVariableRequest Database: $ref: ./components/common/schemas.yaml#/components/schemas/Database DatabaseBranch: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseBranch DatabaseBranchList: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseBranchList DatabaseBranchStorage: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseBranchStorage DatabaseSelectRequest: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseSelectRequest DatabaseInsertRequest: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseInsertRequest DatabaseUpdateRequest: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseUpdateRequest DatabaseDeleteRequest: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseDeleteRequest DatabaseQueryResult: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseQueryResult DatabaseStats: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseStats DatabaseQueryPerformanceResponse: $ref: ./components/common/schemas.yaml#/components/schemas/DatabaseQueryPerformanceResponse UpdateDatabaseBranchRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateDatabaseBranchRequest DeviceAuthorizationResponse: $ref: ./components/common/schemas.yaml#/components/schemas/DeviceAuthorizationResponse EmailTemplate: $ref: ./components/common/schemas.yaml#/components/schemas/EmailTemplate Error: $ref: ./components/common/schemas.yaml#/components/schemas/Error ImportProvider: type: string enum: [vercel] default: vercel x-enum-varnames: [ImportProviderVercel] ImportConnectStartResponse: type: object properties: authorization_url: type: string required: - authorization_url ImportConnection: type: object properties: id: type: string format: uuid provider: $ref: '#/components/schemas/ImportProvider' account_id: type: string account_name: type: string configuration_id: type: string granted_scopes: type: array items: type: string status: type: string expires_at: type: string format: date-time nullable: true last_authenticated_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - provider - account_id - account_name - configuration_id - granted_scopes - status - last_authenticated_at - created_at - updated_at ImportConnectionsResponse: type: object properties: connections: type: array items: $ref: '#/components/schemas/ImportConnection' required: - connections ImportSource: type: object properties: id: type: string name: type: string account_id: type: string framework: type: string required: - id - name - account_id - framework ImportSourcesResponse: type: object properties: sources: type: array items: $ref: '#/components/schemas/ImportSource' required: - sources ProjectImportTarget: type: string enum: [production] x-enum-varnames: [ProjectImportTargetProduction] ProjectImportDestinationMode: type: string enum: [create] x-enum-varnames: [ProjectImportDestinationCreate] ProjectImportDisposition: type: string enum: [automatic, manual, deferred, unsupported] x-enum-varnames: - ProjectImportDispositionAutomatic - ProjectImportDispositionManual - ProjectImportDispositionDeferred - ProjectImportDispositionUnsupported ProjectImportImpact: type: string enum: [none, warning, blocking] x-enum-varnames: - ProjectImportImpactNone - ProjectImportImpactWarning - ProjectImportImpactBlocking ProjectImportReadiness: type: string enum: [importable, needs_input, blocked] x-enum-varnames: - ProjectImportReadinessImportable - ProjectImportReadinessNeedsInput - ProjectImportReadinessBlocked ProjectImportActionCode: type: string enum: [project.create, git.connect, frontend.configure, variable.set] x-enum-varnames: - ProjectImportActionProjectCreate - ProjectImportActionGitConnect - ProjectImportActionFrontendConfigure - ProjectImportActionVariableSet ProjectImportResourceKind: type: string enum: [project, git_repository, frontend, variable, domain] x-enum-varnames: - ProjectImportResourceProject - ProjectImportResourceGitRepository - ProjectImportResourceFrontend - ProjectImportResourceVariable - ProjectImportResourceDomain ProjectImportPreflightRequest: type: object properties: connection_id: type: string format: uuid source_id: type: string minLength: 1 project_name: type: string maxLength: 255 pattern: '^[A-Za-z0-9_-]+$' target: $ref: '#/components/schemas/ProjectImportTarget' confirm_environment_variable_read: type: boolean default: false description: >- Set to true only after the user confirms an immediately preceding disclosure that the Vercel Integration grant permits reads and writes, while this preflight reads production variable values only. When false or omitted, preflight reads variable metadata only and reports readable values as manual input. required: - connection_id - source_id - project_name - target ProjectImportStartRequest: type: object properties: connection_id: type: string format: uuid source_id: type: string minLength: 1 maxLength: 255 project_name: type: string maxLength: 255 pattern: '^[A-Za-z0-9_-]+$' target: $ref: '#/components/schemas/ProjectImportTarget' confirm_environment_variable_read: type: boolean enum: [true] preflight_fingerprint: type: string pattern: '^sha256:[0-9a-f]{64}$' required: - connection_id - source_id - project_name - target - confirm_environment_variable_read - preflight_fingerprint ProjectImportRunStatus: type: string enum: [pending, running, succeeded, failed, superseded] x-enum-varnames: - ProjectImportRunStatusPending - ProjectImportRunStatusRunning - ProjectImportRunStatusSucceeded - ProjectImportRunStatusFailed - ProjectImportRunStatusSuperseded ProjectImportRun: type: object properties: id: type: string provider: $ref: '#/components/schemas/ImportProvider' source_id: type: string destination_project_name: type: string resource: $ref: '#/components/schemas/ResourceReference' deployment: $ref: '#/components/schemas/DeploymentReference' status: $ref: '#/components/schemas/ProjectImportRunStatus' error_code: type: string error_message: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - provider - source_id - destination_project_name - resource - deployment - status - created_at - updated_at ProjectImportDestination: type: object properties: mode: $ref: '#/components/schemas/ProjectImportDestinationMode' project_name: type: string target: $ref: '#/components/schemas/ProjectImportTarget' required: - mode - project_name - target ProjectImportResource: type: object properties: kind: $ref: '#/components/schemas/ProjectImportResourceKind' name: type: string source_id: type: string minLength: 1 description: Stable provider identifier for a scoped source resource. scope: type: string minLength: 1 description: URL-encoded source scope, including target, branch, and custom environment identifiers. required: - kind - name ProjectImportAction: type: object properties: code: $ref: '#/components/schemas/ProjectImportActionCode' resource: $ref: '#/components/schemas/ProjectImportResource' disposition: $ref: '#/components/schemas/ProjectImportDisposition' required: - code - resource - disposition ProjectImportFinding: type: object properties: code: type: string pattern: '^(vercel|volcano|import)\.[a-z0-9_]+$' resource: $ref: '#/components/schemas/ProjectImportResource' disposition: $ref: '#/components/schemas/ProjectImportDisposition' impact: $ref: '#/components/schemas/ProjectImportImpact' message: type: string remediation: type: string required: - code - resource - disposition - impact - message - remediation ProjectImportSummary: type: object properties: automatic: type: integer minimum: 0 manual: type: integer minimum: 0 deferred: type: integer minimum: 0 unsupported: type: integer minimum: 0 warnings: type: integer minimum: 0 blocking: type: integer minimum: 0 required: - automatic - manual - deferred - unsupported - warnings - blocking ProjectImportReport: type: object properties: schema_version: type: string provider: $ref: '#/components/schemas/ImportProvider' source: $ref: '#/components/schemas/ImportSource' destination: $ref: '#/components/schemas/ProjectImportDestination' actions: type: array items: $ref: '#/components/schemas/ProjectImportAction' findings: type: array items: $ref: '#/components/schemas/ProjectImportFinding' summary: $ref: '#/components/schemas/ProjectImportSummary' readiness: $ref: '#/components/schemas/ProjectImportReadiness' source_fingerprint: type: string capability_fingerprint: type: string fingerprint: type: string generated_at: type: string format: date-time required: - schema_version - provider - source - destination - actions - findings - summary - readiness - source_fingerprint - capability_fingerprint - fingerprint - generated_at GitConnection: type: object properties: id: type: string format: uuid provider: type: string provider_user_id: type: string provider_login: type: string status: type: string last_authenticated_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - provider - provider_user_id - provider_login - status - last_authenticated_at - created_at - updated_at GitConnectStartResponse: type: object properties: authorization_url: type: string required: - authorization_url GitConnectionsResponse: type: object properties: connections: type: array items: $ref: '#/components/schemas/GitConnection' required: - connections GitInstallation: type: object properties: id: type: integer format: int64 account_login: type: string account_type: type: string repository_selection: type: string required: - id - account_login - account_type - repository_selection GitInstallationsResponse: type: object properties: installations: type: array items: $ref: '#/components/schemas/GitInstallation' required: - installations GitRepository: type: object properties: id: type: integer format: int64 description: Stable GitHub repository id (repository.id), unchanged by renames. full_name: type: string default_branch: type: string private: type: boolean required: - id - full_name - default_branch - private GitRepositoriesResponse: type: object properties: repositories: type: array items: $ref: '#/components/schemas/GitRepository' required: - repositories ProjectGitConnection: type: object properties: repo_installation_id: type: integer format: int64 repo_id: type: integer format: int64 description: Stable GitHub repository id (repository.id), the authoritative binding. repo_full_name: type: string root_directory: type: string production_branch: type: string description: >- The branch a push must land on to deploy. Follows the repository's GitHub default branch unless the project set its own, which a default-branch rename on GitHub then leaves alone. updated_at: type: string format: date-time required: - repo_installation_id - repo_id - repo_full_name - root_directory - production_branch - updated_at ProjectGitDeploySettings: type: object description: >- A project's GitHub auto-deploy settings: what a push to the connected repo's production branch deploys. All settings are default-off. properties: auto_deploy_enabled: type: boolean description: Whether a production-branch push triggers a deployment. deploy_functions: type: boolean description: Whether the repo's functions are deployed on push. frontend_name: type: string description: >- Name of the frontend to build and deploy on push. Omitted when no frontend is deployed. Resolved at deploy time; need not exist yet. frontend_app_root: type: string description: App root (subdirectory) the frontend builds from. Omitted for the repo root. updated_at: type: string format: date-time required: - auto_deploy_enabled - deploy_functions - updated_at UpdateProjectGitDeploySettingsRequest: type: object description: Full replace of a project's Git auto-deploy settings. properties: auto_deploy_enabled: type: boolean deploy_functions: type: boolean frontend_name: type: string description: Frontend to deploy on push. Omit or empty to deploy no frontend. frontend_app_root: type: string description: >- App root the frontend builds from. Requires frontend_name; omit for the repo root. required: - auto_deploy_enabled - deploy_functions ProjectLockLeaseRequest: type: object additionalProperties: false properties: ttl_seconds: type: integer minimum: 5 maximum: 7776000 description: | Lease duration in seconds, from 5 seconds through 90 days, measured from when the request is served. Renew before it elapses. A renewal sets the new expiry outright, so a shorter TTL shortens the lease. Renewals cannot extend an acquisition beyond its absolute 90-day deadline. required: - ttl_seconds ProjectLockLease: type: object additionalProperties: false properties: expires_at: type: string format: date-time description: Advisory lease expiry timestamp in UTC. fencing_token: type: integer format: int64 description: | Monotonically increasing token for this acquisition. It rises whenever the lock changes hands and stays the same across renewals of one lease. Pass it to the resource you are protecting and reject any write carrying a token lower than the highest already seen; that is what stops a displaced holder from writing after its lease lapsed. required: - expires_at - fencing_token ProjectLockState: type: object additionalProperties: false properties: held: type: boolean description: | Whether the lock is unavailable right now. False means an acquire would succeed. It remains true during the brief grace window after expiry. expires_at: type: string format: date-time description: Advisory lease expiry timestamp in UTC. Present only when held. fencing_token: type: integer format: int64 description: Current holder's fencing token. Present only when held. required: - held SetProjectGitProductionBranchRequest: type: object properties: production_branch: type: string minLength: 1 maxLength: 255 description: >- The branch a push must land on to deploy. Validated as a Git branch name only — it does not have to exist yet. required: - production_branch ConnectProjectGitRequest: type: object properties: connection_id: type: string format: uuid description: The caller's user_git_connections row (see /user/git/connections). installation_id: type: integer format: int64 repository_id: type: integer format: int64 description: >- Stable GitHub repository id (repository.id), the preferred selector. Either repository_id or repo_full_name is required; when both are given they must identify the same live repository. repo_full_name: type: string deprecated: true description: >- Deprecated selector kept for a compatibility window; prefer repository_id. Either repository_id or repo_full_name is required. root_directory: type: string description: Monorepo subdirectory the project builds from. Omit for the repo root. production_branch: type: string maxLength: 255 description: >- The branch a push must land on to deploy, with three cases, because this is a full replace and a read-modify-write client sends back whatever it read. Omit it to follow the repository's GitHub default branch, which also discards a branch set earlier. Send back the branch the project already deploys from, when that is the repository's default, and nothing changes either way — a project pinned to that branch stays pinned. Sending the default branch when the project deploys from something else returns it to following the default, including on a rebind, where a pin describes a branch chosen for the repository being left. Any other branch becomes the project's own choice, exempt from later default-branch renames. Validated as a Git branch name only: it does not have to exist yet, so a project can be pointed at a branch about to be pushed. Changing repository and naming a branch other than the new repository's default in one request is refused with 400, because the branch named is almost always the previous repository's, echoed back — connect first, then set the branch. required: - connection_id - installation_id Frontend: $ref: ./components/common/schemas.yaml#/components/schemas/Frontend FrontendCustomDomainResponse: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendCustomDomainResponse FrontendCustomDomainTLSConfig: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendCustomDomainTLSConfig FrontendDeployment: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendDeployment FrontendDomainRoutingRecord: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendDomainRoutingRecord FrontendDomainVerificationRecord: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendDomainVerificationRecord FrontendUsageDailyEntry: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendUsageDailyEntry FrontendUsageData: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendUsageData FrontendUsageHistoryResponse: $ref: ./components/common/schemas.yaml#/components/schemas/FrontendUsageHistoryResponse Function: $ref: ./components/common/schemas.yaml#/components/schemas/Function FunctionDeployment: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionDeployment FunctionInvocationRequest: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionInvocationRequest FunctionInvocationResponse: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionInvocationResponse LogActivityBucket: $ref: ./components/common/schemas.yaml#/components/schemas/LogActivityBucket LogActivityRequest: $ref: ./components/common/schemas.yaml#/components/schemas/LogActivityRequest LogActivityResponse: $ref: ./components/common/schemas.yaml#/components/schemas/LogActivityResponse LogSearchRequest: $ref: ./components/common/schemas.yaml#/components/schemas/LogSearchRequest LogStreamRequest: $ref: ./components/common/schemas.yaml#/components/schemas/LogStreamRequest LogSearchEvent: $ref: ./components/common/schemas.yaml#/components/schemas/LogSearchEvent LogSearchResponse: $ref: ./components/common/schemas.yaml#/components/schemas/LogSearchResponse FunctionRegion: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionRegion FunctionRuntimeOption: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionRuntimeOption FunctionRuntimesResponse: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionRuntimesResponse FunctionScheduler: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionScheduler FunctionSchedulerListResponse: $ref: ./components/common/schemas.yaml#/components/schemas/FunctionSchedulerListResponse HostedAuthPageType: $ref: ./components/common/schemas.yaml#/components/schemas/HostedAuthPageType HostedLoginEmailCheckRequest: $ref: ./components/common/schemas.yaml#/components/schemas/HostedLoginEmailCheckRequest HostedLoginEmailCheckResponse: $ref: ./components/common/schemas.yaml#/components/schemas/HostedLoginEmailCheckResponse HostedLoginOptionsResponse: $ref: ./components/common/schemas.yaml#/components/schemas/HostedLoginOptionsResponse HostedRenderablePageType: $ref: ./components/common/schemas.yaml#/components/schemas/HostedRenderablePageType LogEvent: $ref: ./components/common/schemas.yaml#/components/schemas/LogEvent LiveLogLevel: $ref: ./components/common/schemas.yaml#/components/schemas/LiveLogLevel MetricUsageData: $ref: ./components/common/schemas.yaml#/components/schemas/MetricUsageData OAuthConfig: $ref: ./components/common/schemas.yaml#/components/schemas/OAuthConfig OAuthErrorResponse: $ref: ./components/common/schemas.yaml#/components/schemas/OAuthErrorResponse PaginatedAuthUsers: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedAuthUsers PaginatedDatabases: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedDatabases PaginatedFrontendDeployments: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedFrontendDeployments PaginatedFrontends: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedFrontends PaginatedFunctionDeployments: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedFunctionDeployments PaginatedFunctions: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedFunctions PaginatedProjectCustomDomains: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedProjectCustomDomains PaginatedProjectDeployments: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedProjectDeployments PaginatedProjects: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedProjects PaginatedServiceKeys: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedServiceKeys PaginatedStorageBuckets: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedStorageBuckets PaginatedVariables: $ref: ./components/common/schemas.yaml#/components/schemas/PaginatedVariables PlatformExchangeResponse: $ref: ./components/common/schemas.yaml#/components/schemas/PlatformExchangeResponse Project: $ref: ./components/common/schemas.yaml#/components/schemas/Project ProjectConfig: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfig ProjectConfigApplyResult: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigApplyResult ProjectConfigApplyResultEntry: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigApplyResultEntry ProjectConfigApplySummary: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigApplySummary ProjectConfigAuth: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuth ProjectConfigAuthCORS: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthCORS ProjectConfigAuthEmail: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthEmail ProjectConfigAuthEmailFrom: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthEmailFrom ProjectConfigAuthEmailPasswordProvider: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthEmailPasswordProvider ProjectConfigAuthEmailSMTP: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthEmailSMTP ProjectConfigAuthEmailVerification: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthEmailVerification ProjectConfigAuthManagedPages: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthManagedPages ProjectConfigAuthPassword: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthPassword ProjectConfigAuthPasswordReset: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthPasswordReset ProjectConfigAuthProviders: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthProviders ProjectConfigAuthRateLimits: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthRateLimits ProjectConfigAuthRedirects: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthRedirects ProjectConfigAuthSessions: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthSessions ProjectConfigAuthSignup: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthSignup ProjectConfigAuthTokens: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigAuthTokens ProjectConfigBucket: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigBucket ProjectConfigBucketPolicy: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigBucketPolicy ProjectConfigCustomDomain: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigCustomDomain ProjectConfigDatabase: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigDatabase ProjectConfigEmailTemplate: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigEmailTemplate ProjectConfigEmailTemplates: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigEmailTemplates ProjectConfigFrontend: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigFrontend ProjectConfigFunction: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigFunction ProjectConfigHostedPage: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigHostedPage ProjectConfigHostedPages: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigHostedPages PreviewAuthPageRequest: $ref: ./components/common/schemas.yaml#/components/schemas/PreviewAuthPageRequest PreviewAuthPageResponse: $ref: ./components/common/schemas.yaml#/components/schemas/PreviewAuthPageResponse ProjectConfigMissingResource: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigMissingResource ProjectConfigOAuthProvider: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigOAuthProvider ProjectConfigProject: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigProject ProjectConfigRealtime: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigRealtime ProjectConfigScheduler: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigScheduler ProjectConfigSkippedResource: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigSkippedResource ProjectConfigValidationError: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigValidationError ProjectConfigValidationErrorResponse: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigValidationErrorResponse ProjectConfigVariable: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectConfigVariable ProjectHealthResource: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthResource ResourceReference: $ref: ./components/common/schemas.yaml#/components/schemas/ResourceReference DeploymentReference: $ref: ./components/common/schemas.yaml#/components/schemas/DeploymentReference ProjectHealthScope: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthScope ProjectHealthResponse: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthResponse ProjectHealthStatus: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthStatus ProjectHealthDataStatus: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthDataStatus ProjectHealthCategory: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthCategory ProjectHealthEvidence: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthEvidence ProjectHealthCheck: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectHealthCheck ProjectMetricsDataStatus: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsDataStatus ProjectMetricsDimensions: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsDimensions ProjectMetricsGroupBy: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsGroupBy ProjectMetricsMetric: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsMetric ProjectMetricsQuery: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsQuery ProjectMetricsQueryRequest: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsQueryRequest ProjectMetricsQueryResponse: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsQueryResponse ProjectMetricsQueryTimeRange: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsQueryTimeRange ProjectMetricsResult: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsResult ProjectMetricsUnit: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsUnit ProjectMetricsValue: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsValue ProjectMetricsWindow: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectMetricsWindow ProjectFrontendCustomDomain: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectFrontendCustomDomain ProjectDeployment: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectDeployment ProjectDeploymentResource: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectDeploymentResource ProjectDeploymentSummary: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectDeploymentSummary ProjectUsageResponse: $ref: ./components/common/schemas.yaml#/components/schemas/ProjectUsageResponse RealtimeConfig: $ref: ./components/common/schemas.yaml#/components/schemas/RealtimeConfig RealtimePlanLimits: $ref: ./components/common/schemas.yaml#/components/schemas/RealtimePlanLimits RealtimeStats: $ref: ./components/common/schemas.yaml#/components/schemas/RealtimeStats ResolveFunctionResponse: $ref: ./components/common/schemas.yaml#/components/schemas/ResolveFunctionResponse ScheduleRequest: $ref: ./components/common/schemas.yaml#/components/schemas/ScheduleRequest ServiceKey: $ref: ./components/common/schemas.yaml#/components/schemas/ServiceKey StorageBucket: $ref: ./components/common/schemas.yaml#/components/schemas/StorageBucket StorageCopyRequest: $ref: ./components/common/schemas.yaml#/components/schemas/StorageCopyRequest StorageListResponse: $ref: ./components/common/schemas.yaml#/components/schemas/StorageListResponse StorageMoveRequest: $ref: ./components/common/schemas.yaml#/components/schemas/StorageMoveRequest StorageObject: $ref: ./components/common/schemas.yaml#/components/schemas/StorageObject StorageObjectWithBucket: $ref: ./components/common/schemas.yaml#/components/schemas/StorageObjectWithBucket StoragePolicy: $ref: ./components/common/schemas.yaml#/components/schemas/StoragePolicy StorageStats: $ref: ./components/common/schemas.yaml#/components/schemas/StorageStats StorageVisibilityRequest: $ref: ./components/common/schemas.yaml#/components/schemas/StorageVisibilityRequest UnbanUserResponse: $ref: ./components/common/schemas.yaml#/components/schemas/UnbanUserResponse TestEmailRequest: $ref: ./components/common/schemas.yaml#/components/schemas/TestEmailRequest TestEmailResponse: $ref: ./components/common/schemas.yaml#/components/schemas/TestEmailResponse UpdateAuthConfigRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateAuthConfigRequest UpdateAuthHostedPageRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateAuthHostedPageRequest UpdateAuthPageLayoutRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateAuthPageLayoutRequest UpdateAuthPageThemeRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateAuthPageThemeRequest UpdateDatabaseTypeRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateDatabaseTypeRequest UpdateEmailTemplateRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateEmailTemplateRequest UpdateFunctionRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateFunctionRequest UpdateFunctionSchedulerRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateFunctionSchedulerRequest UpdateOAuthConfigRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateOAuthConfigRequest UpdateProjectRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateProjectRequest UpdateRealtimeConfigRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateRealtimeConfigRequest UpdateStorageBucketRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateStorageBucketRequest UpdateVariableRequest: $ref: ./components/common/schemas.yaml#/components/schemas/UpdateVariableRequest UploadSessionPart: $ref: ./components/common/schemas.yaml#/components/schemas/UploadSessionPart UploadSessionStatusResponse: $ref: ./components/common/schemas.yaml#/components/schemas/UploadSessionStatusResponse UsageDataPoint: $ref: ./components/common/schemas.yaml#/components/schemas/UsageDataPoint Variable: $ref: ./components/common/schemas.yaml#/components/schemas/Variable