OpenAPI Specification
openapi: 3.0.0
info:
title: Xata API Keys Logs API
description: Xata API
version: '1.0'
contact:
name: help@xata.io
servers:
- url: https://api.xata.tech
description: Xata API
tags:
- name: Logs
description: Operations for retrieving log entries for a branch
x-displayName: Logs
paths:
/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:
- Logs
components:
schemas:
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
LogLevel:
description: Log level enumeration
type: string
enum:
- debug
- info
- warning
- error
OrganizationID:
title: OrganizationID
type: string
pattern: '[a-zA-Z0-9_-~:]+'
x-oapi-codegen-extra-tags:
validate: identifier
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
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
responses:
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
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