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 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: 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: 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: /projects: get: tags: - Projects summary: List all projects for authenticated user operationId: listProjects security: - UserToken: [] parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedProjects' 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) content: application/json: schema: $ref: '#/components/schemas/Error' delete: tags: - Projects summary: Delete a project description: | Starts asynchronous project deletion. The project remains visible with `status: deleting` until cleanup finishes, then it returns 404 and no longer appears in project lists. 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 S3 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 S3 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 S3 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}/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' /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' 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}/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' 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 operationId: listFunctions security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' 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 Lambda 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. New functions and existing function code updates return a Function resource with `status: provisioning` while the Step Functions workflow is running, then transition to `active` or `failed`. 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 5,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: '200': description: Existing function updated and update workflow started content: application/json: schema: $ref: '#/components/schemas/Function' '201': description: Function created and deployment workflow started 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' '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: | Starts asynchronous function deletion. The function remains visible with `status: deleting` until cleanup finishes, then 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 '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 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 monthly bandwidth cap (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' 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 content: application/json: schema: $ref: '#/components/schemas/FunctionInvocationResponse' /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 `levels`, `regions`, `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. Do not send `q`, `cursor`, or `end_time`; use `/logs/search` for text search and 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 Lambda 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' 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 operationId: listFrontends security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' 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. Create, update, and redeploy responses return `status: provisioning` while the frontend workflow is running, then transition to `active` or `failed`. 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.20 (`^18.18.0 || ^19.8.0 || >=20.0.0`) and Next 16.2.10 (`>=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 Lambda 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 5,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 and redeployment workflow started 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' '401': description: Unauthorized - invalid or missing token 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' '404': description: Project not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict - frontend deployment already in progress 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' '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' delete: tags: - Frontends summary: Delete a frontend description: | Starts asynchronous frontend deletion. The frontend remains visible with `status: deleting` until cleanup finishes, then 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 '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' '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. The frontend remains visible with `status: provisioning` while the workflow runs, then transitions to `active` or `failed`. operationId: redeployFrontend security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FrontendId' responses: '200': description: Frontend redeploy started content: application/json: schema: $ref: '#/components/schemas/Frontend' '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' '409': description: Conflict - frontend deployment already in progress 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 content: application/json: schema: $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 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' 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: '200': description: Custom domain already configured with same hostname content: application/json: schema: $ref: '#/components/schemas/FrontendCustomDomainResponse' '201': description: Custom domain provisioning started 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' 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 operationId: listDatabases security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Limit' 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 its backing Neon project. When the Neon project is removed synchronously the database row is deleted and the response is `204`. If the Neon project cannot be deleted right away, the database row is retained (status `deleting`) and its teardown is handed to the background reconciler, which retries the Neon deletion and removes the row once Neon is gone; in that case the response is `202`. The database row is never dropped while its Neon project still exists, so a Neon project is never orphaned without a record to retry from. operationId: deleteDatabase security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/DatabaseName' responses: '202': description: | Deletion accepted and in progress. The Neon project 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 '204': description: Database deleted (Neon project removed synchronously) /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 Neon 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_`. example: vpg_qv3Y4GQwHcklV4G76ZcKhZW-rmZLQktEORHnGqU0Bpk connection_string: type: string description: Updated pgproxy connection string using Volcano-managed credentials. example: postgresql://volcano_client_11111111-1111-1111-1111-111111111111:vpg_qv3Y4GQwHcklV4G76ZcKhZW-rmZLQktEORHnGqU0Bpk@database.volcano.dev:5432/mydb?sslmode=require&application_name=volcano_full_access /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: type: object properties: data: type: array items: type: object additionalProperties: true description: Result rows of the probe query count: type: integer description: Number of rows returned 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 Lambda functions with direct SQL operationId: queryDatabaseSelect security: - AuthUserAccessToken: [] parameters: - $ref: '#/components/parameters/DatabaseName' requestBody: required: true content: application/json: schema: type: object required: - table properties: table: type: string description: Table name to query example: posts select: type: array items: type: string description: Columns to select (omit for *) example: - id - title - content - created_at filters: type: array items: type: object required: - column - operator - value properties: column: type: string example: status operator: type: string enum: - eq - neq - gt - gte - lt - lte - like - ilike - is - in example: eq description: | Filter operators: - eq: equals (=) - neq: not equals (<>) - gt: greater than (>) - gte: greater than or equal (>=) - lt: less than (<) - lte: less than or equal (<=) - like: pattern match (LIKE) - ilike: case-insensitive pattern match (ILIKE) - is: IS NULL / IS NOT NULL - in: IN array value: oneOf: - type: string nullable: true - type: number - type: boolean - type: array description: Array of values for IN (...) queries items: oneOf: - type: string - type: number - type: boolean example: published description: WHERE conditions (combined with AND) example: - column: status operator: eq value: published - column: views operator: gt value: 100 order: type: array items: type: object required: - column properties: column: type: string example: created_at ascending: type: boolean default: true example: false nulls_first: type: boolean default: false description: ORDER BY clauses example: - column: created_at ascending: false limit: type: integer minimum: 1 maximum: 1000 description: Maximum rows to return example: 10 offset: type: integer minimum: 0 description: Number of rows to skip (for pagination) example: 0 responses: '200': description: Query successful content: application/json: schema: type: object properties: data: type: array items: type: object additionalProperties: true description: Array of result rows (automatically filtered by RLS) count: type: integer description: Number of rows returned 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: type: object required: - table - values properties: table: type: string description: Table name example: posts values: type: object additionalProperties: true description: Column values to insert example: title: My New Post content: This is the content status: draft responses: '200': description: Insert successful content: application/json: schema: type: object properties: data: type: array items: type: object additionalProperties: true description: Inserted row(s) with all columns count: type: integer 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 - database does not belong to this project 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: type: object required: - table - values - filters properties: table: type: string description: Table name example: posts values: type: object additionalProperties: true description: Column values to update example: title: Updated Title status: published filters: type: array minItems: 1 items: type: object required: - column - operator - value properties: column: type: string operator: type: string enum: - eq - neq - gt - gte - lt - lte - like - ilike - is - in value: oneOf: - type: string - type: number - type: boolean description: | WHERE conditions for which rows to update. At least one filter is required; a filterless update is rejected to avoid rewriting every row. example: - column: id operator: eq value: post-uuid responses: '200': description: Update successful content: application/json: schema: type: object properties: data: type: array items: type: object additionalProperties: true description: Updated row(s). Empty if RLS blocked the update. count: type: integer 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 - database does not belong to this project 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: type: object required: - table - filters properties: table: type: string description: Table name example: posts filters: type: array minItems: 1 items: type: object required: - column - operator - value properties: column: type: string operator: type: string enum: - eq - neq - gt - gte - lt - lte - like - ilike - is - in value: oneOf: - type: string - type: number - type: boolean description: WHERE conditions (required for safety) example: - column: id operator: eq value: post-uuid responses: '200': description: Delete successful content: application/json: schema: type: object properties: data: type: array items: type: object additionalProperties: true description: Deleted row(s). Empty if RLS blocked the delete. count: type: integer 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 - database does not belong to this project 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/regions: get: tags: - Databases summary: List platform-supported AWS-backed regions for database provisioning operationId: listDatabaseRegions description: | Returns the AWS-backed Neon regions enabled for this platform environment. This is a public endpoint that doesn't require authentication. responses: '200': description: List of platform-supported AWS-backed 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 AWS regions for function deployment operationId: listFunctionRegions security: [] description: | Returns the configured AWS 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' /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 minLength: 6 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 or anon key lacks signup permission '429': description: Rate limit exceeded /auth/signin: post: tags: - Authentication summary: Sign in an auth user description: Authenticate with email and password. Requires anon key. Project is identified via the anon key. operationId: authSignin security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string password: type: string 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, or account banned/deleted '403': description: | Forbidden - Anon key lacks signin permission '429': description: Rate limit exceeded /auth/refresh: post: tags: - Authentication summary: Refresh access token description: Get a new access token using refresh token. Requires anon key. Project is identified via the anon key. operationId: authRefresh security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - refresh_token properties: refresh_token: type: string 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' '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 anon key. Project is identified via the anon key. operationId: authLogout security: - AnonKey: [] requestBody: required: true content: application/json: schema: type: object required: - refresh_token properties: refresh_token: type: string 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 minLength: 6 responses: '200': description: Password reset successful content: application/json: schema: type: object properties: message: type: string '400': description: Password doesn't meet requirements '401': description: Invalid or expired token /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 '400': description: Missing confirmation token in request body '401': description: Invalid or expired token /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 minLength: 6 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 '409': description: Email already in use /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' '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' '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`. 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 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 '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 minLength: 6 user_metadata: type: object additionalProperties: true 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' /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. 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' '404': description: Method not found 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' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaginatedAuthUsers' /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. 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 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 '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. 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' /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 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' /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 current saved HTML/CSS for the page type. If no custom page exists yet, returns the default template for that page type. 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/hosted/{pageType}: get: tags: - Auth Configuration summary: Render managed reset-password page description: | Public HTML endpoint for the managed reset-password page. 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 '404': description: Managed pages disabled '429': description: Rate limit exceeded /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 /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 /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). The session tokens are appended to this URL's fragment on success. If the URL carries a `vh_state` query parameter (the client SDK's one-time nonce), it is moved into the fragment as `state` so the SDK can bind the returned session to the flow it initiated (login-CSRF defense). responses: '307': description: Redirect to OAuth provider '400': description: OAuth provider is disabled for this project '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 content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '201': description: New user created and signed in content: application/json: schema: $ref: '#/components/schemas/AuthTokenResponse' '409': description: Email already exists (requires linking) /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' /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 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 responses: '200': description: Authorization URL generated content: application/json: schema: type: object properties: authorization_url: type: string '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 is the raw JSON response from the provider's API. 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 additionalProperties: true description: Raw response from the OAuth provider's API '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' '502': description: Provider API error content: application/json: schema: $ref: '#/components/schemas/Error' /projects/{id}/anon-keys: get: tags: - Anon Keys summary: List anon keys operationId: listAnonKeys security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: List of anon keys content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AnonKey' 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.signup - auth.signin - auth.refresh - auth.logout - auth.password_reset - auth.confirm_email - auth.resend_confirmation - storage.upload - storage.download - storage.list - storage.delete - realtime.connect - realtime.subscribe - realtime.publish - 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' 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. **WARNING:** Service keys bypass all RLS policies! Store securely and NEVER expose in frontend code. 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", "storage.download"]) to restrict the key; "*" grants everything. Scope enforcement currently applies to function invocation and storage object operations; other service-key routes are not yet gated by scope. example: - functions.invoke - storage.upload - storage.download - storage.list - storage.delete 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. Any services using this key will immediately lose access. 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' /projects/{id}/storage/buckets: get: tags: - Storage Buckets summary: List all storage buckets in a project operationId: listStorageBuckets security: - UserToken: [] parameters: - $ref: '#/components/parameters/ProjectId' responses: '200': description: List of storage buckets content: application/json: schema: type: array items: $ref: '#/components/schemas/StorageBucket' 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 /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 /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 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 /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' /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/{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' /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: '200': description: Resumable upload completed (when X-Upload-Complete=true) content: application/json: schema: $ref: '#/components/schemas/CompleteUploadSessionResponse' '201': description: File uploaded or session created content: application/json: schema: oneOf: - $ref: '#/components/schemas/StorageObject' - $ref: '#/components/schemas/CreateUploadSessionResponse' '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. - 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 S3 access 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: Only file owner or service key can change visibility '404': description: Object not found /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: 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: type: http scheme: bearer bearerFormat: JWT description: | Project-specific public key for frontend authentication. Required for signup, signin, refresh, and logout endpoints. Get from Project Settings → Authentication → Anon Keys. Safe to expose in frontend code (scoped to project, limited permissions). AuthUserAccessToken: type: http scheme: bearer bearerFormat: JWT description: | Auth user access token obtained from signup/signin. Used for authenticated function invocation and user profile access. Functions invoked with access tokens receive user context in event.__volcano_auth. Expires after configured lifetime (default: 1 hour). ServiceRoleKey: type: http scheme: bearer bearerFormat: JWT description: | Service role key for admin operations. **WARNING:** Bypasses Row-Level Security - backend use only! Create via POST /projects/{id}/service-keys. Used for function invocation with full database access. UserToken: type: http scheme: bearer bearerFormat: JWT description: | Platform user token from the Management API. Required for project management operations. Obtain via POST /tokens in Management API (port 8001). parameters: BucketName: name: bucketName in: path required: true schema: type: string pattern: ^[a-zA-Z0-9_-]+$ minLength: 1 maxLength: 64 description: Storage bucket name DatabaseName: name: databaseName in: path required: true schema: type: string pattern: ^[a-z0-9_]+$ maxLength: 64 description: Database name (unique within project, lowercase letters, numbers, and underscores only) DeploymentId: name: deploymentId in: path required: true schema: type: string format: uuid description: Frontend deployment ID FrontendId: name: frontendId in: path required: true schema: type: string format: uuid description: Frontend ID FunctionId: name: functionId in: path required: true schema: type: string format: uuid description: Function ID Limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of items per page (max 100) Page: name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Page number (1-indexed) ProjectId: name: id in: path required: true schema: type: string format: uuid description: Project ID SchedulerId: name: schedulerId in: path required: true schema: type: string format: uuid description: Function scheduler ID VariableName: name: name in: path required: true schema: type: string minLength: 1 maxLength: 256 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ description: Variable name responses: BandwidthCapExceeded: description: | The platform user exceeded their monthly bandwidth cap (aggregate ingress + egress across owned projects). Enforcement is eventual: requests are rejected until the cap increases (plan/override) or the calendar-month meter resets. content: application/json: schema: $ref: '#/components/schemas/Error' DatabaseQueryCapExceeded: description: | The query was rejected by a monthly usage cap: either the platform user's bandwidth cap (aggregate ingress + egress across owned projects) or the project's monthly database-request cap. Enforcement is eventual: queries are rejected until the relevant cap increases (plan/override) or the calendar-month meter resets. The error message identifies which cap. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: AnonKey: type: object properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string key_value: type: string description: JWT token - use this in frontend Authorization header permissions: type: array items: type: string description: | Permissions granted to this anon key. 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 example: - auth.signup - auth.signin - auth.refresh - auth.logout is_default: type: boolean description: Whether this is the project's configured default anon key. Only one key per project can be default. created_at: type: string format: date-time required: - id - name - key_value AuthConfig: type: object properties: project_id: type: string format: uuid access_token_lifetime: type: integer description: Access token lifetime in seconds default: 3600 refresh_token_lifetime: type: integer description: Refresh token lifetime in seconds default: 2592000 inactivity_timeout: type: integer description: Force re-login after inactivity (seconds, 0=never) default: 0 max_session_duration: type: integer description: Force re-login after duration (seconds, 0=never) default: 0 min_password_length: type: integer default: 6 require_uppercase: type: boolean default: false require_lowercase: type: boolean default: false require_numbers: type: boolean default: false require_special_chars: type: boolean default: false enable_signup: type: boolean description: Master switch - allow new user signups via ANY provider default: true enable_email_password: type: boolean description: Enable email/password authentication as a provider default: true rate_limit_signup: type: integer description: Signups per hour per IP default: 100 rate_limit_signin: type: integer description: Signins per hour per IP default: 100 rate_limit_token_refresh: type: integer description: Refreshes per hour per IP default: 1000 cors_enabled: type: boolean default: false cors_allowed_origins: type: array items: type: string example: - https://myapp.com - http://localhost:3000 enable_anonymous_signins: type: boolean description: Allow creating users without email/password default: false platform_token_ttl: type: integer description: TTL in seconds for platform tokens minted via `/auth/platform/exchange` default: 2592000 allow_password_reset: type: boolean description: Enable forgot password flow default: true password_reset_timeout: type: integer description: Recovery token expiry in seconds default: 3600 max_password_history: type: integer description: Number of previous passwords to remember (0=disabled) default: 0 cors_allow_credentials: type: boolean description: Allow credentials in CORS requests default: true cors_max_age: type: integer description: CORS preflight cache duration (seconds) default: 86400 email_enabled: type: boolean description: Enable transactional email sending (confirmation, reset, change notifications). Must be true when require_email_confirmation is true. default: false email_from_address: type: string email_from_name: type: string smtp_host: type: string smtp_port: type: integer default: 587 smtp_username: type: string smtp_password: type: string format: password description: SMTP password. Stored encrypted at rest (AES-256-GCM); returned decrypted only to the authenticated project owner. smtp_use_tls: type: boolean default: true email_confirmation_subject: type: string email_password_reset_subject: type: string email_password_changed_subject: type: string managed_auth_enabled: type: boolean description: Enables project-hosted managed auth pages. default: false post_auth_redirect_url: type: string description: Default redirect target after successful hosted auth. allowed_redirect_urls: type: array description: Redirect allowlist used to validate post_auth_redirect_url and post_logout_redirect_url. items: type: string post_logout_redirect_url: type: string description: Redirect target after logout from hosted pages. device_verification_url: type: string description: | Optional override for the device-authorization verification page. When set, POST /auth/device/authorize returns this URL (with the user_code) as verification_uri/verification_uri_complete instead of the built-in managed device page. Lets a CLI surface the project's own RFC 8628 approval page. Empty falls back to the managed page. example: https://app.acme.com/device AuthHostedPage: type: object properties: id: type: string format: uuid project_id: type: string format: uuid page_type: $ref: '#/components/schemas/HostedAuthPageType' html: type: string description: HTML content for this page type. css: type: string description: CSS content for this page type. created_at: type: string format: date-time updated_at: type: string format: date-time AuthHostedPageResponse: type: object properties: page: $ref: '#/components/schemas/AuthHostedPage' AuthIdentity: type: object description: | A real email identity owned by the account. One account can own multiple identities (for example a work email plus a personal email linked via OAuth). properties: id: type: string format: uuid description: Unique identity identifier email: type: string format: email description: The email address this identity represents email_verified: type: boolean description: Whether ownership of this email has been verified is_primary: type: boolean description: Whether the account's primary sign-in method resolves to this identity created_at: type: string format: date-time required: - id - email - email_verified - is_primary - created_at AuthIdentitiesResponse: type: object properties: identities: type: array items: $ref: '#/components/schemas/AuthIdentity' required: - identities AuthMethodSummary: type: object description: | A single sign-in method the account owns (password, an OAuth provider, or an active anonymous method). `is_primary` reflects the account's primary_method_id. properties: id: type: string format: uuid description: Unique method identifier type: type: string x-go-type: string description: The kind of sign-in method enum: - password - oauth - anonymous provider: type: string description: OAuth provider name; present only when type is oauth example: google identity_id: type: string description: | The identity this method signs in to — a UUID for password/oauth methods, empty for anonymous methods. email: type: string description: The email of the method's identity (empty for anonymous) is_primary: type: boolean description: Whether this is the account's primary sign-in method last_used_at: type: string format: date-time description: When this method was last used to sign in, if ever created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - type - identity_id - email - is_primary - created_at - updated_at AuthMethodsResponse: type: object properties: methods: type: array items: $ref: '#/components/schemas/AuthMethodSummary' required: - methods AuthSession: type: object description: An authentication session for a user properties: id: type: string format: uuid description: Unique session identifier user_id: type: string format: uuid description: The user this session belongs to provider: type: string description: Authentication provider used to create this session enum: - email - google - github - microsoft - apple - anonymous example: email user_agent: type: string description: Browser/device user agent string example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ip_address: type: string description: IP address of the client when the session was created example: 192.168.1.1 last_ip_address: type: string description: IP address of the most recent activity (token refresh) example: 192.168.1.100 expires_at: type: string format: date-time description: When this session expires last_activity_at: type: string format: date-time description: Last activity timestamp session_started_at: type: string format: date-time description: When the session was created is_active: type: boolean description: Whether the session is currently active (not expired) is_current: type: boolean description: Whether this is the session making the current request created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - user_id - provider - expires_at AuthSignupResponse: type: object description: | Uniform, session-less response returned by POST /auth/signup. It carries no tokens and no user object, and is identical for a new account and for an already-registered email (anti-enumeration). Clients obtain a session with a subsequent POST /auth/signin. properties: confirmation_required: type: boolean description: | Whether the project requires email confirmation. Reflects project config only (identical for a new and an existing email), so it leaks nothing about account existence. message: type: string description: Human-readable acknowledgement. required: - confirmation_required - message AuthTokenResponse: type: object properties: access_token: type: string description: JWT access token (expires after configured lifetime) token_type: type: string example: bearer expires_in: type: integer description: Access token lifetime in seconds refresh_token: type: string description: Long-lived token for getting new access tokens user: $ref: '#/components/schemas/AuthUser' required: - access_token - token_type - expires_in - refresh_token - user AuthUser: type: object properties: id: type: string format: uuid project_id: type: string format: uuid email: type: string format: email email_confirmed: type: boolean user_metadata: type: object additionalProperties: true description: User-editable metadata app_metadata: type: object additionalProperties: true description: Application-controlled metadata (read-only for users) avatar_url: type: string format: uri description: User avatar URL (from OAuth provider or manually set) status: type: string enum: - active - banned - deleted banned_until: type: string format: date-time nullable: true description: When temporary ban expires (null if not banned or permanent) last_sign_in_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - email - status BanUserResponse: type: object description: Response when banning a user properties: message: type: string example: User banned until 2026-12-31T23:59:59Z user_id: type: string format: uuid email: type: string format: email status: type: string enum: - banned banned_until: type: string format: date-time nullable: true description: When the ban expires (null for permanent ban) required: - message - user_id - email - status BatchFunctionDeployFailure: type: object properties: name: type: string function_id: type: string format: uuid operation: type: string enum: - deploy - update error: type: string required: - name - error BatchFunctionDeployResponse: type: object properties: batch_id: type: string format: uuid data: type: array description: Functions whose deployment workflows were started successfully items: $ref: '#/components/schemas/Function' failed: type: array description: Functions that failed before their workflow started. Successful functions are left running; failed new functions are deleted and failed updates are rolled back where possible. items: $ref: '#/components/schemas/BatchFunctionDeployFailure' required: - batch_id - data CompleteUploadSessionResponse: type: object description: Response when completing an upload properties: object: $ref: '#/components/schemas/StorageObject' CreateDatabaseRequest: type: object description: | Create a new PostgreSQL database. Volcano automatically sets up: - Auth helpers (auth.uid(), auth.email(), auth.role()) - Database roles (anon for unauthenticated, authenticated for signed-in users) - Secure multi-tenant isolation - Ready for Row-Level Security properties: name: type: string description: Database name (must be unique within project) pattern: ^[a-z0-9_]+$ maxLength: 64 example: my_database region: type: string description: AWS region for database hosting example: aws-us-east-1 enum: - aws-us-east-1 - aws-us-east-2 - aws-us-west-2 - aws-eu-central-1 - aws-eu-west-2 - aws-ap-southeast-1 - aws-ap-southeast-2 - aws-sa-east-1 pg_version: type: string description: PostgreSQL major version example: '16' enum: - '15' - '16' database_type: type: string description: | Compute size tier (optional, defaults to volcano-db-xs). Determines autoscaling limits for the database. enum: - volcano-db-xs - volcano-db-s - volcano-db-m - volcano-db-l - volcano-db-xl - volcano-db-2xl default: volcano-db-xs example: volcano-db-xs required: - name - region - pg_version CreateEmailTemplateRequest: type: object properties: template_type: type: string enum: - welcome - confirmation - password_reset - password_changed description: Type of email template subject: type: string description: Email subject line example: Confirm your email html_body: type: string description: | HTML template body. Available placeholders: - {{.Token}} - The confirmation/reset token - {{.ProjectName}} - The project name - {{.Email}} - User's email address text_body: type: string description: Plain text template body (same placeholders as HTML) required: - template_type - subject - html_body - text_body CreateFrontendCustomDomainRequest: type: object properties: domain: type: string description: Fully-qualified domain name (hostname only, no scheme/path) example: app.example.com tls: $ref: '#/components/schemas/FrontendCustomDomainTLSConfig' required: - domain - tls CreateFunctionSchedulerRequest: type: object required: - name - schedule properties: name: type: string enabled: type: boolean default: true schedule: $ref: '#/components/schemas/ScheduleRequest' payload: type: object additionalProperties: true regions: type: array description: Optional single explicit deployed region. If omitted, the scheduler chooses one deployed region and invokes according to the cron expression. maxItems: 1 items: type: string CreateOAuthConfigRequest: type: object required: - provider properties: provider: type: string enum: - google - github - microsoft - apple - device example: google client_id: type: string example: 123456789.apps.googleusercontent.com description: Required for non-device providers. Must not be provided for `provider=device`; server always auto-generates it. client_secret: type: string example: GOCSPX-abc123def456 description: Required for non-device providers. Must not be provided for `provider=device`; server always auto-generates it. redirect_url: type: string description: Required for non-device providers. Not used for `provider=device`. format: uri example: https://yourapp.com/auth/callback scopes: type: array items: type: string example: - openid - email - profile description: Optional for non-device providers, uses provider defaults if omitted. Not used for `provider=device`. CreateProjectRequest: type: object description: Request to create a new project properties: name: type: string description: | Project name (must be unique). Can only contain letters, numbers, underscores, and hyphens. pattern: ^[A-Za-z0-9_-]+$ minLength: 1 maxLength: 255 example: my-awesome-app all_regions: type: boolean description: | Optional region policy. - `true` (default): project functions deploy to all configured regions - `false`: project deploys only to `selected_regions` default: true selected_regions: type: array items: type: string description: | Optional region subset. Requires `all_regions=false`. Region names must be a subset of platform `AWS_REGIONS`. example: - us-east-1 - us-west-2 required: - name CreateStorageBucketRequest: type: object properties: name: type: string description: Bucket name (alphanumeric, dashes, underscores) pattern: ^[a-zA-Z0-9_-]+$ minLength: 1 maxLength: 64 file_size_limit: type: integer format: int64 description: Maximum file size in bytes allowed_mime_types: type: array items: type: string description: Allowed MIME types (e.g., ["image/png", "image/jpeg"]) required: - name CreateStoragePolicyRequest: type: object properties: name: type: string description: Policy name operation: type: string enum: - SELECT - INSERT - UPDATE - DELETE description: Operation this policy applies to definition: type: string description: Policy expression required: - name - operation - definition CreateUploadSessionRequest: type: object description: Request to create a resumable upload session properties: object_path: type: string description: Target file path within the bucket example: videos/large-file.mp4 content_type: type: string description: MIME type of the file example: video/mp4 total_size: type: integer format: int64 description: Total file size in bytes (max 5TB) minimum: 1 maximum: 5497558138880 example: 5368709120 part_size: type: integer format: int64 description: 'Part size in bytes (default: 25MB, min: 5MB, max: 25MB)' minimum: 5242880 maximum: 26214400 example: 26214400 required: - object_path - content_type - total_size CreateUploadSessionResponse: type: object description: Response when creating an upload session properties: session_id: type: string description: Upload session ID example: session-abc123 part_size: type: integer format: int64 description: Actual part size to use example: 26214400 total_parts: type: integer description: Number of parts to upload example: 52 expires_at: type: string format: date-time description: When the session expires (7 days from creation) example: '2024-01-22T10:30:00Z' CreateVariableRequest: type: object properties: name: type: string minLength: 1 maxLength: 256 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ value: type: string required: - name - value Database: type: object description: | PostgreSQL database with automatic scalability and security features. properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string description: Database name pattern: ^[a-z0-9_]+$ maxLength: 64 status: type: string enum: - provisioning - active - failed - deleting description: Database provisioning status provisioning_started_at: type: string format: date-time description: Timestamp when the current provisioning phase started connection_string: type: string description: | Secure PostgreSQL connection URI for your database. The database is identified by the globally-unique username (`volcano_client_{database_id}`) already in this URI; the `application_name` parameter only selects the access mode: - `volcano_full_access` — Full admin access (DDL, migrations) - `volcano_user_access:{user_id}` — User impersonation (RLS enforced) - `volcano_user_access` — Anonymous access (anon role, RLS enforced) example: postgres://volcano_client_11111111-1111-1111-1111-111111111111:vpg_secret@database.volcano.dev:5432/my_app_db?sslmode=require&application_name=volcano_full_access region: type: string description: AWS region where database is hosted example: aws-us-east-1 pg_version: type: string description: PostgreSQL major version example: '16' database_type: type: string description: | Database size tier that determines available RAM and scaling limits. enum: - volcano-db-xs - volcano-db-s - volcano-db-m - volcano-db-l - volcano-db-xl - volcano-db-2xl example: volcano-db-xs last_invoked_at: type: string format: date-time description: Most recent request timestamp for this database created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - name - status - created_at - updated_at DatabaseStats: type: object properties: storage_bytes: type: integer format: int64 description: Total storage used in bytes (data + WAL) data_written_bytes: type: integer format: int64 description: Total data written in bytes data_transfer_bytes: type: integer format: int64 description: Total data transferred in bytes compute_time_seconds: type: number format: double description: Total CPU seconds consumed active_time_seconds: type: number format: double description: Total active compute time in seconds time_range: type: string description: Time range of the metrics (e.g., "2024-01-01T00:00:00Z to 2024-01-02T00:00:00Z") granularity: type: string enum: - hourly - daily - monthly description: Granularity of the aggregated metrics required: - storage_bytes - data_written_bytes - data_transfer_bytes - compute_time_seconds - active_time_seconds DatabaseQueryPerformanceResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/DatabaseQueryPerformanceItem' required: - data DeviceAuthorizationResponse: type: object properties: device_code: type: string user_code: type: string verification_uri: type: string description: | Browser verification URL. Points at the project's managed device approval page served by this API: `/projects/{projectId}/auth/hosted?action=device&anon_key=...`. Requires the project to have managed auth enabled and a default anon key. A custom CLI may ignore this and direct users to its own RFC 8628-compatible page instead (see the device-auth guide). verification_uri_complete: type: string description: | Same as `verification_uri` but with the `user_code` prefilled (`&user_code=...`). This is the URL most device clients open. expires_in: type: integer interval: type: integer required: - device_code - user_code - verification_uri - verification_uri_complete - expires_in - interval EmailTemplate: type: object description: Custom email template properties: id: type: string format: uuid project_id: type: string format: uuid template_type: type: string enum: - welcome - confirmation - password_reset - password_changed subject: type: string example: Confirm your email address html_body: type: string description: HTML template with placeholders text_body: type: string description: Plain text template with placeholders created_at: type: string format: date-time updated_at: type: string format: date-time required: - template_type - subject - html_body - text_body Error: type: object properties: error: type: string required: - error Frontend: type: object properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ framework: type: string enum: - nextjs app_root: type: string maxLength: 1024 description: Optional relative POSIX path from the uploaded archive root to the Next.js app that is deployed. status: type: string enum: - provisioning - active - failed - deleting provisioning_started_at: type: string format: date-time description: Timestamp when the current provisioning phase started deployed_regions: type: array items: type: string current_deployment_id: type: string format: uuid description: Identifier of the latest frontend deployment operation site_url: type: string custom_domain: type: string description: Active custom domain hostname when configured custom_domain_status: type: string description: Current custom domain lifecycle status enum: - pending_verification - provisioning - active - detaching - failed - deleted last_invoked_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - name - framework - status - deployed_regions - created_at - updated_at FrontendCustomDomainResponse: type: object properties: domain: type: string tls_mode: type: string enum: - managed - byoc domain_status: type: string enum: - pending_verification - provisioning - active - detaching - failed - deleted verification_status: type: string enum: - pending - verified verification_records: type: array items: $ref: '#/components/schemas/FrontendDomainVerificationRecord' required_routing_record: $ref: '#/components/schemas/FrontendDomainRoutingRecord' effective_urls: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - domain - tls_mode - domain_status - verification_status - effective_urls - created_at - updated_at FrontendCustomDomainTLSConfig: type: object properties: mode: type: string enum: - byoc default: byoc description: BYOC is mandatory for custom domain creation. certificate_pem: type: string description: Required. PEM-encoded certificate. private_key_pem: type: string description: Required. PEM-encoded private key. certificate_chain_pem: type: string description: Optional PEM-encoded certificate chain. required: - mode - certificate_pem - private_key_pem FrontendDeployment: type: object properties: id: type: string format: uuid frontend_id: type: string format: uuid project_id: type: string format: uuid operation: type: string enum: - deploy - redeploy - delete status: type: string enum: - provisioning - active - failed - deleting - deleted artifact_bucket: type: string artifact_key: type: string artifact_version: type: string cloudwatch_log_group: type: string site_url: type: string cloudformation_stack_id: type: string cloudformation_stack_url: type: string codebuild_duration_seconds: type: integer format: int64 description: Total CodeBuild build duration recorded for this deployment, in seconds. codebuild_build_count: type: integer description: Number of completed CodeBuild builds included in codebuild_duration_seconds. codebuild_duration_recorded_at: type: string format: date-time error_message: type: string created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - frontend_id - project_id - operation - status - created_at - updated_at FrontendDomainRoutingRecord: type: object properties: record_type: type: string enum: - CNAME name: type: string value: type: string required: - record_type - name - value FrontendDomainVerificationRecord: type: object properties: name: type: string type: type: string value: type: string required: - name - type - value FrontendUsageDailyEntry: type: object description: One day of request and error counts for a single frontend. properties: day: type: string format: date description: UTC date (YYYY-MM-DD) the counts cover. requests: type: integer format: int64 description: Total requests served on this day. errors: type: integer format: int64 description: 5xx responses served on this day. page_views: type: integer format: int64 description: Navigable-document responses served on this day (text/html or Sec-Fetch-Dest=document) — strict subset of `requests`. required: - day - requests - errors - page_views FrontendUsageData: type: object description: Monthly frontend request totals grouped by frontend. properties: frontend_id: type: string format: uuid description: Frontend ID frontend_name: type: string description: Frontend name at the time usage was fetched nullable: true requests: type: integer format: int64 description: Total requests for this frontend in the current usage month required: - frontend_id - requests FrontendUsageHistoryResponse: type: object description: Zero-filled daily series of request + error counts for a single frontend, oldest first. properties: frontend_id: type: string format: uuid days: type: integer description: Number of daily entries returned (always equal to the `days` query param after clamping). daily: type: array items: $ref: '#/components/schemas/FrontendUsageDailyEntry' total_requests: type: integer format: int64 total_errors: type: integer format: int64 total_page_views: type: integer format: int64 required: - frontend_id - days - daily - total_requests - total_errors - total_page_views Function: type: object properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ status: type: string enum: - provisioning - active - failed - deleting provisioning_started_at: type: string format: date-time description: Timestamp when the current provisioning phase started is_public: type: boolean description: | Function visibility for anon-key invocation. - `false` (default): only auth user tokens and service keys can invoke - `true`: anon keys with `functions.invoke` can invoke aws_function_arn: type: string invoke_url: type: string description: Canonical GeoDNS endpoint URL for invoking this function (always HTTPS) deployed_regions: type: array items: type: string description: Regions where this function is currently deployed runtime: type: string handler: type: string current_deployment_id: type: string format: uuid description: Identifier of the latest function deployment operation last_invoked_at: type: string format: date-time description: Most recent successful invocation timestamp created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - name - status - is_public - deployed_regions - created_at - updated_at FunctionDeployment: type: object properties: id: type: string format: uuid function_id: type: string format: uuid project_id: type: string format: uuid batch_id: type: string format: uuid operation: type: string enum: - deploy - update - delete status: type: string enum: - provisioning - active - failed - deleting - deleted artifact_bucket: type: string artifact_key: type: string artifact_version: type: string compile_log_group: type: string compile_log_stream: type: string publish_log_group: type: string publish_log_stream: type: string codebuild_duration_seconds: type: integer format: int64 description: Total CodeBuild build duration recorded for this deployment, in seconds. codebuild_build_count: type: integer description: Number of completed CodeBuild builds included in codebuild_duration_seconds. codebuild_duration_recorded_at: type: string format: date-time error_message: type: string completed_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - function_id - project_id - operation - status - created_at - updated_at FunctionInvocationRequest: type: object properties: payload: type: object additionalProperties: true description: | Payload to send to the Lambda function. If invoked with auth user token, Volcano automatically injects `__volcano_auth` context: ```javascript { ...yourPayload, __volcano_auth: { user_id: "uuid", email: "user@example.com", project_id: "uuid", role: "authenticated" | "anonymous" } } ``` FunctionInvocationResponse: type: object description: Raw function response body returned by the invoked function. additionalProperties: true LogActivityBucket: type: object description: Log-event counts for one activity time bucket. properties: start_time: type: string format: date-time description: Bucket start time. end_time: type: string format: date-time description: Bucket end time. counts: type: object description: Counts grouped by activity dimension. properties: levels: type: object additionalProperties: type: integer description: Counts by normalized log level. regions: type: object additionalProperties: type: integer description: Counts by event region. resource_ids: type: object additionalProperties: type: integer description: Counts by resource ID. required: - levels - regions - resource_ids total: type: integer description: Total events in this bucket. required: - start_time - end_time - counts - total LogActivityRequest: type: object description: Activity request for bucketed log counts. additionalProperties: false properties: resource: $ref: '#/components/schemas/LogRequestResource' q: type: string description: Optional free-text search query for log messages. levels: type: array description: Canonical lowercase log levels to filter by. If omitted, empty, or all levels are selected, no level filter is applied. items: $ref: '#/components/schemas/LiveLogLevel' regions: type: array maxItems: 25 description: Regions to filter by, for example `["us-east-1", "eu-west-1"]`. If omitted or empty, aggregate all deployed regions. items: type: string start_time: type: string format: date-time description: Start time. end_time: type: string format: date-time description: End time. bucket_count: type: integer minimum: 1 maximum: 96 description: Number of activity buckets to return. required: - resource LogActivityResponse: type: object description: Bucketed runtime log activity. properties: data: type: array items: $ref: '#/components/schemas/LogActivityBucket' total: type: integer description: Total events counted across all buckets. required: - data - total LogSearchRequest: type: object description: Search request for project logs. additionalProperties: false properties: resource: $ref: '#/components/schemas/LogRequestResource' q: type: string description: Optional free-text search query for log messages. levels: type: array description: Canonical lowercase log levels to filter by. If omitted, empty, or all levels are selected, no level filter is applied. items: $ref: '#/components/schemas/LiveLogLevel' regions: type: array maxItems: 25 description: Regions to filter by, for example `["us-east-1", "eu-west-1"]`. If omitted or empty, search all deployed regions. items: type: string start_time: type: string format: date-time description: Start time. end_time: type: string format: date-time description: End time. limit: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum number of records to return. cursor: type: string description: Opaque pagination cursor from the previous response's `next_cursor`. required: - resource LogStreamRequest: type: object description: Stream request for live project logs. Text search, pagination cursors, and fixed end times are not supported. additionalProperties: false properties: resource: $ref: '#/components/schemas/LogRequestResource' levels: type: array description: Canonical lowercase log levels to filter by. If omitted, empty, or all levels are selected, no level filter is applied. items: $ref: '#/components/schemas/LiveLogLevel' regions: type: array maxItems: 25 description: Regions to filter by, for example `["us-east-1", "eu-west-1"]`. If omitted or empty, stream all deployed regions. items: type: string start_time: type: string format: date-time description: Start time. limit: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum number of records to deliver on connect or reconnect before following new events. required: - resource LogSearchEvent: allOf: - $ref: '#/components/schemas/LogEvent' - type: object description: Runtime log event returned by project log search. Search results always include a stable event ID and owning resource. properties: id: type: string description: Opaque stable log event ID for pagination, deduplication, and display. resource: $ref: '#/components/schemas/LogResource' required: - id - resource LogSearchResponse: type: object description: Paginated project runtime log search response. properties: data: type: array items: $ref: '#/components/schemas/LogSearchEvent' description: Array of log events sorted by timestamp, newest first. limit: type: integer description: Number of items requested per page. has_more: type: boolean description: Whether there are more log events available. next_cursor: type: string description: Opaque cursor for the next page. Send this value as `cursor` on the next request. required: - data - limit - has_more FunctionRegion: type: object required: - code - label - flag properties: code: type: string example: us-east-1 description: AWS region identifier accepted by function APIs. label: type: string example: NA-East description: Human-readable region label suitable for display in pickers. flag: type: string example: 🇺🇸 description: Country flag emoji associated with the region's geography. FunctionRuntimeOption: type: object required: - name - language - default - deployment properties: name: type: string example: nodejs24.x description: Runtime identifier accepted by function APIs. language: type: string example: nodejs description: Runtime language family used by the CLI to choose defaults from source files. default: type: boolean description: Whether this runtime is the CLI default for its language. deployment: $ref: '#/components/schemas/FunctionRuntimeDeployment' FunctionRuntimesResponse: type: object required: - runtimes properties: runtimes: type: array items: $ref: '#/components/schemas/FunctionRuntimeOption' FunctionScheduler: type: object properties: id: type: string format: uuid project_id: type: string format: uuid function_id: type: string format: uuid name: type: string enabled: type: boolean schedule_kind: type: string enum: - cron cron_expression: type: string payload: type: object additionalProperties: true regions: type: array items: type: string regions_explicit: type: boolean next_run_at: type: string format: date-time last_started_at: type: string format: date-time last_completed_at: type: string format: date-time last_error: type: string created_at: type: string format: date-time updated_at: type: string format: date-time FunctionSchedulerListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/FunctionScheduler' page: type: integer limit: type: integer total: type: integer has_more: type: boolean required: - data - page - limit - total - has_more HostedAuthPageType: type: string enum: - login - reset-password HostedLoginEmailCheckRequest: type: object required: - email properties: email: type: string format: email HostedLoginEmailCheckResponse: type: object properties: exists: type: boolean HostedLoginOptionsResponse: type: object properties: require_email_confirmation: type: boolean email_password_enabled: type: boolean enable_signup: type: boolean post_auth_redirect_url: type: string oauth_providers: type: array items: type: string HostedRenderablePageType: type: string enum: - reset-password LogEvent: type: object description: Normalized historical log event returned by paginated log APIs. properties: id: type: string description: Opaque stable log event ID for pagination, deduplication, and display. timestamp: type: string format: date-time description: Event timestamp. level: $ref: '#/components/schemas/LiveLogLevel' message: type: string description: Display log message. region: type: string description: Region where this log event originated. resource: $ref: '#/components/schemas/LogResource' deployment: $ref: '#/components/schemas/LogDeployment' invocation_id: type: string description: Function invocation ID associated with this log event, when available. raw_message: type: string description: Original log line/message after platform sanitization. metadata: type: object nullable: true additionalProperties: true description: Parsed JSON fields and other indexed metadata, when available. required: - timestamp - message LiveLogLevel: type: string enum: - trace - debug - info - warn - error - fatal description: Canonical lowercase function runtime log level. MetricUsageData: type: object description: Usage data for one metric across totals, daily, and hourly windows. properties: metric: type: string description: | Metric name (for example, "Function & Frontend Invocations", "Frontend Requests", "CodeBuild Build Seconds", "Bandwidth Ingress (Bytes)", "Bandwidth Egress (Bytes)", "Bandwidth Total (Bytes)", or "Database Storage (Bytes)"). Byte-based metrics are reported in bytes. "Bandwidth Total (Bytes)" is derived (ingress + egress) and is not billed separately. "Database Storage (Bytes)" is a current observed gauge, not a cumulative counter. total: type: integer format: int64 description: Total usage for the current usage month all_time: type: integer format: int64 description: Lifetime cumulative usage across every month for this metric daily: type: array description: Last 30 days of daily usage points items: $ref: '#/components/schemas/UsageDataPoint' hourly: type: array description: Last 24 hours of hourly usage points items: $ref: '#/components/schemas/UsageDataPoint' required: - metric - total - all_time - daily - hourly OAuthConfig: type: object properties: id: type: string format: uuid provider: type: string enum: - google - github - microsoft - apple - device client_id: type: string example: 123456789.apps.googleusercontent.com client_secret: type: string description: Masked in responses (shows only first/last 4 chars) example: GOCS...**** enabled: type: boolean redirect_url: type: string format: uri example: https://yourapp.com/auth/callback scopes: type: array items: type: string example: - openid - email - profile created_at: type: string format: date-time updated_at: type: string format: date-time OAuthErrorResponse: type: object properties: error: type: string error_description: type: string required: - error PaginatedAuthUsers: type: object properties: data: type: array items: $ref: '#/components/schemas/AuthUser' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedDatabases: type: object properties: data: type: array items: $ref: '#/components/schemas/Database' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedFrontendDeployments: type: object properties: data: type: array items: $ref: '#/components/schemas/FrontendDeployment' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedFrontends: type: object properties: data: type: array items: $ref: '#/components/schemas/Frontend' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedFunctionDeployments: type: object properties: data: type: array items: $ref: '#/components/schemas/FunctionDeployment' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedFunctions: type: object properties: data: type: array items: $ref: '#/components/schemas/Function' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedProjectCustomDomains: type: object properties: data: type: array items: $ref: '#/components/schemas/ProjectFrontendCustomDomain' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedProjectDeployments: type: object properties: data: type: array items: $ref: '#/components/schemas/ProjectDeployment' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedProjects: type: object properties: data: type: array items: $ref: '#/components/schemas/Project' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) status: type: string enum: - provisioning - active - failed description: Latest project variable propagation status. current_sync_id: type: string format: uuid description: Identifier of the latest variable propagation sync. provisioning_started_at: type: string format: date-time description: Timestamp when the current variable propagation phase started. required: - data - page - limit - total - has_more PaginatedServiceKeys: type: object properties: data: type: array items: $ref: '#/components/schemas/ServiceKey' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PaginatedVariables: type: object properties: data: type: array items: $ref: '#/components/schemas/Variable' page: type: integer description: Current page number (1-indexed) limit: type: integer description: Number of items per page total: type: integer description: Total number of items across all pages has_more: type: boolean description: Whether there are more pages available next: type: string description: URL path to next page (only present if has_more is true) required: - data - page - limit - total - has_more PlatformExchangeResponse: type: object properties: token: type: string user_id: type: string token_id: type: string format: uuid expires_at: type: string format: date-time required: - token - user_id - token_id - expires_at Project: type: object properties: id: type: string format: uuid name: type: string status: type: string enum: - active - deleting - failed plan: type: string enum: - FREE - PRO description: Platform plan applied to the project when available all_regions: type: boolean description: | Region policy for function deployment. - `true`: deploy functions to all configured platform regions - `false`: deploy only to `selected_regions` selected_regions: type: array items: type: string description: Effective region set for this project (normalized and deduplicated) aws_application_name: type: string last_invoked_at: type: string format: date-time description: Most recent activity timestamp across project resources logo_url: type: string description: | Relative API path that serves the project logo when one has been uploaded. The path is versioned with a `?v=` cache-busting query param that changes on each upload. Absent when the project has no logo. The logo image is stored in the project's S3 folder. example: /projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/logo?v=1718524800 created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - status - all_regions - selected_regions - created_at - updated_at ProjectConfig: type: object additionalProperties: false description: | Declarative project configuration manifest (the JSON form of volcano-config.yaml). Omitted sections are left untouched. Within declared entries, omitted optional fields keep their current server values (patch semantics). Declared collection keys are fully synced to the manifest: `variables`, `buckets[].policies`, `auth.providers.oauth`, `auth.email.templates`, and `functions[].schedulers` are reconciled to exactly match, deleting resources absent from the manifest. Functions, frontends, databases, and buckets are never created or deleted through this manifest; entries referencing resources that do not exist are skipped and reported. properties: version: type: integer enum: - 1 description: Manifest schema version. Must be 1. project: $ref: '#/components/schemas/ProjectConfigProject' databases: type: array items: $ref: '#/components/schemas/ProjectConfigDatabase' variables: type: array description: Fully synced when declared - variables absent from this list are deleted. items: $ref: '#/components/schemas/ProjectConfigVariable' buckets: type: array items: $ref: '#/components/schemas/ProjectConfigBucket' realtime: $ref: '#/components/schemas/ProjectConfigRealtime' auth: $ref: '#/components/schemas/ProjectConfigAuth' functions: type: array items: $ref: '#/components/schemas/ProjectConfigFunction' frontends: type: array items: $ref: '#/components/schemas/ProjectConfigFrontend' required: - version ProjectConfigApplyResult: type: object description: Per-resource report for a project config apply (or dry run). properties: dry_run: type: boolean description: True when the request was a dry run and no changes were made. results: type: array items: $ref: '#/components/schemas/ProjectConfigApplyResultEntry' skipped: type: array description: | Manifest entries referencing functions, frontends, databases, or buckets that do not exist. Their configuration was not applied; deploy/create the resource first, then re-apply. items: $ref: '#/components/schemas/ProjectConfigSkippedResource' missing: type: array description: | Existing functions, frontends, databases, or buckets that have no entry in the corresponding declared manifest section. items: $ref: '#/components/schemas/ProjectConfigMissingResource' summary: $ref: '#/components/schemas/ProjectConfigApplySummary' required: - results - skipped - missing - summary ProjectConfigApplyResultEntry: type: object properties: section: type: string description: Manifest section the entry belongs to (e.g. variables, buckets, auth.providers.oauth). name: type: string description: Resource name or key within the section. Empty for singleton sections. action: type: string enum: - created - updated - deleted - unchanged - error error: type: string description: Error detail when action is `error`. notice: type: string description: Optional operational note (e.g. disabling realtime drops active connections). required: - section - action ProjectConfigApplySummary: type: object properties: created: type: integer updated: type: integer deleted: type: integer unchanged: type: integer errors: type: integer skipped: type: integer missing: type: integer required: - created - updated - deleted - unchanged - errors - skipped - missing ProjectConfigAuth: type: object additionalProperties: false description: Authentication settings, grouped like the dashboard auth-settings tabs. properties: tokens: $ref: '#/components/schemas/ProjectConfigAuthTokens' sessions: $ref: '#/components/schemas/ProjectConfigAuthSessions' signup: $ref: '#/components/schemas/ProjectConfigAuthSignup' rate_limits: $ref: '#/components/schemas/ProjectConfigAuthRateLimits' password: $ref: '#/components/schemas/ProjectConfigAuthPassword' password_reset: $ref: '#/components/schemas/ProjectConfigAuthPasswordReset' email_verification: $ref: '#/components/schemas/ProjectConfigAuthEmailVerification' cors: $ref: '#/components/schemas/ProjectConfigAuthCORS' providers: $ref: '#/components/schemas/ProjectConfigAuthProviders' email: $ref: '#/components/schemas/ProjectConfigAuthEmail' managed_pages: $ref: '#/components/schemas/ProjectConfigAuthManagedPages' ProjectConfigAuthCORS: type: object additionalProperties: false properties: enabled: type: boolean allowed_origins: type: array items: type: string allow_credentials: type: boolean max_age: type: integer ProjectConfigAuthEmail: type: object additionalProperties: false properties: enabled: type: boolean description: Enable transactional email sending from: $ref: '#/components/schemas/ProjectConfigAuthEmailFrom' smtp: $ref: '#/components/schemas/ProjectConfigAuthEmailSMTP' templates: $ref: '#/components/schemas/ProjectConfigEmailTemplates' ProjectConfigAuthEmailFrom: type: object additionalProperties: false properties: address: type: string name: type: string ProjectConfigAuthEmailPasswordProvider: type: object additionalProperties: false properties: enabled: type: boolean ProjectConfigAuthEmailSMTP: type: object additionalProperties: false properties: host: type: string port: type: integer username: type: string password: type: string format: password writeOnly: true description: Write-only; omitted from config export. use_tls: type: boolean ProjectConfigAuthEmailVerification: type: object additionalProperties: false properties: require_confirmation: type: boolean description: Require users to confirm email before sign-in. Requires email sending to be enabled. confirmation_timeout: type: integer description: Email confirmation token expiry in seconds ProjectConfigAuthManagedPages: type: object additionalProperties: false properties: enabled: type: boolean description: Enable or disable managed auth hosted pages redirects: $ref: '#/components/schemas/ProjectConfigAuthRedirects' pages: $ref: '#/components/schemas/ProjectConfigHostedPages' ProjectConfigAuthPassword: type: object additionalProperties: false properties: min_length: type: integer require_uppercase: type: boolean require_lowercase: type: boolean require_numbers: type: boolean require_special_chars: type: boolean ProjectConfigAuthPasswordReset: type: object additionalProperties: false properties: allow: type: boolean timeout: type: integer description: Password reset token expiry in seconds max_history: type: integer description: Number of previous passwords to disallow (0=disabled) ProjectConfigAuthProviders: type: object additionalProperties: false properties: email_password: $ref: '#/components/schemas/ProjectConfigAuthEmailPasswordProvider' oauth: type: array description: Fully synced when declared - providers absent from this list are deleted. items: $ref: '#/components/schemas/ProjectConfigOAuthProvider' ProjectConfigAuthRateLimits: type: object additionalProperties: false description: Rate limits per hour. properties: signup: type: integer signin: type: integer token_refresh: type: integer password_reset: type: integer ProjectConfigAuthRedirects: type: object additionalProperties: false properties: allowed: type: array items: type: string description: Redirect allowlist. Every entry must be a valid http/https URL. post_auth: type: string description: Must be included in `allowed` when set. post_logout: type: string description: Must be included in `allowed` when set. device_verification: type: string description: Optional custom device-authorization verification page URL. ProjectConfigAuthSessions: type: object additionalProperties: false properties: inactivity_timeout: type: integer description: Force re-login after inactivity (seconds, 0=never) max_session_duration: type: integer description: Force re-login after duration (seconds, 0=never) ProjectConfigAuthSignup: type: object additionalProperties: false properties: enable_signup: type: boolean description: Master switch for signups across ALL providers enable_anonymous_signins: type: boolean ProjectConfigAuthTokens: type: object additionalProperties: false description: Token lifetimes in seconds. properties: access_token_lifetime: type: integer refresh_token_lifetime: type: integer refresh_token_reuse_interval: type: integer platform_token_ttl: type: integer ProjectConfigBucket: type: object additionalProperties: false description: | Settings for an existing storage bucket. Buckets are never created or deleted through the manifest. When `policies` is declared it is fully synced (policies absent from the list are deleted; an empty list deletes all); omitting `policies` leaves the bucket's policies untouched. properties: name: type: string pattern: ^[a-zA-Z0-9_-]+$ minLength: 1 maxLength: 64 file_size_limit: type: integer format: int64 description: Maximum file size in bytes allowed_mime_types: type: array items: type: string policies: type: array items: $ref: '#/components/schemas/ProjectConfigBucketPolicy' required: - name ProjectConfigBucketPolicy: type: object additionalProperties: false properties: name: type: string minLength: 1 operation: type: string enum: - SELECT - INSERT - UPDATE - DELETE definition: type: string description: Policy expression required: - name - operation - definition ProjectConfigCustomDomain: type: object additionalProperties: false description: | Custom domain with BYOC TLS (PRO plan). `tls` is required when the domain is first created and optional afterwards: providing new TLS material for the same domain rotates the certificate in place (zero downtime); omitting `tls` keeps the stored certificate. TLS material is write-only and omitted from config export. properties: domain: type: string description: Fully-qualified domain name (hostname only, no scheme/path) tls: $ref: '#/components/schemas/FrontendCustomDomainTLSConfig' required: - domain ProjectConfigDatabase: type: object additionalProperties: false description: | Assertion-only entry for an existing database. No database property is mutable through the manifest; declared values are compared against the deployed database and any mismatch fails validation. Databases are never created or deleted here. properties: name: type: string minLength: 1 region: type: string description: Deployed region (aws- prefixed, e.g. aws-us-east-1). Asserted, never written. pg_version: type: string enum: - '15' - '16' description: PostgreSQL major version. Asserted, never written. database_type: type: string enum: - volcano-db-xs - volcano-db-s - volcano-db-m - volcano-db-l - volcano-db-xl - volcano-db-2xl description: | Compute tier. Asserted, never written - tier changes are not supported via the manifest; use the databases API/CLI/GUI instead. required: - name - region - pg_version ProjectConfigEmailTemplate: type: object additionalProperties: false properties: subject: type: string html_body: type: string maxLength: 262144 description: HTML body. Max 256 KiB. PRO plan required for custom bodies. text_body: type: string maxLength: 262144 description: Plain-text body. Max 256 KiB. PRO plan required for custom bodies. ProjectConfigEmailTemplates: type: object additionalProperties: false description: | Email templates keyed by type. Fully synced when declared - template types absent from a declared map revert to server defaults (custom bodies deleted, subject overrides cleared). Custom template bodies require the PRO plan; subject-only changes are available on FREE. properties: confirmation: $ref: '#/components/schemas/ProjectConfigEmailTemplate' password_reset: $ref: '#/components/schemas/ProjectConfigEmailTemplate' password_changed: $ref: '#/components/schemas/ProjectConfigEmailTemplate' welcome: $ref: '#/components/schemas/ProjectConfigEmailTemplate' ProjectConfigFrontend: type: object additionalProperties: false description: | Configuration for an existing (deployed) frontend. Frontends are never created or deleted through the manifest. A declared frontend entry without `custom_domain` deletes an existing custom domain. properties: name: type: string minLength: 1 custom_domain: $ref: '#/components/schemas/ProjectConfigCustomDomain' required: - name ProjectConfigFunction: type: object additionalProperties: false description: | Configuration for an existing (deployed) function. Functions are never created or deleted through the manifest. When `schedulers` is declared it is fully synced (schedulers absent from the list are deleted); omitting `schedulers` leaves the function's schedulers untouched. properties: name: type: string minLength: 1 public: type: boolean description: Function visibility for anon-key invocation schedulers: type: array items: $ref: '#/components/schemas/ProjectConfigScheduler' required: - name ProjectConfigHostedPage: type: object additionalProperties: false properties: html: type: string maxLength: 262144 description: Raw HTML markup for the page. Max 256 KiB. css: type: string maxLength: 262144 description: Optional CSS injected at render time. Max 256 KiB. required: - html ProjectConfigHostedPages: type: object additionalProperties: false description: | Hosted auth pages keyed by page type (PRO plan). Upsert-only: omitted pages are left untouched (there is no delete for hosted pages). properties: login: $ref: '#/components/schemas/ProjectConfigHostedPage' reset_password: $ref: '#/components/schemas/ProjectConfigHostedPage' ProjectConfigMissingResource: type: object properties: type: type: string enum: - function - frontend - database - bucket name: type: string required: - type - name ProjectConfigOAuthProvider: type: object additionalProperties: false properties: provider: type: string enum: - google - github - microsoft - apple - device enabled: type: boolean client_id: type: string description: | Required for non-device providers. Server-generated for `provider=device` (exported read-only, ignored on apply). client_secret: type: string format: password writeOnly: true description: Write-only; omitted from config export. Not used for `provider=device`. redirect_url: type: string description: Not used for `provider=device`. scopes: type: array items: type: string required: - provider ProjectConfigProject: type: object additionalProperties: false description: Project-level settings. `name` renames the project. properties: name: type: string pattern: ^[A-Za-z0-9_-]+$ minLength: 1 maxLength: 255 all_regions: type: boolean description: Region policy. `false` requires `selected_regions` (PRO plan). selected_regions: type: array items: type: string description: Region subset (bare AWS names). Requires `all_regions=false`. ProjectConfigRealtime: type: object additionalProperties: false properties: enabled: type: boolean broadcast_enabled: type: boolean presence_enabled: type: boolean postgres_changes_enabled: type: boolean ProjectConfigScheduler: type: object additionalProperties: false properties: name: type: string minLength: 1 cron: type: string description: 5-field UTC cron expression enabled: type: boolean payload: type: object additionalProperties: true required: - name - cron ProjectConfigSkippedResource: type: object properties: type: type: string enum: - function - frontend - database - bucket name: type: string reason: type: string required: - type - name - reason ProjectConfigValidationError: type: object properties: section: type: string description: Manifest section the error refers to (e.g. databases, functions). name: type: string description: Resource name or key within the section, when applicable. message: type: string required: - section - message ProjectConfigValidationErrorResponse: type: object description: Returned when manifest validation fails. Nothing was applied. properties: error: type: string errors: type: array items: $ref: '#/components/schemas/ProjectConfigValidationError' required: - error - errors ProjectConfigVariable: type: object additionalProperties: false properties: name: type: string minLength: 1 value: type: string required: - name - value ProjectHealthResource: type: object properties: type: type: string enum: - project - function - frontend - database id: type: string format: uuid name: type: string required: - type - id - name ProjectHealthScope: type: object properties: resource: $ref: '#/components/schemas/ProjectHealthResource' required: - resource ProjectHealthResponse: type: object properties: project_id: type: string format: uuid status: $ref: '#/components/schemas/ProjectHealthStatus' observed_at: type: string format: date-time fresh_through: type: string format: date-time data_status: $ref: '#/components/schemas/ProjectHealthDataStatus' checks: type: array items: $ref: '#/components/schemas/ProjectHealthCheck' findings: description: Top findings ordered by severity, then stable check ID. type: array maxItems: 5 items: $ref: '#/components/schemas/ProjectHealthCheck' required: - project_id - status - observed_at - fresh_through - data_status - checks - findings ProjectHealthStatus: type: string enum: - healthy - degraded - critical - unknown ProjectHealthDataStatus: type: string enum: - complete - partial - no_data - stale ProjectHealthCategory: type: string enum: - lifecycle - storage ProjectHealthEvidence: type: object properties: metric: type: string value: type: number format: double unit: type: string sample_count: type: integer format: int64 minimum: 0 required: - metric - value - unit - sample_count ProjectHealthCheck: type: object properties: id: type: string category: $ref: '#/components/schemas/ProjectHealthCategory' status: $ref: '#/components/schemas/ProjectHealthStatus' reason_code: type: string scope: $ref: '#/components/schemas/ProjectHealthScope' evidence: $ref: '#/components/schemas/ProjectHealthEvidence' required: - id - category - status - reason_code - scope - evidence ProjectMetricsDataStatus: type: string enum: - complete - no_data ProjectMetricsDimensions: type: object additionalProperties: false properties: region: type: string resource_type: type: string enum: - function - frontend ProjectMetricsGroupBy: type: string enum: - region - resource_type ProjectMetricsMetric: type: string enum: - request_count - server_error_count - availability - p95_latency ProjectMetricsQuery: type: object additionalProperties: false properties: id: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z][A-Za-z0-9_-]*$ metric: $ref: '#/components/schemas/ProjectMetricsMetric' group_by: $ref: '#/components/schemas/ProjectMetricsGroupBy' required: - id - metric ProjectMetricsQueryRequest: type: object additionalProperties: false properties: time_range: $ref: '#/components/schemas/ProjectMetricsQueryTimeRange' queries: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/ProjectMetricsQuery' required: - time_range - queries ProjectMetricsQueryResponse: type: object additionalProperties: false properties: observed_at: type: string format: date-time fresh_through: type: string format: date-time window: $ref: '#/components/schemas/ProjectMetricsWindow' results: type: array items: $ref: '#/components/schemas/ProjectMetricsResult' required: - observed_at - window - results ProjectMetricsQueryTimeRange: type: object additionalProperties: false properties: window: type: string enum: - 30m - 1h - 24h - 7d required: - window ProjectMetricsResult: type: object additionalProperties: false properties: id: type: string metric: $ref: '#/components/schemas/ProjectMetricsMetric' unit: $ref: '#/components/schemas/ProjectMetricsUnit' data_status: $ref: '#/components/schemas/ProjectMetricsDataStatus' values: type: array items: $ref: '#/components/schemas/ProjectMetricsValue' required: - id - metric - unit - data_status - values ProjectMetricsUnit: type: string enum: - count - ratio - seconds ProjectMetricsValue: type: object additionalProperties: false properties: dimensions: $ref: '#/components/schemas/ProjectMetricsDimensions' value: type: number format: double minimum: 0 required: - dimensions - value ProjectMetricsWindow: type: object properties: from: type: string format: date-time to: type: string format: date-time required: - from - to ProjectFrontendCustomDomain: allOf: - $ref: '#/components/schemas/FrontendCustomDomainResponse' - type: object properties: frontend: type: object description: | The frontend this custom domain is attached to. Inlined to avoid a second fetch from the project-scoped feed. properties: id: type: string format: uuid name: type: string required: - id - name required: - frontend ProjectDeployment: type: object description: A Function or Frontend deployment attempt in a project-scoped feed. properties: id: type: string format: uuid project_id: type: string format: uuid resource: $ref: '#/components/schemas/ProjectDeploymentResource' operation: type: string enum: - deploy - redeploy - update - delete status: type: string enum: - provisioning - active - failed - deleting - deleted artifact_version: type: string error_message: type: string completed_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - resource - operation - status - created_at - updated_at ProjectDeploymentResource: type: object description: The resource this deployment belongs to. properties: type: type: string enum: - function - frontend id: type: string format: uuid name: type: string required: - type - id - name ProjectUsageResponse: type: object description: Aggregated usage metrics for a project. properties: project_id: type: string format: uuid description: Project ID month: type: string description: Usage month in YYYY-MM format example: 2026-02 metrics: type: array description: Usage metrics for the project items: $ref: '#/components/schemas/MetricUsageData' frontends: type: array description: Per-frontend request totals for the current usage month items: $ref: '#/components/schemas/FrontendUsageData' required: - project_id - month - metrics RealtimeConfig: type: object description: | Realtime configuration for a project. Note: Message size and channels per connection are plan-based (not configurable). properties: project_id: type: string format: uuid description: Project ID enabled: type: boolean description: Whether realtime is enabled for this project default: false broadcast_enabled: type: boolean description: Whether broadcast channels are enabled default: true presence_enabled: type: boolean description: Whether presence tracking is enabled default: true postgres_changes_enabled: type: boolean description: Whether Postgres change notifications are enabled default: true created_at: type: string format: date-time description: When the configuration was created updated_at: type: string format: date-time description: When the configuration was last updated RealtimePlanLimits: type: object description: Plan-based limits for realtime features properties: plan: type: string description: Plan name (FREE or PRO) example: FREE max_connections: type: integer description: Maximum concurrent connections allowed example: 100 messages_per_month: type: integer description: Maximum messages per month example: 1000000 message_size_kb: type: integer description: Maximum message size in KB example: 32 channels_per_conn: type: integer description: Maximum channels per connection example: 100 RealtimeStats: type: object description: Realtime usage statistics for a project properties: num_connections: type: integer description: Current number of active connections peak_connections: type: integer description: Peak concurrent connections this usage period last_invoked_at: type: string format: date-time description: Most recent realtime activity timestamp across channels limits: $ref: '#/components/schemas/RealtimePlanLimits' ResolveFunctionResponse: type: object properties: name: type: string maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ description: DNS-safe function name function_id: type: string format: uuid description: Canonical function ID used for invocation routing cache_ttl_seconds: type: integer minimum: 1 description: Suggested SDK cache TTL for this name-to-ID mapping required: - name - function_id - cache_ttl_seconds ScheduleRequest: type: object required: - cron_expression properties: kind: type: string enum: - cron default: cron cron_expression: type: string description: Standard 5-field cron expression evaluated in UTC. Seconds fields, descriptors, and Quartz syntax are not supported. example: '*/5 * * * *' ServiceKey: type: object description: | Service role key for admin operations. **WARNING:** Bypasses all RLS - backend use only! properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string description: Descriptive name for the key key_value: type: string description: | Full JWT token for Authorization header. Returned on create, get, and list (decrypted from storage). **Store securely - NEVER expose in frontend code!** key_prefix: type: string description: First 12 characters of the key for display/identification maxLength: 12 permissions: type: array items: type: string description: | Operations this key may perform. ["*"] grants full admin access (default for keys created without an explicit scope). Scoped keys list specific permissions, e.g. ["functions.invoke"]. example: - '*' created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - key_prefix - permissions StorageBucket: type: object description: | A named container for files within a project. Public access is controlled at the file level via is_public on StorageObject. properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string description: Bucket name (unique within project) pattern: ^[a-zA-Z0-9_-]+$ minLength: 1 maxLength: 64 file_size_limit: type: integer format: int64 nullable: true description: Maximum file size in bytes (null for no limit) allowed_mime_types: type: array nullable: true items: type: string description: Allowed MIME types (null for all types) last_invoked_at: type: string format: date-time description: Most recent bucket operation timestamp created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name StorageCopyRequest: type: object properties: from: type: string description: Source path to: type: string description: Destination path required: - from - to StorageListResponse: type: object properties: objects: type: array items: $ref: '#/components/schemas/StorageObject' next_cursor: type: string description: Cursor for next page (empty if no more results) StorageMoveRequest: type: object properties: from: type: string description: Source path to: type: string description: Destination path required: - from - to StorageObject: type: object properties: id: type: string format: uuid bucket_id: type: string format: uuid name: type: string description: Full path within bucket (e.g., "users/abc123/avatar.png") owner_id: type: string format: uuid nullable: true description: Auth user who uploaded (null for anonymous/service) is_public: type: boolean default: false description: | If true, the file can be downloaded with just an anon key (no user authentication). Files are private by default. Only the owner or a service key can change visibility. size: type: integer format: int64 description: File size in bytes mime_type: type: string description: MIME type etag: type: string description: S3 ETag for cache validation metadata: type: object additionalProperties: true description: | Custom user metadata (key-value pairs). Limits: Maximum 50 keys, maximum 10KB total serialized size. created_at: type: string format: date-time updated_at: type: string format: date-time public_url: type: string format: uri description: | Shareable public URL for this file (only set for public files with is_public=true). This URL requires NO authentication and can be embedded in HTML, shared via email, etc. The URL is properly URL-encoded by the server - use it as-is without additional encoding. required: - id - bucket_id - name - is_public - size - mime_type StorageObjectWithBucket: type: object description: Storage object with bucket name included (for admin listing across buckets) properties: id: type: string format: uuid bucket_id: type: string format: uuid bucket_name: type: string description: Name of the bucket containing this object name: type: string description: Full path within bucket owner_id: type: string format: uuid nullable: true description: Auth user who uploaded (null for anonymous/service) is_public: type: boolean default: false size: type: integer format: int64 description: File size in bytes mime_type: type: string etag: type: string metadata: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time public_url: type: string format: uri description: | Shareable public URL for this file (only set for public files with is_public=true). This URL requires NO authentication and can be embedded in HTML, shared via email, etc. required: - id - bucket_id - bucket_name - name - is_public - size - mime_type StoragePolicy: type: object properties: id: type: string format: uuid bucket_id: type: string format: uuid name: type: string description: Policy name (unique within bucket) operation: type: string enum: - SELECT - INSERT - UPDATE - DELETE description: Operation this policy applies to definition: type: string description: | Policy expression evaluated at request time. Examples: - "true" - Allow all - "auth.uid() = owner_id" - Owner only - "auth.role() = 'authenticated'" - Authenticated users - "(storage.foldername(name))[1] = auth.uid()::text" - User's folder created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - bucket_id - name - operation - definition StorageStats: type: object description: Aggregate storage statistics for a project properties: bucket_count: type: integer description: Number of storage buckets object_count: type: integer description: Total number of stored files total_size: type: integer format: int64 description: Total storage used in bytes required: - bucket_count - object_count - total_size StorageVisibilityRequest: type: object properties: is_public: type: boolean description: Whether the file should be publicly accessible required: - is_public UnbanUserResponse: type: object description: Response when unbanning a user properties: message: type: string example: User unbanned successfully user_id: type: string format: uuid email: type: string format: email status: type: string enum: - active required: - message - user_id - email - status TestEmailRequest: type: object required: - to_email description: | When `html_body` or `text_body` is provided the backend renders those (plus optional `subject`) through html/text templates against the standard `Data` (ProjectName, Name, SiteURL) and sends the result — used by the template-editor "Send Test" affordance to preview an unsaved template. When both bodies are omitted a hardcoded diagnostic message is sent to verify SMTP credentials and `subject` is ignored. Sending `subject` alone (without a body) is rejected with 400. properties: to_email: type: string format: email description: Recipient address for the diagnostic email. subject: type: string description: | Optional subject override, rendered as a text/template. Only applied on the override path — requires `html_body` or `text_body` to also be set, otherwise the request is rejected with 400. html_body: type: string maxLength: 262144 description: Optional HTML body override. Rendered as an html/template. Max 256 KiB. text_body: type: string maxLength: 262144 description: Optional plain-text body override. Rendered as a text/template. Max 256 KiB. TestEmailResponse: type: object required: - success properties: success: type: boolean UpdateAuthConfigRequest: type: object description: 'All fields optional - only include fields you want to update. Validation rule: require_email_confirmation=true requires email_enabled=true.' properties: access_token_lifetime: type: integer refresh_token_lifetime: type: integer inactivity_timeout: type: integer max_session_duration: type: integer min_password_length: type: integer require_uppercase: type: boolean require_lowercase: type: boolean require_numbers: type: boolean require_special_chars: type: boolean enable_signup: type: boolean description: Master switch for signups across ALL providers enable_email_password: type: boolean description: Enable/disable email/password provider rate_limit_signup: type: integer rate_limit_signin: type: integer rate_limit_token_refresh: type: integer cors_allow_credentials: type: boolean cors_max_age: type: integer enable_anonymous_signins: type: boolean allow_password_reset: type: boolean password_reset_timeout: type: integer max_password_history: type: integer require_email_confirmation: type: boolean description: Require users to confirm email before sign-in. Can only be true when email_enabled is true. email_confirmation_timeout: type: integer description: Email confirmation token expiry in seconds. email_enabled: type: boolean description: Enable transactional email sending. Cannot be false while require_email_confirmation is true. email_from_address: type: string email_from_name: type: string smtp_host: type: string smtp_port: type: integer smtp_username: type: string smtp_password: type: string format: password description: SMTP password (sensitive). Encrypted at rest (AES-256-GCM) when stored. smtp_use_tls: type: boolean email_confirmation_subject: type: string email_password_reset_subject: type: string email_password_changed_subject: type: string managed_auth_enabled: type: boolean description: Enable or disable managed auth hosted pages for the project. post_auth_redirect_url: type: string description: Must be included in allowed_redirect_urls when set. allowed_redirect_urls: type: array items: type: string description: Redirect allowlist. Every entry must be a valid http/https URL. post_logout_redirect_url: type: string description: Must be included in allowed_redirect_urls when set. device_verification_url: type: string description: | Optional custom device-authorization verification page. Must be a valid http/https URL (not tied to allowed_redirect_urls). When set, device-code logins return this URL (with user_code) instead of the managed device page. Send an empty string to clear the override. UpdateAuthHostedPageRequest: type: object required: - html properties: html: type: string description: Raw HTML markup for the page. Max 256 KiB. css: type: string description: Optional CSS injected at render time. Max 256 KiB. UpdateDatabaseTypeRequest: type: object description: Update database compute size tier properties: database_type: type: string description: New compute size tier enum: - volcano-db-xs - volcano-db-s - volcano-db-m - volcano-db-l - volcano-db-xl - volcano-db-2xl example: volcano-db-m required: - database_type UpdateEmailTemplateRequest: type: object properties: subject: type: string html_body: type: string text_body: type: string UpdateFunctionRequest: type: object properties: is_public: type: boolean description: | Function visibility for anon-key invocation. - `false` (default): private function - `true`: public function (anon keys with `functions.invoke` can invoke) required: - is_public UpdateFunctionSchedulerRequest: type: object properties: name: type: string enabled: type: boolean schedule: $ref: '#/components/schemas/ScheduleRequest' payload: type: object additionalProperties: true regions: type: array maxItems: 1 items: type: string UpdateOAuthConfigRequest: type: object properties: client_id: type: string description: Supported for non-device providers. Not supported for `provider=device`. client_secret: type: string description: Supported for non-device providers. Not supported for `provider=device`. redirect_url: type: string format: uri scopes: type: array items: type: string enabled: type: boolean UpdateProjectRequest: type: object description: Update mutable project fields (name and/or region policy) properties: name: type: string minLength: 1 maxLength: 255 example: my-awesome-app-renamed all_regions: type: boolean description: | If omitted and `selected_regions` is also omitted, existing region policy is preserved. If `selected_regions` is provided without `all_regions`, it is treated as subset mode. selected_regions: type: array items: type: string description: | Region subset for project deployments. Provide with `all_regions=false`. example: - us-east-1 UpdateRealtimeConfigRequest: type: object description: | Request to update realtime configuration. Limits (message size, channels per connection) are plan-based and cannot be configured. properties: enabled: type: boolean description: Whether realtime is enabled for this project broadcast_enabled: type: boolean description: Whether broadcast channels are enabled presence_enabled: type: boolean description: Whether presence tracking is enabled postgres_changes_enabled: type: boolean description: Whether Postgres change notifications are enabled UpdateStorageBucketRequest: type: object properties: file_size_limit: type: integer format: int64 allowed_mime_types: type: array items: type: string UpdateVariableRequest: type: object properties: value: type: string required: - value UploadSessionPart: type: object description: Information about an uploaded part properties: part_number: type: integer description: Part number (1-10000) etag: type: string description: ETag of the uploaded part size: type: integer format: int64 description: Size of the part in bytes UploadSessionStatusResponse: type: object description: Status of an upload session properties: session_id: type: string description: Upload session ID status: type: string enum: - pending - uploading - completing - completed - aborted description: Current status of the upload path: type: string description: Target file path content_type: type: string description: MIME type total_size: type: integer format: int64 description: Total file size in bytes part_size: type: integer format: int64 description: Size of each part (except last) total_parts: type: integer description: Total number of parts parts_uploaded: type: integer description: Number of parts uploaded bytes_uploaded: type: integer format: int64 description: Total bytes uploaded so far parts: type: array description: List of uploaded parts (for resume) items: $ref: '#/components/schemas/UploadSessionPart' expires_at: type: string format: date-time description: Session expiry time created_at: type: string format: date-time description: Session creation time UsageDataPoint: type: object description: A single timestamped usage value. properties: timestamp: type: string format: date-time description: UTC timestamp for the data point value: type: integer format: int64 description: Usage value at the timestamp required: - timestamp - value Variable: type: object properties: id: type: string format: uuid project_id: type: string format: uuid name: type: string maxLength: 256 value: type: string status: type: string enum: - provisioning - active - failed description: Latest project variable propagation status, when a sync has run. current_sync_id: type: string format: uuid description: Identifier of the latest variable propagation sync. provisioning_started_at: type: string format: date-time description: Timestamp when the current variable propagation phase started. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - project_id - name - value - created_at - updated_at DatabaseQueryPerformanceDatabase: type: object properties: id: type: string format: uuid name: type: string required: - id - name DatabaseQueryPerformanceItem: type: object properties: query_id: type: string description: pg_stat_statements query identifier. query: type: string maxLength: 8192 description: Normalized and obfuscated representative query text. database: $ref: '#/components/schemas/DatabaseQueryPerformanceDatabase' role: type: string description: Database role used for the query. calls: type: integer format: int64 total_exec_time_seconds: type: number format: double description: Cumulative total execution time from pg_stat_statements in seconds. max_exec_time_seconds: type: number format: double mean_exec_time_seconds: type: number format: double min_exec_time_seconds: type: number format: double rows_processed: type: integer format: int64 required: - query_id - query - database - role - calls - total_exec_time_seconds - max_exec_time_seconds - mean_exec_time_seconds - min_exec_time_seconds - rows_processed LogDeploymentRequestSelector: type: object description: Deployment log selector for deployable resources. additionalProperties: false properties: ids: type: array maxItems: 25 description: Optional deployment identifiers. Omit or send an empty array to include every deployment for the selected resources. items: type: string format: uuid LogFunctionRequestResource: type: object description: Edge Function log resource selector. additionalProperties: false properties: type: type: string enum: - function description: Resource type to read logs for. ids: type: array maxItems: 25 description: Optional function identifiers. Omit or send an empty array to include every function in the project. items: type: string format: uuid deployments: $ref: '#/components/schemas/LogDeploymentRequestSelector' required: - type LogFrontendRequestResource: type: object description: Frontend log resource selector. additionalProperties: false properties: type: type: string enum: - frontend description: Resource type to read logs for. ids: type: array maxItems: 25 description: Optional frontend identifiers. Omit or send an empty array to include every frontend in the project. items: type: string format: uuid deployments: $ref: '#/components/schemas/LogDeploymentRequestSelector' required: - type LogDatabaseRequestResource: type: object description: Database runtime log resource selector. Deployment logs are not supported for databases. additionalProperties: false properties: type: type: string enum: - database description: Resource type to read logs for. ids: type: array maxItems: 25 description: Optional database identifiers. Omit or send an empty array to include every database in the project. items: type: string format: uuid required: - type LogRequestResource: description: Resource selectors for project log reads. oneOf: - $ref: '#/components/schemas/LogFunctionRequestResource' - $ref: '#/components/schemas/LogFrontendRequestResource' - $ref: '#/components/schemas/LogDatabaseRequestResource' discriminator: propertyName: type mapping: function: '#/components/schemas/LogFunctionRequestResource' frontend: '#/components/schemas/LogFrontendRequestResource' database: '#/components/schemas/LogDatabaseRequestResource' LogResource: type: object description: Resource that owns a historical log event. properties: type: type: string enum: - function - frontend - database description: Resource type that owns the log event. id: type: string format: uuid description: Resource ID that owns the log event. name: type: string description: Resource name associated with the log event, when available. required: - type - id LogDeployment: type: object description: Deployment context associated with a historical deployment log event. properties: id: type: string format: uuid description: Deployment ID associated with the log event. stage: type: string enum: - compile - publish description: Deployment stage that produced the log event, when available. required: - id FunctionRuntimeDeployment: type: object required: - file_extensions - entrypoint - handler - dependency_manifests properties: file_extensions: type: array description: Source file extensions the CLI can use to detect this runtime. items: type: string example: - .js - .mjs entrypoint: type: string description: Archive path the CLI should use for a single-file function source. example: index.js handler: type: string description: Handler symbol the CLI should submit when deploying this runtime. example: handler dependency_manifests: type: array description: Dependency manifest files the CLI should include for hosted builds. items: type: string example: - package.json - package-lock.json