{ "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 API" } ], "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": "Billing", "description": "Internal organization billing operations", "x-displayName": "Billing" }, { "name": "Gateway", "description": "PostgreSQL connectivity via HTTP SQL, WebSocket wire protocol proxy, and native wire protocol.", "x-displayName": "Gateway" }, { "name": "MCP", "description": "Model Context Protocol endpoint.", "x-displayName": "MCP" }, { "name": "Projects Webhooks", "x-displayName": "Projects Webhooks" }, { "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", "description": "Operations for retrieving observability metrics for a branch", "x-displayName": "Metrics" }, { "name": "Logs", "description": "Operations for retrieving log entries for a branch", "x-displayName": "Logs" }, { "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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" }, "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" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/api-keys": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "listOrganizationAPIKeys", "summary": "List API Keys for an organization", "description": "Retrieve a list of API keys for a specific organization.", "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" ], "x-operation-kind": "read" }, "post": { "operationId": "createOrganizationAPIKey", "summary": "Create an Organization API Key", "description": "Create a new API key for an organization.", "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" ], "x-operation-kind": "write" }, "delete": { "operationId": "deleteOrganizationAPIKeys", "summary": "Bulk delete API Keys for an organization", "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", "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" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/members": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "listOrganizationMembers", "summary": "List members of an organization", "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" ], "x-operation-kind": "read" } }, "/organizations/{organizationID}/members/{userID}": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/UserIDParam" } ], "delete": { "operationId": "removeOrganizationMember", "summary": "Remove a member from an organization", "responses": { "204": { "description": "Member removed" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/invitations": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "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": [ { "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" ], "x-operation-kind": "read" }, "post": { "operationId": "createOrganizationInvitation", "summary": "Send an invitation to join an organization", "description": "Send an invitation email to a user to join an organization.", "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" ], "x-operation-kind": "write" } }, "/organizations/{organizationID}/invitations/{invitationID}": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/InvitationIDParam" } ], "get": { "operationId": "getOrganizationInvitation", "summary": "Get details of a specific invitation", "description": "Retrieve detailed information about a specific invitation by its ID.", "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" ], "x-operation-kind": "read" }, "delete": { "operationId": "deleteOrganizationInvitation", "summary": "Delete an invitation", "description": "Permanently delete an invitation record.", "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" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/invitations/{invitationID}/resend": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" }, { "$ref": "#/components/parameters/InvitationIDParam" } ], "post": { "operationId": "resendOrganizationInvitation", "summary": "Resend an invitation", "description": "Resend a pending invitation with a fresh expiration time.", "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" ], "x-operation-kind": "write" } }, "/organizations/{organizationID}/deletion-request": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "post": { "operationId": "requestOrganizationDeletion", "summary": "Request organization deletion", "description": "Flags the organization for deletion. The request is rejected if the organization still has active projects.\nThe subscription is cancelled immediately and any outstanding invoices are collected automatically after a grace period that prevents missing delayed usage reports.\nDeletion completes asynchronously once all invoices are issued and settled.\n", "responses": { "202": { "description": "Deletion requested — the organization will be removed once all outstanding invoices are settled" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "409": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Organizations" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/membership-limits": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "getOrganizationMembershipLimits", "summary": "Get organization membership limits", "description": "Retrieves the membership limits for the specified organization (maximum members and invitations).", "responses": { "200": { "description": "Membership limits for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMembershipLimits" } } } }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Organizations" ], "x-operation-kind": "read" } }, "/organizations/{organizationID}/billing/checkout-session": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "post": { "operationId": "createBillingCheckoutSession", "summary": "Create a billing checkout session", "description": "Creates a Stripe checkout session used to activate card billing for an organization.", "responses": { "200": { "description": "Billing checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Billing" ], "x-excluded": true, "x-operation-kind": "write" } }, "/organizations/{organizationID}/billing/payment-method-session": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "post": { "operationId": "createBillingPaymentMethodSession", "summary": "Create a billing payment method session", "description": "Creates a Stripe setup-mode checkout session used to add or update an organization payment method.", "responses": { "200": { "description": "Billing payment method session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingPaymentMethodSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:write" ] } ], "tags": [ "Billing" ], "x-excluded": true, "x-operation-kind": "write" } }, "/organizations/{organizationID}/billing/customer": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "getBillingCustomer", "summary": "Get billing customer details", "description": "Retrieves billing customer details for the specified organization.", "responses": { "200": { "description": "Billing customer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCustomerResponse" } } } }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Billing" ], "x-excluded": true, "x-operation-kind": "read" }, "patch": { "operationId": "updateBillingCustomer", "summary": "Update billing customer details", "description": "Updates billing customer details for the specified organization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBillingCustomerRequest" } } } }, "responses": { "200": { "description": "Billing customer updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCustomerResponse" } } } }, "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": [ "Billing" ], "x-excluded": true, "x-operation-kind": "write" } }, "/organizations/{organizationID}/billing/invoices": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "getBillingInvoices", "summary": "List billing invoices", "description": "Retrieves billing invoices for the specified organization.", "parameters": [ { "name": "cursor", "in": "query", "description": "Pagination cursor from a previous response", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of invoices to fetch", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Billing invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInvoicesResponse" } } } }, "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": [ "Billing" ], "x-excluded": true, "x-operation-kind": "read" } }, "/organizations/{organizationID}/billing/invoices/upcoming": { "parameters": [ { "$ref": "#/components/parameters/OrganizationIDParam" } ], "get": { "operationId": "getBillingUpcomingInvoice", "summary": "Get upcoming billing invoice", "description": "Retrieves the upcoming billing invoice for the specified organization's active subscription. Organizations are expected to have at most one active subscription.", "responses": { "200": { "description": "Upcoming billing invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUpcomingInvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/AuthError" }, "403": { "$ref": "#/components/responses/AuthError" }, "404": { "$ref": "#/components/responses/SimpleError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Billing" ], "x-excluded": true, "x-operation-kind": "read" } }, "/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, "x-operation-kind": "write" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" }, "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" ], "x-operation-kind": "destructive" } }, "/sql": { "servers": [ { "url": "https://{branch}.{region}.xata.tech", "description": "Xata Gateway. The hostname encodes the target branch and region.", "variables": { "branch": { "default": "my-branch", "description": "Branch ID. Use the branch `id`, NOT its human-readable name" }, "region": { "default": "us-east-1", "description": "Branch region. The `us-east-1` default is a placeholder and may not be the region of your database." } } } ], "post": { "operationId": "query", "summary": "Execute SQL query", "description": "Execute a single SQL query or a batch of queries against a PostgreSQL branch.\n\n**Authentication:** send the branch's PostgreSQL connection string in the\n`Connection-String` header. The control-plane API key (Bearer token) is\n**not** accepted on the gateway host.\n\n**Routing:** the target branch, region, and endpoint type are taken from the\nhostname embedded in the connection string, which must match the request host.\nSee the `Connection-String` security scheme for the host format.\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": "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" }, "examples": { "single": { "summary": "Single parameterized query", "value": { "query": "SELECT id, name FROM users WHERE id = $1", "params": [ 42 ] } }, "batch": { "summary": "Batch of queries in one transaction", "value": { "queries": [ { "query": "INSERT INTO logs (message) VALUES ($1)", "params": [ "hello" ] }, { "query": "SELECT count(*) FROM logs" } ] } } } } } }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/QueryResult" }, { "$ref": "#/components/schemas/BatchResponse" } ] }, "examples": { "single": { "summary": "Result of the single query above", "value": { "fields": [ { "name": "id", "tableID": 0, "columnID": 0, "dataTypeID": 23, "dataTypeSize": 4, "dataTypeModifier": -1, "format": "text" }, { "name": "name", "tableID": 0, "columnID": 0, "dataTypeID": 25, "dataTypeSize": -1, "dataTypeModifier": -1, "format": "text" } ], "command": "SELECT", "rowCount": 1, "rows": [ { "id": 42, "name": "Ada" } ], "rowAsArray": false } }, "batch": { "summary": "Result of the batch above, one entry per query", "value": { "results": [ { "command": "INSERT", "fields": [], "rowCount": 1, "rows": [], "rowAsArray": false }, { "command": "SELECT", "fields": [ { "name": "count", "tableID": 0, "columnID": 0, "dataTypeID": 20, "dataTypeSize": 8, "dataTypeModifier": -1, "format": "text" } ], "rowCount": 1, "rows": [ { "count": "1" } ], "rowAsArray": false } ] } } } } } }, "400": { "description": "Invalid request, SQL error, or query execution timeout", "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" } } } }, "504": { "description": "Timed out connecting to the database", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "507": { "description": "Response too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "branchConnectionString": [] } ], "tags": [ "Gateway" ], "x-operation-kind": "destructive" } }, "/v2": { "servers": [ { "url": "https://{branch}.{region}.xata.tech", "description": "Xata Gateway. The hostname encodes the target branch and region.", "variables": { "branch": { "default": "my-branch", "description": "Branch ID. Use the branch `id`, NOT its human-readable name" }, "region": { "default": "us-east-1", "description": "Branch region. The `us-east-1` default is a placeholder and may not be the region of your database." } } } ], "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\n**Authentication:** the same branch connection string credential as the\nHTTP SQL endpoint is used, but it is supplied via the PostgreSQL startup\nmessage inside the wire protocol rather than an HTTP header. The\ncontrol-plane API key (Bearer token) is not accepted.\n", "responses": { "101": { "description": "Switching Protocols — WebSocket connection established" }, "400": { "description": "Bad request — unable to upgrade connection" } }, "tags": [ "Gateway" ], "x-operation-kind": "read" } }, "/mcp": { "post": { "operationId": "sendMcpRequest", "summary": "Send an MCP message", "description": "Handle a single JSON-RPC 2.0 message from an MCP client, per the MCP\n[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).\n\nThe server is stateless: every request is self-contained and carries the caller's\ncredential, so there is no session to establish or resume. `GET` and `DELETE` on this\npath return `405 Method Not Allowed`.\n\n**Requests** (messages with an `id`) are answered with the JSON-RPC response, either as\n`application/json` or as a `text/event-stream` carrying the response and any notifications\nemitted while it runs. Requests must accept both. **Notifications and responses**\n(messages without an `id`) are answered with `202 Accepted` and an empty body.\n", "parameters": [ { "name": "Accept", "in": "header", "description": "Must list both `application/json` and `text/event-stream`.", "required": true, "schema": { "type": "string", "default": "application/json, text/event-stream" } }, { "name": "MCP-Protocol-Version", "in": "header", "description": "Protocol revision negotiated during `initialize`, echoed on every subsequent request.\nOmitted on the `initialize` request itself.\n", "required": false, "schema": { "type": "string", "example": "2025-06-18" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONRPCMessage" }, "examples": { "initialize": { "summary": "Start a session and learn the server's capabilities", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0.0" } } } }, "toolsList": { "summary": "List the available tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } }, "toolsCall": { "summary": "Call a tool", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "user_info", "arguments": {} } } } } } } }, "responses": { "200": { "description": "JSON-RPC response to the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONRPCResponse" }, "examples": { "toolsCall": { "summary": "Result of the tool call above", "value": { "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "text": "{\"email\":\"user@example.com\"}", "type": "text" } ], "isError": false } } } } }, "text/event-stream": { "schema": { "description": "Server-sent events, each `data` field holding one JSON-RPC message.", "type": "string" }, "example": "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":3,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"{\\\"email\\\":\\\"user@example.com\\\"}\"}],\"isError\":false}}\n" } } }, "202": { "description": "Notification or response accepted; no body is returned" }, "400": { "description": "Malformed message, unsupported `MCP-Protocol-Version`, or an `Accept` header missing one of the required media types" }, "401": { "description": "Missing or invalid credentials", "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing at the protected resource metadata, per RFC 9728.", "schema": { "type": "string", "example": "Bearer resource_metadata=\"https://api.xata.tech/.well-known/oauth-protected-resource/mcp\"" } } } }, "413": { "description": "Request body larger than 4 MiB" }, "415": { "description": "`Content-Type` is not `application/json`" }, "500": { "description": "Internal server error" } }, "security": [ { "apiKey": [] }, { "oidc": [] } ], "tags": [ "MCP" ], "x-operation-kind": "write" } }, "/webhooks/github": { "post": { "operationId": "githubWebhook", "summary": "GitHub App webhook", "description": "Endpoint used by GitHub to deliver App webhook events.\nThis endpoint is authenticated via GitHub's HMAC-SHA256 signature header,\nnot via the normal API authentication.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "GitHub 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": [ "Projects Webhooks" ], "x-excluded": true, "x-operation-kind": "write" } }, "/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" }, "provider": { "description": "Cloud provider the region runs on", "type": "string", "enum": [ "aws", "gcp", "custom" ] }, "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", "provider", "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" ], "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" } }, "/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, "x-operation-kind": "read" } }, "/organizations/{organizationID}/limits": { "summary": "Organization Limits", "description": "Endpoint for retrieving the effective resource limits for an organization. Call this before creating a project or branch to know what constraints apply.", "get": { "operationId": "getOrganizationLimits", "summary": "Get organization resource limits", "description": "Retrieves the effective org-level limits, including project creation limits and branch configuration defaults. Project-specific overrides are not applied here.", "parameters": [ { "name": "organizationID", "in": "path", "description": "Unique identifier of the organization", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationID" } } ], "responses": { "200": { "description": "Effective resource limits for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationLimits" } } } }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "403": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "org:read" ] } ], "tags": [ "Projects" ], "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" }, "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" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/projects/{projectID}/limits": { "summary": "Project Limits", "description": "Endpoint for retrieving the effective resource limits for a specific project.", "get": { "operationId": "getProjectLimits", "summary": "Get project resource limits", "description": "Retrieves the effective resource limits for the specified project, merging organization-level overrides with any project-specific overrides.", "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 to get limits for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Effective resource limits for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectiveProjectLimits" } } } }, "401": { "$ref": "#/components/responses/AuthorizationError" }, "5XX": { "description": "Unexpected Error" }, "default": { "description": "Unexpected Error" } }, "security": [ { "xata": [ "project:read" ] } ], "tags": [ "Projects" ], "x-operation-kind": "read" } }, "/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, "x-operation-kind": "read" } }, "/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, "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" } }, "/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" ], "x-operation-kind": "read" }, "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" ], "x-operation-kind": "write" }, "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" ], "x-operation-kind": "destructive" } }, "/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, defaults to `xata`", "required": false, "schema": { "type": "string", "default": "xata" } } ], "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" ], "x-operation-kind": "read" } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentials/rotate": { "post": { "operationId": "rotateBranchCredentials", "summary": "Rotate branch credentials", "description": "Triggers a credential rotation for the branch database user. The new credentials can be retrieved via the credentials endpoint after rotation completes.", "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/RotateCredentialsRequest" } } } }, "responses": { "204": { "description": "Credential rotation initiated 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": [ "credentials:write" ] } ], "tags": [ "Branches" ], "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metrics": { "post": { "operationId": "branchMetrics", "summary": "Retrieve branch metrics", "description": "Returns time-series data for one or more metrics of a branch.", "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" ], "x-operation-kind": "read" } }, "/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, "x-operation-kind": "destructive" } }, "/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/logs": { "post": { "operationId": "branchLogs", "summary": "Retrieve branch logs", "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/BranchLogsRequest" } } } }, "responses": { "200": { "description": "Logs for a branch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchLogs" } } } }, "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": [ "logs:read" ] } ], "tags": [ "Branches", "Logs" ], "x-operation-kind": "read" } }, "/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" ], "x-operation-kind": "read" } }, "/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" ], "x-excluded": true, "x-operation-kind": "read" }, "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" ], "x-excluded": true, "x-operation-kind": "write" } }, "/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" ], "x-excluded": true, "x-operation-kind": "write" } }, "/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" ], "x-excluded": true, "x-operation-kind": "read" }, "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" ], "x-excluded": true, "x-operation-kind": "write" }, "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" ], "x-excluded": true, "x-operation-kind": "write" }, "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" ], "x-excluded": true, "x-operation-kind": "destructive" } }, "/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, "x-operation-kind": "write" } }, "/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, "x-operation-kind": "write" } } }, "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", "logs:read": "Read logs data", "credentials:read": "Read credentials", "credentials:write": "Rotate credentials", "marketplace:write": "Register with cloud marketplaces" } } } }, "branchConnectionString": { "type": "apiKey", "in": "header", "name": "Connection-String", "description": "Branch PostgreSQL connection string (`postgres://user:pass@{branch}.{region}.xata.tech/db`), including the embedded password. The hostname selects the target branch, region, and endpoint type (the `-rw`/`-ro` suffix, see `EndpointType`), and must match the request host. Obtain it from the Xata dashboard or the control-plane API. This is the only credential the gateway accepts; the control-plane API key (Bearer token) is rejected here. For the WebSocket endpoint (`GET /v2`) the same connection string is conveyed via the PostgreSQL startup message instead of this header." } }, "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", "allOf": [ { "$ref": "#/components/schemas/OrganizationMarketplaceProvider" } ], "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", "deletion_requested" ] }, "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" ] }, "BillingCustomerResponse": { "type": "object", "properties": { "billing_email": { "type": "string", "format": "email" }, "marketplace": { "description": "Marketplace provider for this organization (e.g. \"aws\"), if billed through a marketplace", "allOf": [ { "$ref": "#/components/schemas/OrganizationMarketplaceProvider" } ], "nullable": true }, "has_payment_method": { "description": "True when the customer has a valid Stripe default card payment method.", "type": "boolean" }, "default_payment_method": { "description": "The Stripe default card payment method, when one is configured and retrievable.", "allOf": [ { "$ref": "#/components/schemas/BillingPaymentMethod" } ], "nullable": true }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCredit" } }, "credit_details": { "$ref": "#/components/schemas/BillingCreditDetails" } }, "required": [ "billing_email", "marketplace", "has_payment_method", "default_payment_method", "credits", "credit_details" ] }, "BillingPaymentMethod": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/BillingPaymentMethodCard" } }, "required": [ "card" ] }, "BillingPaymentMethodCard": { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" }, "expiry_month": { "type": "integer" }, "expiry_year": { "type": "integer" } }, "required": [ "brand", "last4", "expiry_month", "expiry_year" ] }, "BillingCredit": { "type": "object", "properties": { "id": { "type": "string" }, "balance": { "description": "Remaining credit balance.", "type": "number", "format": "double" }, "effective_date": { "description": "Date when the credit becomes usable.", "type": "string", "format": "date-time" }, "expiry_date": { "description": "Date when the credit expires, or null for credits that do not expire.", "type": "string", "format": "date-time", "nullable": true }, "maximum_initial_balance": { "description": "Initial credit balance before any usage.", "type": "number", "format": "double" }, "status": { "type": "string", "enum": [ "active", "pending_payment" ] } }, "required": [ "id", "balance", "effective_date", "expiry_date", "maximum_initial_balance", "status" ] }, "BillingCreditDetails": { "type": "object", "properties": { "total_lifetime_credits": { "type": "number", "format": "double" }, "last_expiry": { "type": "string", "format": "date-time", "nullable": true }, "last_expiry_with_balance": { "type": "string", "format": "date-time", "nullable": true }, "active_credits": { "description": "Credits with active status, a reached effective date, positive balance, and no past expiry.", "type": "array", "items": { "$ref": "#/components/schemas/BillingCredit" } }, "last_active_credit_expiry": { "type": "string", "format": "date-time", "nullable": true }, "total_active_credits": { "type": "number", "format": "double" }, "days_until_last_active_credit_expiry": { "description": "Days until the last active credit expiry, or null when there is no future active credit expiry.", "type": "integer", "nullable": true }, "days_until_last_expiry_with_balance": { "description": "Days until the last positive-balance credit expiry, or null when there is no future positive-balance credit expiry.", "type": "integer", "nullable": true } }, "required": [ "total_lifetime_credits", "last_expiry", "last_expiry_with_balance", "active_credits", "last_active_credit_expiry", "total_active_credits", "days_until_last_active_credit_expiry", "days_until_last_expiry_with_balance" ] }, "UpdateBillingCustomerRequest": { "type": "object", "properties": { "billing_email": { "type": "string", "format": "email" } }, "required": [ "billing_email" ] }, "BillingInvoicesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoice" } }, "pagination_metadata": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination_metadata" ] }, "BillingInvoice": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_number": { "type": "string" }, "amount_due": { "description": "Decimal amount due.", "type": "number", "format": "double" }, "currency": { "type": "string" }, "invoice_date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "issued", "paid", "void", "synced" ] }, "invoice_pdf": { "type": "string", "nullable": true } }, "required": [ "id", "invoice_number", "amount_due", "currency", "invoice_date", "status", "invoice_pdf" ] }, "PaginationMetadata": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "has_more", "next_cursor" ] }, "BillingUpcomingInvoiceResponse": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "amount_due": { "description": "Decimal amount due.", "type": "number", "format": "double" }, "currency": { "type": "string" }, "target_date": { "type": "string", "format": "date-time" }, "subtotal": { "description": "Decimal subtotal.", "type": "number", "format": "double" }, "total": { "description": "Decimal total.", "type": "number", "format": "double" }, "hosted_invoice_url": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "created_at", "amount_due", "currency", "target_date", "subtotal", "total", "hosted_invoice_url" ] }, "BillingCheckoutSessionResponse": { "type": "object", "properties": { "url": { "description": "Stripe checkout session URL", "type": "string", "format": "uri" } }, "required": [ "url" ] }, "BillingPaymentMethodSessionResponse": { "type": "object", "properties": { "url": { "description": "Stripe payment method session URL", "type": "string", "format": "uri" } }, "required": [ "url" ] }, "MarketplaceRegistrationProvider": { "description": "Marketplace provider accepted for registration.", "type": "string", "enum": [ "aws" ], "x-enum-varnames": [ "MarketplaceRegistrationProviderAWS" ] }, "OrganizationMarketplaceProvider": { "description": "Marketplace provider associated with an organization.", "type": "string", "enum": [ "aws" ], "x-enum-varnames": [ "OrganizationMarketplaceProviderAWS" ] }, "MarketplaceRegisterRequest": { "description": "Request to register with a cloud marketplace", "type": "object", "properties": { "marketplace": { "description": "The cloud marketplace provider", "allOf": [ { "$ref": "#/components/schemas/MarketplaceRegistrationProvider" } ] }, "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" ] }, "OrganizationMembershipLimits": { "description": "Membership limits for an organization", "type": "object", "properties": { "maxMembers": { "description": "Maximum number of members allowed in the organization", "type": "integer", "minimum": 1, "title": "Maximum number of organization members" }, "maxInvites": { "description": "Maximum number of pending invitations allowed at once", "type": "integer", "minimum": 1, "title": "Maximum number of pending invitations" } }, "required": [ "maxMembers", "maxInvites" ] }, "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", "pooled_rw" ] }, "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" ] }, "JSONRPCMessage": { "description": "A JSON-RPC 2.0 message. A request carries `id` and `method` and is answered with a\nresponse; a notification carries `method` without `id` and is not. The `method` and\n`params` values are defined by the MCP specification.\n", "type": "object", "properties": { "jsonrpc": { "description": "JSON-RPC protocol version. Always `2.0`.", "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Request identifier, echoed on the response. Omitted for notifications.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "description": "MCP method, such as `initialize`, `tools/list`, or `tools/call`.", "type": "string" }, "params": { "description": "Method parameters as defined by the MCP specification.", "type": "object", "additionalProperties": true } }, "required": [ "jsonrpc", "method" ] }, "JSONRPCResponse": { "description": "A JSON-RPC 2.0 response. Exactly one of `result` or `error` is present.", "type": "object", "properties": { "jsonrpc": { "description": "JSON-RPC protocol version. Always `2.0`.", "type": "string", "enum": [ "2.0" ] }, "id": { "description": "Identifier of the request this responds to.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "result": { "description": "Method result as defined by the MCP specification.", "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/JSONRPCError" } }, "required": [ "jsonrpc", "id" ] }, "JSONRPCError": { "description": "A JSON-RPC 2.0 error. Failures inside a tool are reported in the tool result with `isError`, not here.", "type": "object", "properties": { "code": { "description": "JSON-RPC error code.", "type": "integer" }, "message": { "description": "Short description of the error.", "type": "string" }, "data": { "description": "Additional error detail." } }, "required": [ "code", "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" }, "maxItems": 64 } }, "required": [ "enabled", "cidr" ] }, "CidrEntry": { "type": "object", "properties": { "cidr": { "description": "IP address or CIDR block (e.g., \"192.168.0.0/24\")", "type": "string", "maxLength": 64, "minLength": 1 }, "description": { "description": "Optional label for the CIDR entry", "type": "string", "maxLength": 100 } }, "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": "Deprecated: retrieve the connection string from the branch credentials endpoint (GET .../branches/{branchID}/credentials) instead.", "type": "string", "deprecated": true, "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": "Deprecated: retrieve the connection string from the branch credentials endpoint (GET .../branches/{branchID}/credentials) instead.", "type": "string", "deprecated": true, "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 and connection details for accessing a branch", "type": "object", "properties": { "username": { "description": "Username for accessing the branch database", "type": "string" }, "password": { "description": "Password for accessing the branch database", "type": "string" }, "hostname": { "description": "Hostname for accessing the branch database", "type": "string" }, "port": { "description": "Port for accessing the branch database", "type": "integer" }, "dbname": { "description": "Name of the database to connect to", "type": "string" }, "connectionString": { "description": "Database connection string for accessing this branch. It carries no sslmode parameter, clients choose their own TLS settings.", "type": "string" } }, "required": [ "username", "password", "hostname", "port", "dbname", "connectionString" ] }, "RotateCredentialsRequest": { "description": "Request to rotate credentials for a branch database user", "type": "object", "properties": { "username": { "description": "Database username to rotate credentials for", "type": "string" } }, "required": [ "username" ] }, "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). The maximum allowed value depends on the organization's storage limit.", "type": "integer", "format": "int32", "minimum": 1 }, "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" } }, "image": { "description": "PostgreSQL image to use for the database instances", "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": { "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" }, "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": [ "maxInstances", "minInstances", "maxDescriptionLength", "maxBranches" ] }, "BranchMetricName": { "description": "Name of a branch metric exposed by the API.", "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" ] }, "OrganizationLimits": { "description": "Effective resource limits for an organization, covering org-level defaults for all projects plus organization-specific constraints", "allOf": [ { "$ref": "#/components/schemas/EffectiveProjectLimits" }, { "type": "object", "properties": { "maxProjects": { "description": "Maximum number of projects allowed in the organization", "type": "integer", "minimum": 1, "title": "Maximum number of projects" }, "maxProjectsPerHour": { "description": "Maximum number of projects that can be created in a rolling one-hour window", "type": "integer", "minimum": 1, "title": "Maximum project creation rate per hour" }, "maxBranchesPerOrg": { "description": "Maximum number of active branches allowed across all projects in the organization", "type": "integer", "minimum": 1, "title": "Maximum number of branches per organization" } }, "required": [ "maxProjects", "maxProjectsPerHour", "maxBranchesPerOrg" ] } ] }, "EffectiveProjectLimits": { "description": "Full set of resource limits applicable to a project and its branches", "type": "object", "properties": { "maxDescriptionLength": { "description": "Maximum character length allowed for project descriptions", "type": "integer", "minimum": 25, "title": "Maximum length of a project description" }, "maxBranchesPerProject": { "description": "Maximum number of branches allowed per project", "type": "integer", "title": "Maximum number of branches per project" }, "maxInstancesPerBranch": { "description": "Maximum number of database instances allowed per branch", "type": "integer", "minimum": 1, "title": "Maximum number of instances per branch" }, "minInstancesPerBranch": { "description": "Minimum number of database instances required per branch", "type": "integer", "minimum": 1, "title": "Minimum number of instances per branch" }, "maxAllowedInstanceType": { "description": "Maximum VCPUs (in millicores) allowed per instance; instance types with a higher VCPUsRequest are unavailable", "type": "integer", "minimum": 1, "title": "Maximum allowed instance type (VCPUs in millicores)" }, "maxBranchesPerHour": { "description": "Maximum number of branches that can be created in a rolling one-hour window", "type": "integer", "minimum": 1, "title": "Maximum branch creation rate per hour" }, "maxStorageGBPerBranch": { "description": "Maximum storage in GiB (gigabytes) allowed per branch; 0 means no limit", "type": "integer", "minimum": 0, "title": "Maximum storage per branch (GiB)" } }, "required": [ "maxDescriptionLength", "maxBranchesPerProject", "maxInstancesPerBranch", "minInstancesPerBranch", "maxAllowedInstanceType", "maxBranchesPerHour", "maxStorageGBPerBranch" ] }, "BranchMetricsRequest": { "type": "object", "properties": { "start": { "description": "Start time", "type": "string", "format": "date-time" }, "end": { "description": "End time", "type": "string", "format": "date-time" }, "metrics": { "description": "List of metric names to query.", "type": "array", "items": { "$ref": "#/components/schemas/BranchMetricName" }, "maxItems": 15, "minItems": 1 }, "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 per metric in the response.", "type": "array", "items": { "type": "string", "enum": [ "avg", "max", "min" ] } } }, "required": [ "start", "end", "metrics", "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" }, "results": { "description": "One entry per requested metric, in the order the metrics were requested.", "type": "array", "items": { "$ref": "#/components/schemas/BranchMetricResult" } } }, "required": [ "start", "end", "results" ] }, "BranchMetricResult": { "description": "Time-series for a single metric.", "type": "object", "properties": { "metric": { "description": "Name of the queried metric.", "type": "string" }, "unit": { "description": "Unit of the metric (percentage, bytes, ms, etc.)", "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } } }, "required": [ "metric", "unit", "series" ] }, "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" ] }, "BranchLogsRequest": { "type": "object", "properties": { "start": { "description": "Start time", "type": "string", "format": "date-time" }, "end": { "description": "End time", "type": "string", "format": "date-time" }, "filters": { "description": "Filters applied to log entries. Multiple filters are combined with AND.", "type": "array", "items": { "$ref": "#/components/schemas/LogFilter" } }, "limit": { "type": "integer", "default": 100, "maximum": 200, "minimum": 1 }, "cursor": { "description": "Pagination cursor from a previous response", "type": "string" } }, "required": [ "start", "end" ] }, "BranchLogs": { "description": "A collection of logs for each of the instances of a branch", "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "logs": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } }, "nextCursor": { "description": "Pagination cursor for the next page", "type": "string", "nullable": true } }, "required": [ "start", "end", "logs", "nextCursor" ] }, "LogFilter": { "description": "A single filter on log entries.", "type": "object", "properties": { "field": { "description": "Log attribute to filter on.", "type": "string", "enum": [ "instance", "level", "process", "body" ] }, "op": { "description": "Match operator.", "type": "string", "enum": [ "in", "contains", "icontains", "regex", "iregex" ] }, "values": { "description": "Used with `op: in`.", "type": "array", "items": { "type": "string" } }, "value": { "description": "Used with the body operators.", "type": "string" } }, "required": [ "field", "op" ] }, "LogEntry": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "instanceID": { "type": "string" }, "level": { "$ref": "#/components/schemas/LogLevel" }, "message": { "type": "string" }, "process": { "description": "Name of the PostgreSQL process that emitted the log", "type": "string" } }, "required": [ "timestamp", "instanceID", "message" ] }, "LogLevel": { "description": "Log level enumeration", "type": "string", "enum": [ "debug", "info", "warning", "error" ] }, "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", "Billing", "Webhooks" ] }, { "name": "Gateway API", "tags": [ "Gateway" ] }, { "name": "MCP API", "tags": [ "MCP" ] }, { "name": "Projects API", "tags": [ "Projects Webhooks", "Projects", "Branches", "GitHub App", "Metrics", "Logs" ] } ] }