{ "openapi": "3.0.0", "info": { "title": "Xata API", "description": "Xata API", "version": "1.0", "contact": { "name": "help@xata.io" } }, "servers": [ { "url": "https://api.xata.tech", "description": "xata PROD" }, { "url": "https://api.staging.maki.cooking", "description": "xata STAGING" }, { "url": "https://api.dev.maki.cooking", "description": "xata DEV" } ], "tags": [ { "name": "Organizations", "description": "Operations for creating, retrieving, updating, and deleting organizations", "x-displayName": "Organizations" }, { "name": "Users", "description": "Operations for managing user accounts and profiles", "x-displayName": "Users" }, { "name": "API Keys", "description": "Operations for managing API keys, including creation, listing, and deletion", "x-displayName": "API Keys" }, { "name": "Marketplace", "description": "Operations for linking user accounts to cloud marketplace subscriptions", "x-displayName": "Marketplace" }, { "name": "Gateway", "description": "PostgreSQL connectivity via HTTP SQL, WebSocket wire protocol proxy, and native wire protocol.", "x-displayName": "Gateway" }, { "name": "Projects", "description": "Operations for creating, retrieving, updating, and deleting projects within an organization", "x-displayName": "Projects" }, { "name": "Branches", "description": "Operations for managing database branches within projects, including creation, configuration, and deletion", "x-displayName": "Branches" }, { "name": "GitHub App", "description": "Operations for managing GitHub App installation mappings", "x-displayName": "GitHub App" }, { "name": "Metrics", "x-displayName": "Metrics" }, { "name": "Webhooks", "x-displayName": "Webhooks" } ], "externalDocs": { "url": "https://xata.io/docs/api" }, "paths": { "/organizations": { "summary": "Organizations Management", "description": "This endpoint enables creating and listing organizations within Xata. Organizations are the top-level entity that contains projects, branches, and team members.", "get": { "operationId": "getOrganizationsList", "summary": "Get list of organizations", "description": "Retrieve the list of all organizations the authenticated user belongs to, including their IDs and names. This endpoint allows users to view all organizations they have access to.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations": { "description": "List of organizations the user has access to", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the organization", "$ref": "#/components/schemas/OrganizationID" }, "name": { "description": "Human-readable name of the organization", "type": "string" }, "status": { "description": "Current status of the organization", "$ref": "#/components/schemas/OrganizationStatus" } }, "required": [ "id", "name", "status" ] } } }, "required": [ "organizations" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Organizations" ] }, "post": { "operationId": "createOrganization", "summary": "Create a new organization", "description": "Creates a new organization with the authenticated user as its single owner.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } } }, "responses": { "201": { "description": "Organization successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}": { "summary": "Organization Operations", "description": "This endpoint provides operations for a specific organization, allowing retrieval, updating, and deletion of an organization by its unique identifier.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "getOrganization", "summary": "Get organization details", "description": "Retrieve detailed information about a specific organization by its ID.", "responses": { "200": { "description": "Organization details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Organizations" ] }, "put": { "operationId": "updateOrganization", "summary": "Update organization details", "description": "Update information for an existing organization, such as its name.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "Unique identifier for the organization to update", "$ref": "#/components/schemas/OrganizationID" }, "name": { "description": "New name for the organization", "type": "string" } } } } } }, "responses": { "200": { "description": "Organization successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ] }, "delete": { "operationId": "deleteOrganization", "summary": "Delete an organization", "description": "[Not implemented yet] Permanently delete an organization. This action cannot be undone.", "responses": { "204": { "description": "Organization successfully deleted" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}/api-keys": { "get": { "operationId": "listOrganizationAPIKeys", "summary": "List API Keys for an organization", "description": "Retrieve a list of API keys for a specific organization.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "responses": { "200": { "description": "List of API keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "description": "Array of API keys for the organization", "type": "array", "items": { "$ref": "#/components/schemas/APIKeyPreview" } } }, "required": [ "keys" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "keys:read" ] } ], "tags": [ "API Keys" ] }, "post": { "operationId": "createOrganizationAPIKey", "summary": "Create an Organization API Key", "description": "Create a new API key for an organization.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAPIKeyRequest" } } } }, "responses": { "201": { "description": "API Key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FullAPIKey" } }, "required": [ "key" ] } } } }, "400": { "description": "API key limit reached or invalid request" } }, "security": [ { "xata": [ "keys:write" ] } ], "tags": [ "API Keys" ] }, "delete": { "operationId": "deleteOrganizationAPIKeys", "summary": "Bulk delete API Keys for an organization", "description": "Delete multiple API keys in a single request.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "description": "Array of API key IDs to delete", "type": "array", "items": { "type": "string" }, "maxItems": 50 } }, "required": [ "ids" ] } } } }, "responses": { "204": { "description": "API Keys deleted successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" } }, "security": [ { "xata": [ "keys:write" ] } ], "tags": [ "API Keys" ] } }, "/organizations/{organizationID}/members": { "get": { "operationId": "listOrganizationMembers", "summary": "List members of an organization", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/UserWithID" } } }, "required": [ "members" ] } } } } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}/members/{userID}": { "delete": { "operationId": "removeOrganizationMember", "summary": "Remove a member from an organization", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/UserIDParam" } ], "responses": { "204": { "description": "Member removed" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}/invitations": { "get": { "operationId": "listOrganizationInvitations", "summary": "List invitations for an organization", "description": "Retrieve all invitations for an organization with optional filtering by status, email, and name.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "name": "status", "in": "query", "description": "Filter invitations by status", "schema": { "type": "string", "enum": [ "pending", "expired" ] } }, { "name": "email", "in": "query", "description": "Filter invitations by email address", "schema": { "type": "string" } }, { "name": "first_name", "in": "query", "description": "Filter invitations by first name", "schema": { "type": "string" } }, { "name": "last_name", "in": "query", "description": "Filter invitations by last name", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search invitations by email or name", "schema": { "type": "string" } }, { "name": "first", "in": "query", "description": "Index of the first result to return (0-based offset for pagination)", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "max", "in": "query", "description": "Maximum number of results to return", "schema": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List of invitations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInvitation" } } }, "required": [ "invitations" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "invite:read" ] } ], "tags": [ "Organizations" ] }, "post": { "operationId": "createOrganizationInvitation", "summary": "Send an invitation to join an organization", "description": "Send an invitation email to a user to join an organization.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInvitationRequest" } } } }, "responses": { "201": { "description": "Invitation sent successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "409": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "invite:write" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}/invitations/{invitationID}": { "get": { "operationId": "getOrganizationInvitation", "summary": "Get details of a specific invitation", "description": "Retrieve detailed information about a specific invitation by its ID.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/InvitationIDParam" } ], "responses": { "200": { "description": "Invitation details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitation" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "invite:read" ] } ], "tags": [ "Organizations" ] }, "delete": { "operationId": "deleteOrganizationInvitation", "summary": "Delete an invitation", "description": "Permanently delete an invitation record.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/InvitationIDParam" } ], "responses": { "204": { "description": "Invitation deleted successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "invite:write" ] } ], "tags": [ "Organizations" ] } }, "/organizations/{organizationID}/invitations/{invitationID}/resend": { "post": { "operationId": "resendOrganizationInvitation", "summary": "Resend an invitation", "description": "Resend a pending invitation with a fresh expiration time.", "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/InvitationIDParam" } ], "responses": { "204": { "description": "Invitation resent successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "invite:write" ] } ], "tags": [ "Organizations" ] } }, "/marketplace/register": { "post": { "operationId": "registerMarketplace", "summary": "Register with a cloud marketplace", "description": "Links the authenticated user to a cloud marketplace subscription. Only one marketplace registration is allowed per user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceRegisterRequest" } } } }, "responses": { "200": { "description": "Marketplace registration successful" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "409": { "$ref": "#/components/responses/SimpleError" }, "502": { "description": "Marketplace registration provider failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } }, "security": [ { "xata": [ "marketplace:write" ] } ], "tags": [ "Marketplace" ], "x-excluded": true } }, "/api-keys": { "get": { "operationId": "listUserAPIKeys", "summary": "List API Keys for the authenticated user", "description": "Retrieve a list of API keys for the authenticated user.", "responses": { "200": { "description": "List of API keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "description": "Array of API keys for the user", "type": "array", "items": { "$ref": "#/components/schemas/APIKeyPreview" } } }, "required": [ "keys" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "keys:read" ] } ], "tags": [ "API Keys" ] }, "post": { "operationId": "createUserAPIKey", "summary": "Create a User API Key", "description": "Create a new API key for the authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAPIKeyRequest" } } } }, "responses": { "201": { "description": "API Key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FullAPIKey" } }, "required": [ "key" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "keys:write" ] } ], "tags": [ "API Keys" ] }, "delete": { "operationId": "deleteUserAPIKeys", "summary": "Bulk delete API Keys for the authenticated user", "description": "Delete multiple API keys in a single request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "description": "Array of API key IDs to delete (maximum 50 keys per request)", "type": "array", "items": { "type": "string" }, "maxItems": 50 } }, "required": [ "ids" ] } } } }, "responses": { "204": { "description": "API Keys deleted successfully" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "keys:write" ] } ], "tags": [ "API Keys" ] } }, "/sql": { "servers": [ { "url": "https://{branch}.{region}.xata.tech", "description": "xata PROD", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } }, { "url": "https://{branch}.{region}.staging.maki.cooking", "description": "xata STAGING", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } }, { "url": "https://{branch}.{region}.dev.maki.cooking", "description": "xata DEV", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } } ], "post": { "operationId": "query", "summary": "Execute SQL query", "description": "Execute a single SQL query or a batch of queries against a PostgreSQL branch.\n\n**Single query:** provide `query` (and optional `params`) at the top level.\n\n**Batch:** provide `queries` as an array of query objects, or send the request body\nas a JSON array. Batch queries execute within a single transaction.\n", "parameters": [ { "name": "Connection-String", "in": "header", "description": "PostgreSQL connection string (`postgres://user:pass@host/db`). The hostname encodes the target branch and endpoint type.", "required": false, "schema": { "type": "string", "format": "uri" } }, { "name": "Array-Mode", "in": "header", "description": "When `true`, return rows as arrays instead of objects.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "Raw-Text-Output", "in": "header", "description": "When `true`, return all values as strings without type conversion.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "Batch-Isolation-Level", "in": "header", "description": "Transaction isolation level for batch queries.", "required": false, "schema": { "type": "string", "enum": [ "ReadCommitted", "ReadUncommitted", "RepeatableRead", "Serializable" ] } }, { "name": "Batch-Read-Only", "in": "header", "description": "When `true`, execute the batch transaction in read-only mode.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "Batch-Deferrable", "in": "header", "description": "When `true`, execute the batch transaction in deferrable mode.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SQLRequest" } } } }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QueryResult" }, { "$ref": "#/components/schemas/BatchResponse" } ] } } } }, "400": { "description": "Invalid request or SQL error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid connection string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Response too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "Gateway" ] } }, "/v2": { "servers": [ { "url": "https://{branch}.{region}.xata.tech", "description": "xata PROD", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } }, { "url": "https://{branch}.{region}.staging.maki.cooking", "description": "xata STAGING", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } }, { "url": "https://{branch}.{region}.dev.maki.cooking", "description": "xata DEV", "variables": { "branch": { "default": "my-branch" }, "region": { "default": "us-east-1" } } } ], "get": { "operationId": "websocket", "summary": "WebSocket wire protocol proxy", "description": "Upgrade to a WebSocket connection that proxies the PostgreSQL wire protocol.\nThe client sends and receives PostgreSQL protocol messages over binary WebSocket frames.\n\nAuthentication is handled via the PostgreSQL startup message within the wire protocol,\nusing the same connection-string hostname conventions as the HTTP SQL endpoint.\n", "responses": { "101": { "description": "Switching Protocols — WebSocket connection established" }, "400": { "description": "Bad request — unable to upgrade connection" } }, "tags": [ "Gateway" ] } }, "/organizations/{organizationID}/regions": { "summary": "Region Operations", "description": "Endpoints for retrieving available regions for deploying projects within an organization.", "get": { "operationId": "listRegions", "summary": "Get available regions", "description": "Retrieves a list of all regions where new branches can be deployed for the specified organization.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to check region availability for", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "responses": { "200": { "description": "List of regions available for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "regions": { "description": "Array of available regions with their properties", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the region", "type": "string" }, "publicAccess": { "description": "Whether data plane is public-facing to the internet in this region", "type": "boolean" }, "backupsEnabled": { "description": "Whether backups are enabled for branches created in this region", "type": "boolean" }, "organizationId": { "description": "Organization that owns this region, if set the region is only available to this organization", "type": "string", "nullable": true } }, "required": [ "id", "publicAccess", "backupsEnabled", "organizationId" ] } } }, "required": [ "regions" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/instanceTypes": { "summary": "Instance Types Operations", "description": "Endpoints for retrieving available instance types for creating branches within an organization.", "get": { "operationId": "listInstanceTypes", "summary": "Get available instance types", "description": "Retrieves a list of all instance types for the specified organization and region", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to check instance type availability for", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "region", "in": "query", "description": "Region to check instance type availability for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of instance types available for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceTypes": { "description": "Array of available instance types with their properties", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Instance type name", "type": "string" }, "vcpus": { "description": "number of vCPUs", "type": "integer" }, "ram": { "description": "memory in Gi", "type": "integer" }, "hourlyRate": { "description": "price per hour for this instance type and region", "type": "number", "format": "double" }, "storageMonthlyRate": { "description": "price per month for a GB of storage for this region", "type": "number", "format": "double" }, "region": { "description": "region where this instance type is available", "type": "string" } }, "required": [ "name", "vcpus", "ram", "hourlyRate", "region", "storageMonthlyRate" ] } } }, "required": [ "instanceTypes" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/images": { "summary": "Images Operations", "description": "Endpoints for retrieving available images for creating branches within an organization.", "get": { "operationId": "listImages", "summary": "Get available images", "description": "Retrieves a list of all images for the specified organization and region", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to check image availability", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "region", "in": "query", "description": "Region to check image availability for organization", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of images available for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "description": "Array of available images with their properties", "type": "array", "items": { "$ref": "#/components/schemas/Image" } } }, "required": [ "images" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/extensions": { "summary": "Extensions Operations", "description": "Endpoints for retrieving available extensions of images used for creating branches within an organization.", "get": { "operationId": "listExtensions", "summary": "Get available extensions for image", "description": "Retrieves a list of all extensions for the specified image in the organization and region given", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to check instance type availability for", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "image", "in": "query", "description": "Image for which we list extensions", "required": true, "schema": { "type": "string" } }, { "name": "region", "in": "query", "description": "Region to list extensions for image in", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of extensions available for the image in the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "extensions": { "description": "Array of available images with their properties", "type": "array", "items": { "$ref": "#/components/schemas/Extension" } } }, "required": [ "extensions" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Projects" ], "x-excluded": true, "x-internal": true } }, "/organizations/{organizationID}/projects/limits": { "summary": "Project Limits", "description": "Endpoint for retrieving the default resource limits for projects within an organization.", "get": { "operationId": "getDefaultProjectLimits", "summary": "Get project resource limits", "description": "Retrieves the default resource limits for projects in the specified organization, including maximum instances, storage, and allowed regions.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to get project limits for", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "responses": { "200": { "description": "Default resource limits for projects in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLimits" } } } } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/projects": { "summary": "Projects Management", "description": "Endpoints for listing and creating projects within an organization.", "get": { "operationId": "listProjects", "summary": "List all projects", "description": "Retrieves a list of all projects within the specified organization that the authenticated user has access to.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to list projects from", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "responses": { "200": { "description": "A list of projects within the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "description": "Array of project objects with their metadata", "type": "array", "items": { "$ref": "#/components/schemas/Project" } } }, "required": [ "projects" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ] }, "post": { "operationId": "createProject", "summary": "Create a new project", "description": "Creates a new project within the specified organization. Projects are containers for database branches and resources.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization to create the project in", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Human-readable name for the new project", "type": "string" }, "configuration": { "$ref": "#/components/schemas/ProjectConfiguration" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Project successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/projects/{projectID}": { "summary": "Project Operations", "description": "Endpoints for retrieving, updating, and deleting a specific project by ID.", "get": { "operationId": "getProject", "summary": "Get project details", "description": "Retrieves detailed information about a specific project by its ID within the specified organization.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to retrieve", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ] }, "patch": { "operationId": "updateProject", "summary": "Update project details", "description": "Updates the details of a specific project by its ID, such as changing its name.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name for the project", "type": "string" }, "configuration": { "$ref": "#/components/schemas/UpdateProjectConfiguration" } } } } } }, "responses": { "200": { "description": "Project successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "Projects" ] }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "description": "Permanently deletes a specific project by its ID and all associated resources including branches and databases. This action cannot be undone.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Project successfully deleted" }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "Projects" ] } }, "/organizations/{organizationID}/projects/{projectID}/backups": { "summary": "Backups Operations", "description": "Endpoints for managing project backups.", "get": { "operationId": "listBackups", "summary": "List project backups", "description": "Retrieves a list of backups for the specified project.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to retrieve backups for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of backups within the project", "content": { "application/json": { "schema": { "type": "object", "properties": { "backups": { "description": "list of backups within the project", "type": "array", "items": { "$ref": "#/components/schemas/BackupMetadata" } } }, "required": [ "backups" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ], "x-excluded": true, "x-internal": true } }, "/organizations/{organizationID}/projects/{projectID}/backups/{backupID}": { "summary": "Backup Operations", "description": "Endpoints for getting project backup.", "get": { "operationId": "getBackup", "summary": "Get project backup by ID", "description": "Retrieves a backup by ID for the specified project.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to retrieve backups for", "required": true, "schema": { "type": "string" } }, { "name": "backupID", "in": "path", "description": "Unique identifier of the backup for the project", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The backup metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupMetadata" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ], "x-excluded": true, "x-internal": true } }, "/organizations/{organizationID}/projects/{projectID}/branches": { "summary": "Branch Management", "description": "Endpoints for listing and creating branches within a project.", "get": { "operationId": "listBranches", "summary": "List all branches", "description": "Retrieves a list of all branches within the specified project, including their metadata, region, and access settings.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to list branches from", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of branches within the project", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "description": "Array of branch objects with their metadata", "type": "array", "items": { "$ref": "#/components/schemas/BranchListMetadata" } } }, "required": [ "branches" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:read" ] } ], "tags": [ "Branches" ] }, "post": { "operationId": "createBranch", "summary": "Create a new branch", "description": "Creates a new branch within the specified project. Branches can be created from scratch or derived from an existing parent branch.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project to create the branch in", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCreationDetails" } } } }, "responses": { "201": { "description": "Branch successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchShortMetadata" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "412": { "$ref": "#/components/responses/PreconditionFailedError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:write" ] } ], "tags": [ "Branches" ] } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}": { "summary": "Branch Operations", "description": "Endpoints for retrieving, updating, and deleting a specific branch by ID.", "get": { "operationId": "describeBranch", "summary": "Get branch details", "description": "Retrieves detailed information about a specific branch by its ID, including status, connection string, and configuration.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project containing the branch", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch to retrieve details for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Branch details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMetadata" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:read" ] } ], "tags": [ "Branches" ] }, "patch": { "operationId": "updateBranch", "summary": "Update branch details", "description": "Updates the configuration of a specific branch by its ID, such as changing its name, description, or resource allocation.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project containing the branch", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchUpdateDetails" } } } }, "responses": { "200": { "description": "Branch successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchShortMetadata" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:write" ] } ], "tags": [ "Branches" ] }, "delete": { "operationId": "deleteBranch", "summary": "Delete a branch", "description": "Permanently deletes a specific branch by its ID and all associated data. This action cannot be undone.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project containing the branch", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Branch successfully deleted" }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:write" ] } ], "tags": [ "Branches" ] } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentials": { "get": { "operationId": "getBranchCredentials", "summary": "Retrieve branch credentials", "parameters": [ { "name": "organizationID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "query", "description": "Username that the credentials requested for", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credentials for the branch retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchCredentials" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "credentials:read" ] } ], "tags": [ "Branches" ] } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics": { "post": { "operationId": "branchMetrics", "summary": "Retrieve branch metrics", "parameters": [ { "name": "organizationID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMetricsRequest" } } } }, "responses": { "200": { "description": "Metrics for a branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchMetrics" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "metrics:read" ] } ], "tags": [ "Branches", "Metrics" ] } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/restore": { "summary": "Restore from backup", "description": "Endpoint for restoring from a backup.", "post": { "operationId": "restoreFromBackup", "summary": "Create a new branch from a backup of another branch", "description": "Creates a new backup branch within the specified project.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project containing the source branch", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the source branch of the backup", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreDetails" } } } }, "responses": { "201": { "description": "Branch successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchShortMetadata" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:write" ] } ], "tags": [ "Branches" ], "x-excluded": true, "x-internal": true } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/postgres-config": { "get": { "operationId": "getBranchPostgresConfig", "summary": "Get PostgreSQL configuration details", "description": "Retrieves detailed information about the current PostgreSQL configuration parameters for a branch, including parameter types, descriptions, acceptable ranges, default values, and current values.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization containing the project", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project containing the branch", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch to retrieve PostgreSQL configuration for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PostgreSQL configuration details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostgresConfigDetails" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "branch:read" ] } ], "tags": [ "Branches" ] } }, "/organizations/{organizationID}/githubapp/installations": { "summary": "GitHub App Installation Operations (organization-scoped)", "description": "Manage GitHub App installations for an organization.", "get": { "operationId": "listGithubAppInstallations", "summary": "List GitHub App installations for organization", "description": "Returns all GitHub App installations associated with the specified organization.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "responses": { "200": { "description": "List of GitHub App installations", "content": { "application/json": { "schema": { "type": "object", "properties": { "installations": { "description": "Array of GitHub App installations", "type": "array", "items": { "$ref": "#/components/schemas/GithubInstallation" } } }, "required": [ "installations" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "GitHub App" ] }, "post": { "operationId": "createGithubAppInstallation", "summary": "Create GitHub App installation", "description": "Creates a new GitHub App installation mapping for the specified organization.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGithubAppInstallationRequest" } } } }, "responses": { "201": { "description": "Installation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubInstallation" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "409": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "GitHub App" ] } }, "/organizations/{organizationID}/githubapp/installations/{githubInstallationID}": { "summary": "GitHub App Installation Operations by ID", "description": "Manage a specific GitHub App installation.", "put": { "operationId": "updateGithubAppInstallation", "summary": "Update GitHub App installation", "description": "Updates an existing GitHub App installation mapping.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "githubInstallationID", "in": "path", "description": "Unique identifier of the GitHub installation record", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGithubAppInstallationRequest" } } } }, "responses": { "200": { "description": "Installation updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubInstallation" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "409": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "GitHub App" ] } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/githubapp/repository": { "summary": "GitHub App Repository Operations", "description": "Manage GitHub repository to Xata branch mappings.", "get": { "operationId": "getGithubRepository", "summary": "Get GitHub repository for branch", "description": "Returns the GitHub repository mapping for the specified branch.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub repository mapping details", "content": { "application/json": { "schema": { "type": "object", "properties": { "mapping": { "description": "Repository mapping details, null if no mapping exists", "$ref": "#/components/schemas/GithubRepository", "nullable": true } }, "required": [ "mapping" ] } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "GitHub App" ] }, "post": { "operationId": "createGithubRepository", "summary": "Create GitHub repository mapping", "description": "Creates a new GitHub repository to Xata branch mapping.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGithubRepositoryRequest" } } } }, "responses": { "201": { "description": "Repository mapping created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubRepository" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "409": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "GitHub App" ] }, "put": { "operationId": "updateGithubRepository", "summary": "Update GitHub repository mapping", "description": "Updates an existing GitHub repository to Xata branch mapping.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGithubRepositoryRequest" } } } }, "responses": { "200": { "description": "Repository mapping updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubRepository" } } } }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "GitHub App" ] }, "delete": { "operationId": "deleteGithubRepository", "summary": "Delete GitHub repository mapping", "description": "Deletes the GitHub repository mapping for the specified branch.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } }, { "name": "projectID", "in": "path", "description": "Unique identifier of the project", "required": true, "schema": { "type": "string" } }, { "name": "branchID", "in": "path", "description": "Unique identifier of the branch", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Repository mapping deleted successfully" }, "400": { "$ref": "#/components/responses/GenericError" }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "404": { "$ref": "#/components/responses/GenericError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:write" ] } ], "tags": [ "GitHub App" ] } }, "/webhooks/orb": { "post": { "operationId": "orbWebhook", "summary": "Orb billing webhook", "description": "Endpoint used by Orb to deliver billing-related webhook events.\nThis endpoint is authenticated via Orb's HMAC signature headers,\nnot via the normal API authentication.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Orb webhook event payload", "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Webhook received and processed successfully" }, "400": { "description": "Invalid signature or malformed request" }, "500": { "description": "Internal error while handling the webhook" } }, "tags": [ "Webhooks" ], "x-excluded": true } }, "/webhooks/stripe": { "post": { "operationId": "stripeWebhook", "summary": "Stripe webhook", "description": "Endpoint used by Stripe to deliver webhook events.\nThis endpoint is authenticated via Stripe's signature headers,\nnot via the normal API authentication.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Stripe webhook event payload", "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Webhook received and processed successfully" }, "400": { "description": "Invalid signature or malformed request" }, "500": { "description": "Internal error while handling the webhook" } }, "tags": [ "Webhooks" ], "x-excluded": true } } }, "components": { "securitySchemes": { "oidc": { "type": "openIdConnect", "openIdConnectUrl": "https://auth.xata.io/realms/xata/.well-known/openid-configuration" }, "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key authentication using Bearer token format: Bearer " }, "xata": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://auth.xata.io/realms/xata/protocol/openid-connect/auth", "scopes": { "org:read": "Read organization information", "org:write": "Create and modify organizations", "keys:read": "Read API keys", "keys:write": "Create and manage API keys", "project:read": "Read project information", "project:write": "Create and modify projects", "branch:read": "Read branch information", "branch:write": "Create and modify branches", "metrics:read": "Read metrics data", "credentials:read": "Read credentials", "marketplace:write": "Register with cloud marketplaces" } } } } }, "parameters": { "InvitationIDParam": { "name": "invitationID", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for an invitation" }, "OrganizationIDParam": { "name": "organizationID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" }, "description": "Unique identifier for a specific organization" }, "UserIDParam": { "name": "userID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UserID" }, "description": "Unique identifier for a specific user account" } }, "schemas": { "User": { "description": "User information including email, full name, and profile image", "type": "object", "properties": { "email": { "description": "Email address associated with the user account", "type": "string", "format": "email" }, "name": { "description": "Name of the user", "type": "string" } }, "required": [ "name", "email" ] }, "UserID": { "description": "Unique identifier for a user account", "type": "string", "pattern": "[a-zA-Z0-9_-~:]+", "title": "UserID", "x-oapi-codegen-extra-tags": { "validate": "identifier" } }, "UserWithID": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "description": "Extended user object that includes the unique user identifier", "properties": { "id": { "$ref": "#/components/schemas/UserID" } }, "required": [ "id" ] } ] }, "CreateOrganizationRequest": { "description": "Request payload for creating a new organization", "type": "object", "properties": { "name": { "description": "Name for the new organization", "type": "string" } }, "required": [ "name" ] }, "Organization": { "description": "Organization details including ID and name", "type": "object", "properties": { "id": { "description": "Unique identifier for the organization", "$ref": "#/components/schemas/OrganizationID" }, "name": { "description": "Human-readable name of the organization", "type": "string" }, "status": { "description": "Current status of the organization", "$ref": "#/components/schemas/OrganizationStatus" }, "marketplace": { "description": "Marketplace provider for this organization (e.g. \"aws\"), if billed through a marketplace", "type": "string", "nullable": true } }, "required": [ "id", "name", "status" ] }, "OrganizationStatus": { "type": "object", "properties": { "status": { "description": "Indicates whether the organization is active, it's computed as `!disabled_by_admin AND billing_status == 'ok'`", "type": "string", "enum": [ "enabled", "disabled" ] }, "disabled_by_admin": { "description": "Indicates if the organization has been disabled by an admin", "type": "boolean" }, "admin_reason": { "description": "Reason for the current admin status", "type": "string" }, "billing_status": { "description": "Indicates the status of the organization from a billing perspective", "type": "string", "enum": [ "ok", "no_payment_method", "invoice_overdue", "unknown" ] }, "billing_reason": { "description": "Reason for the current billing status", "type": "string" }, "usage_tier": { "description": "Usage tier of the organization. t1 is the default for new organizations, t2 is assigned when a valid payment method is on file.", "type": "string", "enum": [ "t1", "t2" ] }, "last_updated": { "description": "Timestamp of the last update to the organization's status", "type": "string", "format": "date-time" }, "created_at": { "description": "Timestamp when the organization was created", "type": "string", "format": "date-time" } }, "required": [ "status", "disabled_by_admin", "billing_status", "usage_tier", "last_updated" ] }, "CreateOrganizationInvitationRequest": { "type": "object", "properties": { "email": { "description": "Email address of the user to invite", "type": "string", "format": "email" } }, "required": [ "email" ] }, "OrganizationInvitation": { "type": "object", "properties": { "id": { "description": "Unique identifier for the invitation", "type": "string" }, "organization_id": { "description": "ID of the organization the invitation is for", "$ref": "#/components/schemas/OrganizationID" }, "email": { "description": "Email address of the invited user", "type": "string", "format": "email" }, "first_name": { "description": "First name of the invited user", "type": "string", "nullable": true }, "last_name": { "description": "Last name of the invited user", "type": "string", "nullable": true }, "created_at": { "description": "Timestamp when the invitation was created", "type": "string", "format": "date-time" }, "expires_at": { "description": "Timestamp when the invitation expires", "type": "string", "format": "date-time" }, "status": { "description": "Current status of the invitation", "type": "string", "enum": [ "pending", "expired" ] }, "invite_link": { "description": "URL link to accept the invitation", "type": "string" } }, "required": [ "id", "organization_id", "email", "created_at", "expires_at", "status" ] }, "MarketplaceRegisterRequest": { "description": "Request to register with a cloud marketplace", "type": "object", "properties": { "marketplace": { "description": "The cloud marketplace provider", "type": "string", "enum": [ "aws" ] }, "company_name": { "description": "Company name for the marketplace registration", "type": "string" }, "aws": { "description": "AWS-specific marketplace details", "type": "object", "properties": { "customer_id": { "description": "AWS Marketplace customer ID", "type": "string" }, "product_id": { "description": "AWS Marketplace product ID", "type": "string" }, "account_id": { "description": "AWS account ID", "type": "string" } }, "required": [ "customer_id", "product_id", "account_id" ] } }, "required": [ "marketplace", "company_name", "aws" ] }, "CreateAPIKeyRequest": { "type": "object", "properties": { "name": { "type": "string" }, "expiry": { "description": "Expiration date for the API key, null for no expiry", "type": "string", "format": "date-time", "nullable": true }, "scopes": { "description": "Optional scopes assigned to the API key", "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "projects": { "description": "Limit access to these projects", "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "branches": { "description": "Limit access to these branches", "type": "array", "items": { "type": "string" }, "maxItems": 50 } }, "required": [ "name" ] }, "APIKeyPreview": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preview": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "projects": { "description": "Projects this API key has access to", "type": "array", "items": { "type": "string" } }, "branches": { "description": "Branches this API key has access to", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expiry": { "description": "Date when the API key expires (null if no expiry)", "type": "string", "format": "date-time", "nullable": true }, "last_used": { "description": "Timestamp of the last time the key was used (null if never)", "type": "string", "format": "date-time", "nullable": true }, "created_by": { "description": "ID of the user that created this API key", "type": "string", "nullable": true }, "created_by_key": { "description": "ID of the API key that created this API key", "type": "string", "nullable": true } }, "required": [ "id", "name", "preview", "created_at", "expiry", "last_used", "scopes", "projects", "branches" ] }, "FullAPIKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preview": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "projects": { "description": "Projects this API key has access to", "type": "array", "items": { "type": "string" } }, "branches": { "description": "Branches this API key has access to", "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expiry": { "description": "Date when the API key expires (null if no expiry)", "type": "string", "format": "date-time", "nullable": true }, "last_used": { "description": "Timestamp of the last time the key was used (null if never)", "type": "string", "format": "date-time", "nullable": true }, "token": { "description": "The actual API key token", "type": "string" }, "created_by": { "description": "ID of the user that created this API key", "type": "string", "nullable": true }, "created_by_key": { "description": "ID of the API key that created this API key", "type": "string", "nullable": true } }, "required": [ "id", "name", "preview", "created_at", "expiry", "last_used", "token", "scopes", "projects", "branches" ] }, "OrganizationID": { "title": "OrganizationID", "type": "string", "pattern": "[a-zA-Z0-9_-~:]+", "x-oapi-codegen-extra-tags": { "validate": "identifier" } }, "EndpointType": { "description": "Endpoint suffix that determines which PostgreSQL instance receives traffic.\nEncoded as the hostname suffix in the connection string (e.g. `my-branch-ro.example.com`).\n", "type": "string", "enum": [ "rw", "ro", "r" ] }, "SQLRequest": { "description": "SQL query request. Provide either `query` for a single query or `queries` for a batch.", "type": "object", "properties": { "query": { "description": "SQL query to execute (single query mode).", "type": "string" }, "params": { "description": "Positional parameters for the query (`$1`, `$2`, ...).", "type": "array", "items": {} }, "queries": { "description": "Array of queries for batch execution within a single transaction.", "type": "array", "items": { "$ref": "#/components/schemas/QueryItem" } }, "arrayMode": { "description": "Override array mode for this query (single query mode only).", "type": "boolean" } } }, "QueryItem": { "description": "A single query within a batch request.", "type": "object", "properties": { "query": { "description": "SQL query to execute.", "type": "string" }, "params": { "description": "Positional parameters for the query.", "type": "array", "items": {} }, "arrayMode": { "description": "Override array mode for this individual query.", "type": "boolean" } }, "required": [ "query" ] }, "QueryResult": { "description": "Result of a single SQL query execution.", "type": "object", "properties": { "fields": { "description": "Column metadata for the result set.", "type": "array", "items": { "$ref": "#/components/schemas/FieldDefinition" } }, "command": { "description": "PostgreSQL command tag (e.g. `SELECT`, `INSERT`, `UPDATE`, `DELETE`).", "type": "string" }, "rowCount": { "description": "Number of rows affected by the command.", "type": "integer", "nullable": true }, "rows": { "description": "Result rows. Each row is an object (column-name keys) or an array (when array mode is enabled).", "type": "array", "items": {}, "x-go-type": "any" }, "rowAsArray": { "description": "Whether rows are returned as arrays (`true`) or objects (`false`).", "type": "boolean" } }, "required": [ "fields", "command", "rowCount", "rows", "rowAsArray" ] }, "FieldDefinition": { "description": "PostgreSQL column metadata from the row description message.", "type": "object", "properties": { "name": { "description": "Column name.", "type": "string" }, "tableID": { "description": "OID of the source table (0 if not a table column).", "type": "integer", "format": "int32", "x-go-type": "uint32" }, "columnID": { "description": "Attribute number of the column within the table.", "type": "integer", "format": "int32", "x-go-type": "uint16" }, "dataTypeID": { "description": "OID of the column data type.", "type": "integer", "format": "int32", "x-go-type": "uint32" }, "dataTypeSize": { "description": "Data type size (negative for variable-length types).", "type": "integer", "format": "int32", "x-go-type": "int16" }, "dataTypeModifier": { "description": "Type-specific modifier (e.g. precision/scale for numeric types).", "type": "integer", "format": "int32" }, "format": { "description": "Data format (`text` or `binary`).", "type": "string" } }, "required": [ "name", "tableID", "columnID", "dataTypeID", "dataTypeSize", "dataTypeModifier", "format" ] }, "BatchResponse": { "description": "Response for a batch query execution.", "type": "object", "properties": { "results": { "description": "Results for each query in the batch, in order.", "type": "array", "items": { "$ref": "#/components/schemas/QueryResult" } } }, "required": [ "results" ] }, "ErrorResponse": { "description": "Error response with PostgreSQL error fields.", "type": "object", "properties": { "message": { "description": "Human-readable error message.", "type": "string" }, "code": { "description": "PostgreSQL error code (SQLSTATE) or application error code.", "type": "string" }, "severity": { "description": "PostgreSQL error severity (e.g. `ERROR`, `FATAL`).", "type": "string" }, "detail": { "description": "Optional detail message.", "type": "string" }, "hint": { "description": "Optional hint for resolving the error.", "type": "string" }, "position": { "description": "Character position in the query where the error occurred.", "type": "string" }, "internalPosition": { "description": "Position in an internally-generated query.", "type": "string" }, "internalQuery": { "description": "Text of the internally-generated query.", "type": "string" }, "where": { "description": "Context in which the error occurred.", "type": "string" }, "schema": { "description": "Schema name related to the error.", "type": "string" }, "table": { "description": "Table name related to the error.", "type": "string" }, "column": { "description": "Column name related to the error.", "type": "string" }, "dataType": { "description": "Data type name related to the error.", "type": "string" }, "constraint": { "description": "Constraint name related to the error.", "type": "string" }, "file": { "description": "Source file where the error was reported (server-side).", "type": "string" }, "line": { "description": "Source line where the error was reported (server-side).", "type": "string" }, "routine": { "description": "Source routine where the error was reported (server-side).", "type": "string" } }, "required": [ "message" ] }, "GithubInstallation": { "description": "A GitHub App installation associated with an organization", "type": "object", "properties": { "id": { "description": "Unique identifier of the installation record", "type": "string" }, "installationId": { "description": "GitHub App installation ID", "type": "integer", "format": "int64" }, "organization": { "description": "Organization ID this installation belongs to", "type": "string" }, "createdAt": { "description": "Timestamp when the installation was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the installation was last updated", "type": "string", "format": "date-time" } }, "required": [ "id", "installationId", "organization", "createdAt", "updatedAt" ] }, "GithubRepository": { "description": "A mapping between a GitHub repository and a Xata project", "type": "object", "properties": { "id": { "description": "Unique identifier of the mapping record", "type": "string" }, "githubRepositoryID": { "description": "GitHub repository ID", "type": "integer", "format": "int64" }, "project": { "description": "Project ID this mapping is associated with", "type": "string" }, "rootBranchId": { "description": "ID of the root Xata branch mapped to this repository", "type": "string" }, "createdAt": { "description": "Timestamp when the mapping was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the mapping was last updated", "type": "string", "format": "date-time" } }, "required": [ "id", "githubRepositoryID", "project", "rootBranchId", "createdAt", "updatedAt" ] }, "CreateGithubAppInstallationRequest": { "type": "object", "properties": { "installationId": { "description": "GitHub App installation ID", "type": "integer", "format": "int64" } }, "required": [ "installationId" ] }, "UpdateGithubAppInstallationRequest": { "type": "object", "properties": { "installationId": { "description": "GitHub App installation ID", "type": "integer", "format": "int64" } }, "required": [ "installationId" ] }, "CreateGithubRepositoryRequest": { "type": "object", "properties": { "githubRepositoryID": { "description": "GitHub repository ID", "type": "integer", "format": "int64" } }, "required": [ "githubRepositoryID" ] }, "UpdateGithubRepositoryRequest": { "type": "object", "properties": { "githubRepositoryID": { "description": "GitHub repository ID", "type": "integer", "format": "int64" } }, "required": [ "githubRepositoryID" ] }, "Extension": { "description": "Details of a postgres extension", "type": "object", "properties": { "name": { "description": "Extension name", "type": "string" }, "version": { "description": "Extension version", "type": "string" }, "description": { "description": "Extension description", "type": "string" }, "docs": { "description": "Documentation URL", "type": "string" }, "preloadRequired": { "description": "is preload required for the extension or not", "type": "boolean" }, "type": { "description": "type of installation", "type": "string", "enum": [ "extension", "plugin", "module" ] } }, "required": [ "name", "description", "version", "docs", "preloadRequired", "type" ], "x-excluded": true, "x-internal": true }, "Image": { "description": "Details of a postgres image", "type": "object", "properties": { "name": { "description": "Image name", "type": "string" }, "majorVersion": { "description": "major postgres version", "type": "string" }, "fullVersion": { "description": "full postgres version", "type": "string" }, "region": { "description": "region where this instance type is available", "type": "array", "items": { "type": "string", "minItems": 1 } } }, "required": [ "name", "majorVersion", "fullVersion" ] }, "Project": { "description": "Details of a project including its ID, name, and creation/update timestamps", "type": "object", "properties": { "id": { "description": "Unique identifier for the project", "type": "string" }, "name": { "description": "Human-readable name of the project", "type": "string" }, "createdAt": { "description": "Timestamp when the project was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the project was last updated", "type": "string", "format": "date-time" }, "configuration": { "$ref": "#/components/schemas/ProjectConfiguration" } }, "required": [ "id", "name", "createdAt", "updatedAt", "configuration" ] }, "ProjectConfiguration": { "description": "Configuration details for a project, including its scale to zero settings", "type": "object", "properties": { "scaleToZero": { "$ref": "#/components/schemas/ProjectScaleToZeroConfiguration" }, "ipFiltering": { "$ref": "#/components/schemas/IPFilteringConfiguration" } }, "required": [ "scaleToZero" ] }, "UpdateProjectConfiguration": { "description": "Partial configuration update for a project", "type": "object", "properties": { "scaleToZero": { "$ref": "#/components/schemas/ProjectScaleToZeroConfiguration" }, "ipFiltering": { "$ref": "#/components/schemas/IPFilteringConfiguration" } } }, "ProjectScaleToZeroConfiguration": { "description": "Whether the project branches are configured to scale down to zero when not in use", "type": "object", "properties": { "baseBranches": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" }, "childBranches": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" } }, "required": [ "baseBranches", "childBranches" ] }, "ScaleToZeroConfiguration": { "description": "Configuration for scaling branches to zero when not in use", "type": "object", "properties": { "enabled": { "description": "Whether scale to zero is enabled", "type": "boolean" }, "inactivityPeriodMinutes": { "description": "Duration in minutes after which branches will be hibernated if not accessed", "type": "integer", "default": 30 } }, "required": [ "enabled", "inactivityPeriodMinutes" ] }, "IPFilteringConfiguration": { "description": "Configuration for IP filtering on project branches", "type": "object", "properties": { "enabled": { "description": "Whether IP filtering is enabled", "type": "boolean" }, "cidr": { "type": "array", "items": { "$ref": "#/components/schemas/CidrEntry" } } }, "required": [ "enabled", "cidr" ] }, "CidrEntry": { "type": "object", "properties": { "cidr": { "description": "CIDR block (e.g., \"192.168.0.0/24\")", "type": "string" }, "description": { "description": "Optional label for the CIDR entry", "type": "string" } }, "required": [ "cidr" ] }, "BranchFromParent": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inherit" ] }, "parentID": { "description": "If present, the branch will inherit the parent branch configuration and data", "type": "string" } }, "required": [ "mode", "parentID" ] }, "BranchFromConfiguration": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "custom" ] }, "configuration": { "$ref": "#/components/schemas/ClusterConfiguration" } }, "required": [ "mode", "configuration" ] }, "BranchShortMetadata": { "description": "Basic metadata about a branch, used in response to create/update operations", "type": "object", "properties": { "id": { "description": "Unique identifier for the branch", "type": "string" }, "name": { "description": "Human-readable name of the branch", "type": "string" }, "description": { "description": "Optional description of the branch purpose or contents", "type": "string" }, "createdAt": { "description": "Timestamp when the branch was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the branch was last updated", "type": "string", "format": "date-time" }, "parentID": { "description": "Identifier of the parent branch if this is a derived branch, null otherwise", "type": "string", "nullable": true }, "connectionString": { "description": "Database connection string for accessing this branch", "type": "string", "nullable": true }, "region": { "description": "Geographic region where the branch is deployed", "type": "string" }, "publicAccess": { "description": "Whether the branch allows public access without authentication", "type": "boolean" } }, "required": [ "id", "name", "createdAt", "updatedAt", "region", "publicAccess" ] }, "BranchListMetadata": { "description": "Metadata about a branch used when listing branches in a project", "type": "object", "properties": { "id": { "description": "Unique identifier for the branch", "type": "string" }, "name": { "description": "Human-readable name of the branch", "type": "string" }, "description": { "description": "Optional description of the branch purpose or contents", "type": "string" }, "createdAt": { "description": "Timestamp when the branch was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the branch was last updated", "type": "string", "format": "date-time" }, "parentID": { "description": "Identifier of the parent branch if this is a derived branch, null otherwise", "type": "string", "nullable": true }, "region": { "description": "Geographic region where the branch is deployed", "type": "string" }, "publicAccess": { "description": "Whether the branch allows public access without authentication", "type": "boolean" }, "backupsEnabled": { "description": "Whether the branch is in a region that supports backups", "type": "boolean" } }, "required": [ "id", "name", "createdAt", "updatedAt", "region", "publicAccess", "backupsEnabled" ] }, "BranchMetadata": { "description": "Detailed metadata about a branch, including its status and configuration", "type": "object", "properties": { "id": { "description": "Unique identifier for the branch", "type": "string" }, "name": { "description": "Human-readable name of the branch", "type": "string" }, "description": { "description": "Optional description of the branch purpose or contents", "type": "string" }, "createdAt": { "description": "Timestamp when the branch was created", "type": "string", "format": "date-time" }, "updatedAt": { "description": "Timestamp when the branch was last updated", "type": "string", "format": "date-time" }, "parentID": { "description": "Identifier of the parent branch if this is a derived branch, null otherwise", "type": "string", "nullable": true }, "region": { "description": "Geographic region where the branch is deployed", "type": "string" }, "status": { "$ref": "#/components/schemas/BranchStatus" }, "connectionString": { "description": "Database connection string for accessing this branch", "type": "string", "nullable": true }, "publicAccess": { "description": "Whether the branch allows public access without authentication", "type": "boolean" }, "backupsEnabled": { "description": "Whether the branch is in a region that supports backups", "type": "boolean" }, "scaleToZero": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" }, "configuration": { "$ref": "#/components/schemas/ClusterConfiguration" }, "backupConfiguration": { "$ref": "#/components/schemas/BackupConfiguration" } }, "required": [ "id", "name", "createdAt", "updatedAt", "region", "status", "connectionString", "configuration", "publicAccess", "backupsEnabled", "scaleToZero" ] }, "BackupMetadata": { "description": "metadata about a continuous backup", "type": "object", "properties": { "id": { "description": "unique identifier for the backup", "type": "string" }, "branchID": { "description": "the branchID the branch associated with the backup", "type": "string" }, "earliestRestore": { "description": "the earlies point in time available for restoring the branch", "type": "string", "format": "date-time" }, "latestRestore": { "description": "the latest point in time available for restoring the branch", "type": "string", "format": "date-time" }, "description": { "description": "description of the backup", "type": "string" } }, "required": [ "id", "branchID", "description" ] }, "BranchCredentials": { "description": "Credentials for accessing a branch, username and password", "type": "object", "properties": { "username": { "description": "Username for accessing the branch database", "type": "string" }, "password": { "description": "Password for accessing the branch database", "type": "string" } }, "required": [ "username", "password" ], "x-internal": true }, "ClusterLifecycle": { "description": "Information about the current lifecycle state of a database cluster", "type": "object", "properties": { "state": { "description": "Current operational state of the cluster (ready, creating, updating, etc.)", "enum": [ "ready", "creating", "updating", "upgrading", "unknown" ], "title": "Current state in the cluster lifecycle" }, "reason": { "description": "Reason for the current lifecycle state, especially useful for non-ready states", "type": "string" }, "phase": { "description": "Current phase within the lifecycle process", "type": "string" } }, "deprecated": true, "required": [ "state", "phase" ] }, "BranchStatus": { "description": "Detailed status information about a branch and its underlying database cluster", "type": "object", "properties": { "status": { "description": "Status indicator for the branch according to CNPG", "type": "string", "title": "Current status of the cluster" }, "statusType": { "description": "Type of status of the branch", "enum": [ "STATUS_TYPE_UNSPECIFIED", "STATUS_TYPE_HEALTHY", "STATUS_TYPE_TRANSIENT", "STATUS_TYPE_FAULT", "STATUS_TYPE_HIBERNATED" ] }, "message": { "description": "Human-readable message explaining the current status", "type": "string", "deprecated": true, "title": "Summary of the cluster status" }, "lifecycle": { "$ref": "#/components/schemas/ClusterLifecycle" }, "instanceCount": { "description": "Total number of database instances in the cluster", "type": "integer", "maximum": 5, "minimum": 1, "title": "Number of instances in the cluster" }, "instanceReadyCount": { "description": "Number of database instances that are ready and operational", "type": "integer", "maximum": 5, "minimum": 0, "title": "Number of instances ready in the cluster" }, "instances": { "description": "Details about each individual database instance in the cluster", "type": "array", "items": { "$ref": "#/components/schemas/InstanceStatus" }, "title": "List of instances in the cluster" } }, "required": [ "status", "statusType", "instanceCount", "instanceReadyCount", "instances" ] }, "InstanceStatus": { "description": "Status information about an individual database instance within a cluster", "type": "object", "properties": { "id": { "description": "Unique identifier for the database instance", "type": "string", "title": "Instance unique ID" }, "status": { "description": "Current operational status of the instance", "type": "string", "title": "Current status of the instance" }, "primary": { "description": "Indicates if this instance is currently the primary (write) instance", "type": "boolean", "title": "Whether the instance is the primary" }, "targetPrimary": { "description": "Indicates if this instance is the target primary during a failover operation", "type": "boolean", "title": "Whether the cluster is switching and this is the target primary" } }, "required": [ "id", "status", "primary", "targetPrimary" ], "title": "Status of an instance in the cluster" }, "BranchCreationDetails": { "description": "Details required when creating a new branch", "type": "object", "properties": { "name": { "description": "Human-readable name for the new branch", "type": "string" }, "description": { "description": "Optional description for the branch purpose or contents (max 50 characters)", "type": "string", "maxLength": 50, "pattern": "^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$" }, "scaleToZero": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" }, "backupConfiguration": { "$ref": "#/components/schemas/BackupConfiguration" }, "mode": { "description": "The mode used to discriminate between types of branches.", "type": "string", "enum": [ "inherit", "custom" ] } }, "discriminator": { "propertyName": "mode", "mapping": { "inherit": "#/components/schemas/BranchFromParent", "custom": "#/components/schemas/BranchFromConfiguration" } }, "oneOf": [ { "$ref": "#/components/schemas/BranchFromParent" }, { "$ref": "#/components/schemas/BranchFromConfiguration" } ], "required": [ "name", "mode" ] }, "BranchUpdateDetails": { "description": "Details that can be updated for an existing branch", "type": "object", "properties": { "name": { "description": "New name for the branch", "type": "string" }, "description": { "description": "New description for the branch (max 50 characters)", "type": "string", "maximum": 50, "pattern": "^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$" }, "replicas": { "description": "Number of database replicas to scale to", "type": "integer", "format": "int32", "maximum": 4, "minimum": 0 }, "storage": { "description": "Branch storage in GiB (gigabytes)", "type": "integer", "format": "int32", "maximum": 250 }, "instanceType": { "description": "New instance type for the branch", "type": "string" }, "backupConfiguration": { "$ref": "#/components/schemas/BackupConfiguration" }, "hibernate": { "description": "Enabled when the branch should be hibernated, disabled if it needs to be reactivated.", "type": "boolean" }, "scaleToZero": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" }, "postgresConfigurationParameters": { "description": "Arbitrary PostgreSQL configuration parameters for the cluster", "type": "object", "additionalProperties": { "type": "string" } }, "preloadLibraries": { "description": "List of PostgreSQL extensions and libraries to preload", "type": "array", "items": { "type": "string" } } } }, "ClusterConfiguration": { "description": "Configuration details for a database cluster backing a branch", "type": "object", "properties": { "region": { "description": "Geographic region where the cluster will be deployed", "type": "string" }, "storage": { "description": "Branch storage in GiB (gigabytes)", "type": "integer", "format": "int32", "maximum": 250 }, "instanceType": { "description": "The instance type according to the xata instance types available", "type": "string" }, "image": { "description": "PostgreSQL image to use for the database instances", "type": "string" }, "replicas": { "description": "Number of replicas in the branch. Every child branch is created with no replicas. This can be updated.", "type": "integer", "format": "int32", "maximum": 4, "minimum": 0 }, "postgresConfigurationParameters": { "description": "Arbitrary PostgreSQL configuration parameters for the cluster", "type": "object", "additionalProperties": { "type": "string" } }, "preloadLibraries": { "description": "List of PostgreSQL extensions and libraries to preload", "type": "array", "items": { "type": "string" } } }, "required": [ "image", "region", "instanceType", "replicas" ] }, "BackupConfiguration": { "description": "Details about the branch continuous backup configuration", "type": "object", "properties": { "retentionPeriod": { "description": "how long are we keeping the backups around for", "type": "integer", "format": "int32", "default": 2, "maximum": 35, "minimum": 2 }, "backupTime": { "description": "time of day/week when we are taking a full backup", "type": "string", "pattern": "^(\\*|[0-6]):(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9])$" } }, "x-excluded": true, "x-internal": true }, "ProjectLimits": { "description": "Resource limits and constraints for projects within an organization", "type": "object", "properties": { "regions": { "description": "List of region identifiers where branches can be deployed", "type": "array", "items": { "type": "string" }, "title": "Regions the branch can be deployed in" }, "maxInstances": { "description": "Maximum number of database instances allowed per branch", "type": "integer", "minimum": 1, "title": "Maximum number of instances in a branch" }, "minInstances": { "description": "Minimum number of database instances required per branch", "type": "integer", "minimum": 1, "title": "Minimum number of instances in a branch" }, "images": { "description": "List of PostgreSQL image identifiers that can be used for branches", "type": "array", "items": { "type": "string" }, "title": "Allowed PostgreSQL images", "uniqueItems": true }, "maxDescriptionLength": { "description": "Maximum character length allowed for project descriptions", "type": "integer", "minimum": 25, "title": "Maximum length of a project description" }, "maxBranches": { "description": "Maximum number of branches allowed per project", "type": "integer", "title": "Maximum number of branches per project" } }, "required": [ "regions", "maxInstances", "minInstances", "maxDescriptionLength", "images", "maxBranches" ] }, "BranchMetricsRequest": { "type": "object", "properties": { "start": { "description": "Start time", "type": "string", "format": "date-time" }, "end": { "description": "End time", "type": "string", "format": "date-time" }, "metric": { "description": "Metric name to query", "type": "string", "enum": [ "cpu", "memory", "disk", "connections_active", "connections_idle", "network_ingress", "network_egress", "iops_read", "iops_write", "latency_read", "latency_write", "throughput_read", "throughput_write", "wal_sync_time", "replication_lag_time" ] }, "instances": { "description": "List of instance IDs to query", "type": "array", "items": { "type": "string" } }, "aggregations": { "description": "List of aggregations to get, this is how the data-points within the interval are aggregated. Each one will generate a separate time-series in the response.", "type": "array", "items": { "type": "string", "enum": [ "avg", "max", "min" ] } } }, "required": [ "start", "end", "metric", "instances", "aggregations" ] }, "BranchMetrics": { "description": "A collection of metrics (cpu, memory, disk,...) for each of the instances of a branch", "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "metric": { "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } }, "unit": { "description": "The unit of the metric (percentage, bytes, ms, etc.)", "type": "string" } }, "required": [ "start", "end", "metric", "series", "unit" ] }, "MetricSeries": { "description": "The metric series", "type": "object", "properties": { "instanceID": { "description": "ID of the instance", "type": "string" }, "aggregation": { "description": "The aggregation used to generate this time-series", "type": "string", "enum": [ "avg", "max", "min" ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "value": { "type": "number" } }, "required": [ "timestamp", "value" ] } } }, "required": [ "instanceID", "aggregation", "values" ] }, "PostgresConfigDetails": { "description": "Detailed information about PostgreSQL configuration parameters for a branch", "type": "object", "properties": { "parameters": { "description": "Array of PostgreSQL configuration parameters with detailed information", "items": { "$ref": "#/components/schemas/PostgresConfigParameter" }, "type": "array" } }, "required": [ "parameters" ] }, "PostgresConfigParameter": { "description": "Detailed information about a single PostgreSQL configuration parameter", "type": "object", "properties": { "name": { "description": "The name of the PostgreSQL parameter", "type": "string" }, "type": { "description": "The data type of the parameter", "type": "string", "enum": [ "string", "int", "float", "bytes", "enum", "duration", "boolean" ] }, "description": { "description": "Human-readable description of what the parameter controls", "type": "string" }, "section": { "description": "The section/category this parameter belongs to", "type": "string" }, "acceptableRange": { "description": "Information about the acceptable range of values for this parameter", "type": "object", "properties": { "minValue": { "description": "Minimum allowed value (if applicable)", "type": "string" }, "maxValue": { "description": "Maximum allowed value (if applicable)", "type": "string" }, "enumValues": { "description": "List of allowed enum values (if applicable)", "type": "array", "items": { "type": "string" } } } }, "defaultValue": { "description": "The default value for this parameter", "type": "string" }, "defaultValueSource": { "description": "The source of the default value", "type": "string", "enum": [ "postgres", "instance_type" ] }, "currentValue": { "description": "The current value of this parameter in the branch", "type": "string" }, "documentationLink": { "description": "Link to PostgreSQL documentation for this parameter", "type": "string" }, "recommendation": { "description": "Optional recommendation for this parameter (currently empty)", "type": "string" }, "restartRequired": { "description": "Whether a database restart is required for this parameter change to take effect", "type": "boolean" } }, "required": [ "name", "type", "description", "defaultValue", "defaultValueSource", "currentValue", "documentationLink", "recommendation", "section" ] }, "RestoreDetails": { "description": "Metadata about a backup, used in request to create a restore. If configuration is not provided, the branch will inherit the source branch configuration.", "type": "object", "properties": { "name": { "description": "Human-readable name of the branch", "type": "string" }, "description": { "description": "Optional description of the branch purpose or contents", "type": "string" }, "scaleToZero": { "$ref": "#/components/schemas/ScaleToZeroConfiguration" }, "backupConfiguration": { "$ref": "#/components/schemas/BackupConfiguration" }, "configuration": { "$ref": "#/components/schemas/ClusterConfiguration" } }, "required": [ "name" ], "x-excluded": true, "x-internal": true } }, "responses": { "BadRequestError": { "description": "Error returned when the request is malformed or contains invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the issue", "type": "string" } }, "required": [ "message" ] } } } }, "AuthError": { "description": "Error returned when authentication or authorization fails", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the issue", "type": "string" } }, "example": { "message": "invalid API key" }, "required": [ "message" ] } } } }, "SimpleError": { "description": "Generic error response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the issue", "type": "string" } }, "required": [ "message" ] } } } }, "GenericError": { "description": "Generic error response for most error conditions", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the issue", "type": "string" } }, "required": [ "message" ] } } } }, "AuthorizationError": { "description": "Error response when authentication or authorization fails", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the authentication or authorization issue", "type": "string" } }, "required": [ "message" ] } } } }, "PreconditionFailedError": { "description": "Error response when a precondition for the request is not met", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Error identifier for tracking and debugging", "type": "string" }, "message": { "description": "Human-readable error message explaining the precondition failure", "type": "string" } }, "required": [ "message" ] } } } } } }, "x-tagGroups": [ { "name": "Authentication API", "tags": [ "Organizations", "Users", "API Keys", "Marketplace", "Webhooks" ] }, { "name": "Gateway API", "tags": [ "Gateway" ] }, { "name": "Projects API", "tags": [ "Projects", "Branches", "GitHub App", "Metrics" ] } ] }