{"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":"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"]},"post":{"operationId":"createOrganization","summary":"Create a new organization","description":"Creates a new organization with the authenticated user as its single owner.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationRequest"}}}},"responses":{"201":{"description":"Organization successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["org:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}":{"summary":"Organization Operations","description":"This endpoint provides operations for a specific organization, allowing retrieval, updating, and deletion of an organization by its unique identifier.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"get":{"operationId":"getOrganization","summary":"Get organization details","description":"Retrieve detailed information about a specific organization by its ID.","responses":{"200":{"description":"Organization details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["org:read"]}],"tags":["Organizations"]},"put":{"operationId":"updateOrganization","summary":"Update organization details","description":"Update information for an existing organization, such as its name.","requestBody":{"content":{"application/json":{"schema":{"properties":{"id":{"description":"Unique identifier for the organization to update","$ref":"#/components/schemas/OrganizationID"},"name":{"description":"New name for the organization","type":"string"}}}}}},"responses":{"200":{"description":"Organization successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["org:write"]}],"tags":["Organizations"]},"delete":{"operationId":"deleteOrganization","summary":"Delete an organization","description":"[Not implemented yet] Permanently delete an organization. This action cannot be undone.","responses":{"204":{"description":"Organization successfully deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["org:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/api-keys":{"get":{"operationId":"listOrganizationAPIKeys","summary":"List API Keys for an organization","description":"Retrieve a list of API keys for a specific organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"responses":{"200":{"description":"List of API keys retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"description":"Array of API keys for the organization","type":"array","items":{"$ref":"#/components/schemas/APIKeyPreview"}}},"required":["keys"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["keys:read"]}],"tags":["API Keys"]},"post":{"operationId":"createOrganizationAPIKey","summary":"Create an Organization API Key","description":"Create a new API key for an organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}}},"responses":{"201":{"description":"API Key created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/FullAPIKey"}},"required":["key"]}}}},"400":{"description":"API key limit reached or invalid request"}},"security":[{"xata":["keys:write"]}],"tags":["API Keys"]},"delete":{"operationId":"deleteOrganizationAPIKeys","summary":"Bulk delete API Keys for an organization","description":"Delete multiple API keys in a single request.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"description":"Array of API key IDs to delete","type":"array","items":{"type":"string"},"maxItems":50}},"required":["ids"]}}}},"responses":{"204":{"description":"API Keys deleted successfully"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"}},"security":[{"xata":["keys:write"]}],"tags":["API Keys"]}},"/organizations/{organizationID}/members":{"get":{"operationId":"listOrganizationMembers","summary":"List members of an organization","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/UserWithID"}}},"required":["members"]}}}}},"security":[{"xata":["org:read"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/members/{userID}":{"delete":{"operationId":"removeOrganizationMember","summary":"Remove a member from an organization","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"$ref":"#/components/parameters/UserIDParam"}],"responses":{"204":{"description":"Member removed"}},"security":[{"xata":["org:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/invitations":{"get":{"operationId":"listOrganizationInvitations","summary":"List invitations for an organization","description":"Retrieve all invitations for an organization with optional filtering by status, email, and name.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"name":"status","in":"query","description":"Filter invitations by status","schema":{"type":"string","enum":["pending","expired"]}},{"name":"email","in":"query","description":"Filter invitations by email address","schema":{"type":"string"}},{"name":"first_name","in":"query","description":"Filter invitations by first name","schema":{"type":"string"}},{"name":"last_name","in":"query","description":"Filter invitations by last name","schema":{"type":"string"}},{"name":"search","in":"query","description":"Search invitations by email or name","schema":{"type":"string"}},{"name":"first","in":"query","description":"Index of the first result to return (0-based offset for pagination)","schema":{"type":"integer","default":0,"minimum":0}},{"name":"max","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":100,"maximum":100,"minimum":1}}],"responses":{"200":{"description":"List of invitations retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationInvitation"}}},"required":["invitations"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["invite:read"]}],"tags":["Organizations"]},"post":{"operationId":"createOrganizationInvitation","summary":"Send an invitation to join an organization","description":"Send an invitation email to a user to join an organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationInvitationRequest"}}}},"responses":{"201":{"description":"Invitation sent successfully"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"409":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["invite:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/invitations/{invitationID}":{"get":{"operationId":"getOrganizationInvitation","summary":"Get details of a specific invitation","description":"Retrieve detailed information about a specific invitation by its ID.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"$ref":"#/components/parameters/InvitationIDParam"}],"responses":{"200":{"description":"Invitation details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvitation"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["invite:read"]}],"tags":["Organizations"]},"delete":{"operationId":"deleteOrganizationInvitation","summary":"Delete an invitation","description":"Permanently delete an invitation record.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"$ref":"#/components/parameters/InvitationIDParam"}],"responses":{"204":{"description":"Invitation deleted successfully"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["invite:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/invitations/{invitationID}/resend":{"post":{"operationId":"resendOrganizationInvitation","summary":"Resend an invitation","description":"Resend a pending invitation with a fresh expiration time.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"$ref":"#/components/parameters/InvitationIDParam"}],"responses":{"204":{"description":"Invitation resent successfully"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["invite:write"]}],"tags":["Organizations"]}},"/organizations/{organizationID}/deletion-request":{"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","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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"]}},"/organizations/{organizationID}/membership-limits":{"get":{"operationId":"getOrganizationMembershipLimits","summary":"Get organization membership limits","description":"Retrieves the membership limits for the specified organization (maximum members and invitations).","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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"]}},"/organizations/{organizationID}/billing/checkout-session":{"post":{"operationId":"createBillingCheckoutSession","summary":"Create a billing checkout session","description":"Creates a Stripe checkout session used to activate card billing for an organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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}},"/organizations/{organizationID}/billing/payment-method-session":{"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.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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}},"/organizations/{organizationID}/billing/customer":{"get":{"operationId":"getBillingCustomer","summary":"Get billing customer details","description":"Retrieves billing customer details for the specified organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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},"patch":{"operationId":"updateBillingCustomer","summary":"Update billing customer details","description":"Updates billing customer details for the specified organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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}},"/organizations/{organizationID}/billing/invoices":{"get":{"operationId":"getBillingInvoices","summary":"List billing invoices","description":"Retrieves billing invoices for the specified organization.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"},{"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}},"/organizations/{organizationID}/billing/invoices/upcoming":{"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.","parameters":[{"$ref":"#/components/parameters/OrganizationIDParam"}],"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}},"/marketplace/register":{"post":{"operationId":"registerMarketplace","summary":"Register with a cloud marketplace","description":"Links the authenticated user to a cloud marketplace subscription. Only one marketplace registration is allowed per user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceRegisterRequest"}}}},"responses":{"200":{"description":"Marketplace registration successful"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"409":{"$ref":"#/components/responses/SimpleError"},"502":{"description":"Marketplace registration provider failed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}},"security":[{"xata":["marketplace:write"]}],"tags":["Marketplace"],"x-excluded":true}},"/api-keys":{"get":{"operationId":"listUserAPIKeys","summary":"List API Keys for the authenticated user","description":"Retrieve a list of API keys for the authenticated user.","responses":{"200":{"description":"List of API keys retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"description":"Array of API keys for the user","type":"array","items":{"$ref":"#/components/schemas/APIKeyPreview"}}},"required":["keys"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["keys:read"]}],"tags":["API Keys"]},"post":{"operationId":"createUserAPIKey","summary":"Create a User API Key","description":"Create a new API key for the authenticated user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}}},"responses":{"201":{"description":"API Key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/FullAPIKey"}},"required":["key"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["keys:write"]}],"tags":["API Keys"]},"delete":{"operationId":"deleteUserAPIKeys","summary":"Bulk delete API Keys for the authenticated user","description":"Delete multiple API keys in a single request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"description":"Array of API key IDs to delete (maximum 50 keys per request)","type":"array","items":{"type":"string"},"maxItems":50}},"required":["ids"]}}}},"responses":{"204":{"description":"API Keys deleted successfully"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/SimpleError"},"5XX":{"description":"Unexpected Error"}},"security":[{"xata":["keys:write"]}],"tags":["API Keys"]}},"/sql":{"servers":[{"url":"https://{branch}.{region}.xata.tech","description":"Xata 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 or SQL error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid connection string","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"507":{"description":"Response too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"branchConnectionString":[]}],"tags":["Gateway"]}},"/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"]}},"/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}},"/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"]}},"/organizations/{organizationID}/instanceTypes":{"summary":"Instance Types Operations","description":"Endpoints for retrieving available instance types for creating branches within an organization.","get":{"operationId":"listInstanceTypes","summary":"Get available instance types","description":"Retrieves a list of all instance types for the specified organization and region","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to check instance type availability for","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"region","in":"query","description":"Region to check instance type availability for","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of instance types available for the organization","content":{"application/json":{"schema":{"type":"object","properties":{"instanceTypes":{"description":"Array of available instance types with their properties","type":"array","items":{"type":"object","properties":{"name":{"description":"Instance type name","type":"string"},"vcpus":{"description":"number of vCPUs","type":"integer"},"ram":{"description":"memory in Gi","type":"integer"},"hourlyRate":{"description":"price per hour for this instance type and region","type":"number","format":"double"},"storageMonthlyRate":{"description":"price per month for a GB of storage for this region","type":"number","format":"double"},"region":{"description":"region where this instance type is available","type":"string"}},"required":["name","vcpus","ram","hourlyRate","region","storageMonthlyRate"]}}},"required":["instanceTypes"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["org:read"]}],"tags":["Projects"]}},"/organizations/{organizationID}/images":{"summary":"Images Operations","description":"Endpoints for retrieving available images for creating branches within an organization.","get":{"operationId":"listImages","summary":"Get available images","description":"Retrieves a list of all images for the specified organization and region","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to check image availability","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"region","in":"query","description":"Region to check image availability for organization","schema":{"type":"string"}}],"responses":{"200":{"description":"List of images available for the organization","content":{"application/json":{"schema":{"type":"object","properties":{"images":{"description":"Array of available images with their properties","type":"array","items":{"$ref":"#/components/schemas/Image"}}},"required":["images"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["org:read"]}],"tags":["Projects"]}},"/organizations/{organizationID}/extensions":{"summary":"Extensions Operations","description":"Endpoints for retrieving available extensions of images used for creating branches within an organization.","get":{"operationId":"listExtensions","summary":"Get available extensions for image","description":"Retrieves a list of all extensions for the specified image in the organization and region given","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to check instance type availability for","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"image","in":"query","description":"Image for which we list extensions","required":true,"schema":{"type":"string"}},{"name":"region","in":"query","description":"Region to list extensions for image in","schema":{"type":"string"}}],"responses":{"200":{"description":"List of extensions available for the image in the organization","content":{"application/json":{"schema":{"type":"object","properties":{"extensions":{"description":"Array of available images with their properties","type":"array","items":{"$ref":"#/components/schemas/Extension"}}},"required":["extensions"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["org:read"]}],"tags":["Projects"],"x-excluded":true,"x-internal":true}},"/organizations/{organizationID}/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"]}},"/organizations/{organizationID}/projects/limits":{"summary":"Project Limits","description":"Endpoint for retrieving the default resource limits for projects within an organization.","get":{"operationId":"getDefaultProjectLimits","summary":"Get project resource limits","description":"Retrieves the default resource limits for projects in the specified organization, including maximum instances, storage, and allowed regions.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to get project limits for","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}}],"responses":{"200":{"description":"Default resource limits for projects in the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectLimits"}}}}},"security":[{"xata":["project:read"]}],"tags":["Projects"]}},"/organizations/{organizationID}/projects":{"summary":"Projects Management","description":"Endpoints for listing and creating projects within an organization.","get":{"operationId":"listProjects","summary":"List all projects","description":"Retrieves a list of all projects within the specified organization that the authenticated user has access to.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to list projects from","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}}],"responses":{"200":{"description":"A list of projects within the organization","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"description":"Array of project objects with their metadata","type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["projects"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:read"]}],"tags":["Projects"]},"post":{"operationId":"createProject","summary":"Create a new project","description":"Creates a new project within the specified organization. Projects are containers for database branches and resources.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization to create the project in","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Human-readable name for the new project","type":"string"},"configuration":{"$ref":"#/components/schemas/ProjectConfiguration"}},"required":["name"]}}}},"responses":{"201":{"description":"Project successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:write"]}],"tags":["Projects"]}},"/organizations/{organizationID}/projects/{projectID}":{"summary":"Project Operations","description":"Endpoints for retrieving, updating, and deleting a specific project by ID.","get":{"operationId":"getProject","summary":"Get project details","description":"Retrieves detailed information about a specific project by its ID within the specified organization.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to retrieve","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:read"]}],"tags":["Projects"]},"patch":{"operationId":"updateProject","summary":"Update project details","description":"Updates the details of a specific project by its ID, such as changing its name.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to update","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name for the project","type":"string"},"configuration":{"$ref":"#/components/schemas/UpdateProjectConfiguration"}}}}}},"responses":{"200":{"description":"Project successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:write"]}],"tags":["Projects"]},"delete":{"operationId":"deleteProject","summary":"Delete a project","description":"Permanently deletes a specific project by its ID and all associated resources including branches and databases. This action cannot be undone.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to delete","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Project successfully deleted"},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:write"]}],"tags":["Projects"]}},"/organizations/{organizationID}/projects/{projectID}/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"]}},"/organizations/{organizationID}/projects/{projectID}/backups":{"summary":"Backups Operations","description":"Endpoints for managing project backups.","get":{"operationId":"listBackups","summary":"List project backups","description":"Retrieves a list of backups for the specified project.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to retrieve backups for","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of backups within the project","content":{"application/json":{"schema":{"type":"object","properties":{"backups":{"description":"list of backups within the project","type":"array","items":{"$ref":"#/components/schemas/BackupMetadata"}}},"required":["backups"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:read"]}],"tags":["Projects"],"x-excluded":true,"x-internal":true}},"/organizations/{organizationID}/projects/{projectID}/backups/{backupID}":{"summary":"Backup Operations","description":"Endpoints for getting project backup.","get":{"operationId":"getBackup","summary":"Get project backup by ID","description":"Retrieves a backup by ID for the specified project.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to retrieve backups for","required":true,"schema":{"type":"string"}},{"name":"backupID","in":"path","description":"Unique identifier of the backup for the project","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The backup metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupMetadata"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:read"]}],"tags":["Projects"],"x-excluded":true,"x-internal":true}},"/organizations/{organizationID}/projects/{projectID}/branches":{"summary":"Branch Management","description":"Endpoints for listing and creating branches within a project.","get":{"operationId":"listBranches","summary":"List all branches","description":"Retrieves a list of all branches within the specified project, including their metadata, region, and access settings.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to list branches from","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of branches within the project","content":{"application/json":{"schema":{"type":"object","properties":{"branches":{"description":"Array of branch objects with their metadata","type":"array","items":{"$ref":"#/components/schemas/BranchListMetadata"}}},"required":["branches"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:read"]}],"tags":["Branches"]},"post":{"operationId":"createBranch","summary":"Create a new branch","description":"Creates a new branch within the specified project. Branches can be created from scratch or derived from an existing parent branch.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project to create the branch in","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchCreationDetails"}}}},"responses":{"201":{"description":"Branch successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchShortMetadata"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"412":{"$ref":"#/components/responses/PreconditionFailedError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:write"]}],"tags":["Branches"]}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}":{"summary":"Branch Operations","description":"Endpoints for retrieving, updating, and deleting a specific branch by ID.","get":{"operationId":"describeBranch","summary":"Get branch details","description":"Retrieves detailed information about a specific branch by its ID, including status, connection string, and configuration.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project containing the branch","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","description":"Unique identifier of the branch to retrieve details for","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Branch details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchMetadata"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:read"]}],"tags":["Branches"]},"patch":{"operationId":"updateBranch","summary":"Update branch details","description":"Updates the configuration of a specific branch by its ID, such as changing its name, description, or resource allocation.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project containing the branch","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","description":"Unique identifier of the branch to update","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchUpdateDetails"}}}},"responses":{"200":{"description":"Branch successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchShortMetadata"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:write"]}],"tags":["Branches"]},"delete":{"operationId":"deleteBranch","summary":"Delete a branch","description":"Permanently deletes a specific branch by its ID and all associated data. This action cannot be undone.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project containing the branch","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","description":"Unique identifier of the branch to delete","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Branch successfully deleted"},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:write"]}],"tags":["Branches"]}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentials":{"get":{"operationId":"getBranchCredentials","summary":"Retrieve branch credentials","parameters":[{"name":"organizationID","in":"path","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","required":true,"schema":{"type":"string"}},{"name":"username","in":"query","description":"Username that the credentials requested for","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credentials for the branch retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchCredentials"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["credentials:read"]}],"tags":["Branches"]}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/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"]}},"/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"]}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/restore":{"summary":"Restore from backup","description":"Endpoint for restoring from a backup.","post":{"operationId":"restoreFromBackup","summary":"Create a new branch from a backup of another branch","description":"Creates a new backup branch within the specified project.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project containing the source branch","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","description":"Unique identifier of the source branch of the backup","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreDetails"}}}},"responses":{"201":{"description":"Branch successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchShortMetadata"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:write"]}],"tags":["Branches"],"x-excluded":true,"x-internal":true}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/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"]}},"/organizations/{organizationID}/projects/{projectID}/branches/{branchID}/postgres-config":{"get":{"operationId":"getBranchPostgresConfig","summary":"Get PostgreSQL configuration details","description":"Retrieves detailed information about the current PostgreSQL configuration parameters for a branch, including parameter types, descriptions, acceptable ranges, default values, and current values.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization containing the project","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}},{"name":"projectID","in":"path","description":"Unique identifier of the project containing the branch","required":true,"schema":{"type":"string"}},{"name":"branchID","in":"path","description":"Unique identifier of the branch to retrieve PostgreSQL configuration for","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"PostgreSQL configuration details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostgresConfigDetails"}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"404":{"$ref":"#/components/responses/GenericError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["branch:read"]}],"tags":["Branches"]}},"/organizations/{organizationID}/githubapp/installations":{"summary":"GitHub App Installation Operations (organization-scoped)","description":"Manage GitHub App installations for an organization.","get":{"operationId":"listGithubAppInstallations","summary":"List GitHub App installations for organization","description":"Returns all GitHub App installations associated with the specified organization.","parameters":[{"name":"organizationID","in":"path","description":"Unique identifier of the organization","required":true,"schema":{"$ref":"#/components/schemas/OrganizationID"}}],"responses":{"200":{"description":"List of GitHub App installations","content":{"application/json":{"schema":{"type":"object","properties":{"installations":{"description":"Array of GitHub App installations","type":"array","items":{"$ref":"#/components/schemas/GithubInstallation"}}},"required":["installations"]}}}},"400":{"$ref":"#/components/responses/GenericError"},"401":{"$ref":"#/components/responses/AuthorizationError"},"5XX":{"description":"Unexpected Error"},"default":{"description":"Unexpected Error"}},"security":[{"xata":["project:read"]}],"tags":["GitHub App"],"x-excluded":true},"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}},"/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}},"/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},"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},"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},"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}},"/webhooks/orb":{"post":{"operationId":"orbWebhook","summary":"Orb billing webhook","description":"Endpoint used by Orb to deliver billing-related webhook events.\nThis endpoint is authenticated via Orb's HMAC signature headers,\nnot via the normal API authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Orb webhook event payload","type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Webhook received and processed successfully"},"400":{"description":"Invalid signature or malformed request"},"500":{"description":"Internal error while handling the webhook"}},"tags":["Webhooks"],"x-excluded":true}},"/webhooks/stripe":{"post":{"operationId":"stripeWebhook","summary":"Stripe webhook","description":"Endpoint used by Stripe to deliver webhook events.\nThis endpoint is authenticated via Stripe's signature headers,\nnot via the normal API authentication.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Stripe webhook event payload","type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Webhook received and processed successfully"},"400":{"description":"Invalid signature or malformed request"},"500":{"description":"Internal error while handling the webhook"}},"tags":["Webhooks"],"x-excluded":true}}},"components":{"securitySchemes":{"oidc":{"type":"openIdConnect","openIdConnectUrl":"https://auth.xata.io/realms/xata/.well-known/openid-configuration"},"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication using Bearer token format: Bearer \u003capi_key\u003e"},"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","type":"string","nullable":true}},"required":["id","name","status"]},"OrganizationStatus":{"type":"object","properties":{"status":{"description":"Indicates whether the organization is active, it's computed as `!disabled_by_admin AND billing_status == 'ok'`","type":"string","enum":["enabled","disabled"]},"disabled_by_admin":{"description":"Indicates if the organization has been disabled by an admin","type":"boolean"},"admin_reason":{"description":"Reason for the current admin status","type":"string"},"billing_status":{"description":"Indicates the status of the organization from a billing perspective","type":"string","enum":["ok","no_payment_method","invoice_overdue","unknown","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"},"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","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"]},"MarketplaceRegisterRequest":{"description":"Request to register with a cloud marketplace","type":"object","properties":{"marketplace":{"description":"The cloud marketplace provider","type":"string","enum":["aws"]},"company_name":{"description":"Company name for the marketplace registration","type":"string"},"aws":{"description":"AWS-specific marketplace details","type":"object","properties":{"customer_id":{"description":"AWS Marketplace customer ID","type":"string"},"product_id":{"description":"AWS Marketplace product ID","type":"string"},"account_id":{"description":"AWS account ID","type":"string"}},"required":["customer_id","product_id","account_id"]}},"required":["marketplace","company_name","aws"]},"CreateAPIKeyRequest":{"type":"object","properties":{"name":{"type":"string"},"expiry":{"description":"Expiration date for the API key, null for no expiry","type":"string","format":"date-time","nullable":true},"scopes":{"description":"Optional scopes assigned to the API key","type":"array","items":{"type":"string"},"maxItems":50},"projects":{"description":"Limit access to these projects","type":"array","items":{"type":"string"},"maxItems":50},"branches":{"description":"Limit access to these branches","type":"array","items":{"type":"string"},"maxItems":50}},"required":["name"]},"APIKeyPreview":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"preview":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"projects":{"description":"Projects this API key has access to","type":"array","items":{"type":"string"}},"branches":{"description":"Branches this API key has access to","type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"expiry":{"description":"Date when the API key expires (null if no expiry)","type":"string","format":"date-time","nullable":true},"last_used":{"description":"Timestamp of the last time the key was used (null if never)","type":"string","format":"date-time","nullable":true},"created_by":{"description":"ID of the user that created this API key","type":"string","nullable":true},"created_by_key":{"description":"ID of the API key that created this API key","type":"string","nullable":true}},"required":["id","name","preview","created_at","expiry","last_used","scopes","projects","branches"]},"FullAPIKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"preview":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"projects":{"description":"Projects this API key has access to","type":"array","items":{"type":"string"}},"branches":{"description":"Branches this API key has access to","type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"expiry":{"description":"Date when the API key expires (null if no expiry)","type":"string","format":"date-time","nullable":true},"last_used":{"description":"Timestamp of the last time the key was used (null if never)","type":"string","format":"date-time","nullable":true},"token":{"description":"The actual API key token","type":"string"},"created_by":{"description":"ID of the user that created this API key","type":"string","nullable":true},"created_by_key":{"description":"ID of the API key that created this API key","type":"string","nullable":true}},"required":["id","name","preview","created_at","expiry","last_used","token","scopes","projects","branches"]},"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"]},"GithubInstallation":{"description":"A GitHub App installation associated with an organization","type":"object","properties":{"id":{"description":"Unique identifier of the installation record","type":"string"},"installationId":{"description":"GitHub App installation ID","type":"integer","format":"int64"},"organization":{"description":"Organization ID this installation belongs to","type":"string"},"createdAt":{"description":"Timestamp when the installation was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the installation was last updated","type":"string","format":"date-time"}},"required":["id","installationId","organization","createdAt","updatedAt"]},"GithubRepository":{"description":"A mapping between a GitHub repository and a Xata project","type":"object","properties":{"id":{"description":"Unique identifier of the mapping record","type":"string"},"githubRepositoryID":{"description":"GitHub repository ID","type":"integer","format":"int64"},"project":{"description":"Project ID this mapping is associated with","type":"string"},"rootBranchId":{"description":"ID of the root Xata branch mapped to this repository","type":"string"},"createdAt":{"description":"Timestamp when the mapping was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the mapping was last updated","type":"string","format":"date-time"}},"required":["id","githubRepositoryID","project","rootBranchId","createdAt","updatedAt"]},"CreateGithubAppInstallationRequest":{"type":"object","properties":{"installationId":{"description":"GitHub App installation ID","type":"integer","format":"int64"}},"required":["installationId"]},"UpdateGithubAppInstallationRequest":{"type":"object","properties":{"installationId":{"description":"GitHub App installation ID","type":"integer","format":"int64"}},"required":["installationId"]},"CreateGithubRepositoryRequest":{"type":"object","properties":{"githubRepositoryID":{"description":"GitHub repository ID","type":"integer","format":"int64"}},"required":["githubRepositoryID"]},"UpdateGithubRepositoryRequest":{"type":"object","properties":{"githubRepositoryID":{"description":"GitHub repository ID","type":"integer","format":"int64"}},"required":["githubRepositoryID"]},"Extension":{"description":"Details of a postgres extension","type":"object","properties":{"name":{"description":"Extension name","type":"string"},"version":{"description":"Extension version","type":"string"},"description":{"description":"Extension description","type":"string"},"docs":{"description":"Documentation URL","type":"string"},"preloadRequired":{"description":"is preload required for the extension or not","type":"boolean"},"type":{"description":"type of installation","type":"string","enum":["extension","plugin","module"]}},"required":["name","description","version","docs","preloadRequired","type"],"x-excluded":true,"x-internal":true},"Image":{"description":"Details of a postgres image","type":"object","properties":{"name":{"description":"Image name","type":"string"},"majorVersion":{"description":"major postgres version","type":"string"},"fullVersion":{"description":"full postgres version","type":"string"},"region":{"description":"region where this instance type is available","type":"array","items":{"type":"string","minItems":1}}},"required":["name","majorVersion","fullVersion"]},"Project":{"description":"Details of a project including its ID, name, and creation/update timestamps","type":"object","properties":{"id":{"description":"Unique identifier for the project","type":"string"},"name":{"description":"Human-readable name of the project","type":"string"},"createdAt":{"description":"Timestamp when the project was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the project was last updated","type":"string","format":"date-time"},"configuration":{"$ref":"#/components/schemas/ProjectConfiguration"}},"required":["id","name","createdAt","updatedAt","configuration"]},"ProjectConfiguration":{"description":"Configuration details for a project, including its scale to zero settings","type":"object","properties":{"scaleToZero":{"$ref":"#/components/schemas/ProjectScaleToZeroConfiguration"},"ipFiltering":{"$ref":"#/components/schemas/IPFilteringConfiguration"}},"required":["scaleToZero"]},"UpdateProjectConfiguration":{"description":"Partial configuration update for a project","type":"object","properties":{"scaleToZero":{"$ref":"#/components/schemas/ProjectScaleToZeroConfiguration"},"ipFiltering":{"$ref":"#/components/schemas/IPFilteringConfiguration"}}},"ProjectScaleToZeroConfiguration":{"description":"Whether the project branches are configured to scale down to zero when not in use","type":"object","properties":{"baseBranches":{"$ref":"#/components/schemas/ScaleToZeroConfiguration"},"childBranches":{"$ref":"#/components/schemas/ScaleToZeroConfiguration"}},"required":["baseBranches","childBranches"]},"ScaleToZeroConfiguration":{"description":"Configuration for scaling branches to zero when not in use","type":"object","properties":{"enabled":{"description":"Whether scale to zero is enabled","type":"boolean"},"inactivityPeriodMinutes":{"description":"Duration in minutes after which branches will be hibernated if not accessed","type":"integer","default":30}},"required":["enabled","inactivityPeriodMinutes"]},"IPFilteringConfiguration":{"description":"Configuration for IP filtering on project branches","type":"object","properties":{"enabled":{"description":"Whether IP filtering is enabled","type":"boolean"},"cidr":{"type":"array","items":{"$ref":"#/components/schemas/CidrEntry"}}},"required":["enabled","cidr"]},"CidrEntry":{"type":"object","properties":{"cidr":{"description":"CIDR block (e.g., \"192.168.0.0/24\")","type":"string"},"description":{"description":"Optional label for the CIDR entry","type":"string"}},"required":["cidr"]},"BranchFromParent":{"type":"object","properties":{"mode":{"type":"string","enum":["inherit"]},"parentID":{"description":"If present, the branch will inherit the parent branch configuration and data","type":"string"}},"required":["mode","parentID"]},"BranchFromConfiguration":{"type":"object","properties":{"mode":{"type":"string","enum":["custom"]},"configuration":{"$ref":"#/components/schemas/ClusterConfiguration"}},"required":["mode","configuration"]},"BranchShortMetadata":{"description":"Basic metadata about a branch, used in response to create/update operations","type":"object","properties":{"id":{"description":"Unique identifier for the branch","type":"string"},"name":{"description":"Human-readable name of the branch","type":"string"},"description":{"description":"Optional description of the branch purpose or contents","type":"string"},"createdAt":{"description":"Timestamp when the branch was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the branch was last updated","type":"string","format":"date-time"},"parentID":{"description":"Identifier of the parent branch if this is a derived branch, null otherwise","type":"string","nullable":true},"connectionString":{"description":"Database connection string for accessing this branch","type":"string","nullable":true},"region":{"description":"Geographic region where the branch is deployed","type":"string"},"publicAccess":{"description":"Whether the branch allows public access without authentication","type":"boolean"}},"required":["id","name","createdAt","updatedAt","region","publicAccess"]},"BranchListMetadata":{"description":"Metadata about a branch used when listing branches in a project","type":"object","properties":{"id":{"description":"Unique identifier for the branch","type":"string"},"name":{"description":"Human-readable name of the branch","type":"string"},"description":{"description":"Optional description of the branch purpose or contents","type":"string"},"createdAt":{"description":"Timestamp when the branch was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the branch was last updated","type":"string","format":"date-time"},"parentID":{"description":"Identifier of the parent branch if this is a derived branch, null otherwise","type":"string","nullable":true},"region":{"description":"Geographic region where the branch is deployed","type":"string"},"publicAccess":{"description":"Whether the branch allows public access without authentication","type":"boolean"},"backupsEnabled":{"description":"Whether the branch is in a region that supports backups","type":"boolean"}},"required":["id","name","createdAt","updatedAt","region","publicAccess","backupsEnabled"]},"BranchMetadata":{"description":"Detailed metadata about a branch, including its status and configuration","type":"object","properties":{"id":{"description":"Unique identifier for the branch","type":"string"},"name":{"description":"Human-readable name of the branch","type":"string"},"description":{"description":"Optional description of the branch purpose or contents","type":"string"},"createdAt":{"description":"Timestamp when the branch was created","type":"string","format":"date-time"},"updatedAt":{"description":"Timestamp when the branch was last updated","type":"string","format":"date-time"},"parentID":{"description":"Identifier of the parent branch if this is a derived branch, null otherwise","type":"string","nullable":true},"region":{"description":"Geographic region where the branch is deployed","type":"string"},"status":{"$ref":"#/components/schemas/BranchStatus"},"connectionString":{"description":"Database connection string for accessing this branch","type":"string","nullable":true},"publicAccess":{"description":"Whether the branch allows public access without authentication","type":"boolean"},"backupsEnabled":{"description":"Whether the branch is in a region that supports backups","type":"boolean"},"scaleToZero":{"$ref":"#/components/schemas/ScaleToZeroConfiguration"},"configuration":{"$ref":"#/components/schemas/ClusterConfiguration"},"backupConfiguration":{"$ref":"#/components/schemas/BackupConfiguration"}},"required":["id","name","createdAt","updatedAt","region","status","connectionString","configuration","publicAccess","backupsEnabled","scaleToZero"]},"BackupMetadata":{"description":"metadata about a continuous backup","type":"object","properties":{"id":{"description":"unique identifier for the backup","type":"string"},"branchID":{"description":"the branchID the branch associated with the backup","type":"string"},"earliestRestore":{"description":"the earlies point in time available for restoring the branch","type":"string","format":"date-time"},"latestRestore":{"description":"the latest point in time available for restoring the branch","type":"string","format":"date-time"},"description":{"description":"description of the backup","type":"string"}},"required":["id","branchID","description"]},"BranchCredentials":{"description":"Credentials for accessing a branch, username and password","type":"object","properties":{"username":{"description":"Username for accessing the branch database","type":"string"},"password":{"description":"Password for accessing the branch database","type":"string"}},"required":["username","password"],"x-internal":true},"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)","type":"integer","format":"int32","maximum":250},"instanceType":{"description":"New instance type for the branch","type":"string"},"backupConfiguration":{"$ref":"#/components/schemas/BackupConfiguration"},"hibernate":{"description":"Enabled when the branch should be hibernated, disabled if it needs to be reactivated.","type":"boolean"},"scaleToZero":{"$ref":"#/components/schemas/ScaleToZeroConfiguration"},"postgresConfigurationParameters":{"description":"Arbitrary PostgreSQL configuration parameters for the cluster","type":"object","additionalProperties":{"type":"string"}},"preloadLibraries":{"description":"List of PostgreSQL extensions and libraries to preload","type":"array","items":{"type":"string"}},"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"}},"required":["maxDescriptionLength","maxBranchesPerProject","maxInstancesPerBranch","minInstancesPerBranch","maxAllowedInstanceType","maxBranchesPerHour"]},"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":"Projects API","tags":["Projects Webhooks","Projects","Branches","GitHub App","Metrics","Logs"]}]}