openapi: 3.0.0
info:
  title: Xata API Keys Gateway API
  description: Xata API
  version: '1.0'
  contact:
    name: help@xata.io
servers:
- url: https://api.xata.tech
  description: Xata API
tags:
- name: Gateway
  description: PostgreSQL connectivity via HTTP SQL, WebSocket wire protocol proxy, and native wire protocol.
  x-displayName: Gateway
paths:
  /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.


        **Authentication:** send the branch''s PostgreSQL connection string in the

        `Connection-String` header. The control-plane API key (Bearer token) is

        **not** accepted on the gateway host.


        **Routing:** the target branch, region, and endpoint type are taken from the

        hostname embedded in the connection string, which must match the request host.

        See the `Connection-String` security scheme for the host format.


        **Single query:** provide `query` (and optional `params`) at the top level.


        **Batch:** provide `queries` as an array of query objects, or send the request body

        as a JSON array. Batch queries execute within a single transaction.

        '
      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.

        The client sends and receives PostgreSQL protocol messages over binary WebSocket frames.


        **Authentication:** the same branch connection string credential as the

        HTTP SQL endpoint is used, but it is supplied via the PostgreSQL startup

        message inside the wire protocol rather than an HTTP header. The

        control-plane API key (Bearer token) is not accepted.

        '
      responses:
        '101':
          description: Switching Protocols — WebSocket connection established
        '400':
          description: Bad request — unable to upgrade connection
      tags:
      - Gateway
components:
  schemas:
    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
    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
    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
    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
    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
    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
  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 <api_key>'
    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.
externalDocs:
  url: https://xata.io/docs/api
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