Ryft Ingest API

openapi: 3.1.0
info:
  title: Ryft Ingest API
  version: '1.0'
  description: The Ryft Ingest API accepts query-execution data from any custom query engine so Ryft can build usage-based Apache Iceberg optimizations. Send query telemetry (SQL text, timing, state, context) as JSON, singly or in bulk. Authenticated with a per-environment ingest token.
  contact:
    name: Ryft Support
    email: support@ryft.io
    url: https://docs.ryft.io/integrations/custom-engine
servers:
- url: https://ingest.ryft.io
  description: Ryft ingest endpoint (HTTPS, port 443)
security:
- RyftIngestToken: []
tags:
- name: Ingest
  description: Push query-execution telemetry to Ryft.
paths:
  /ingest/push/queries:
    post:
      tags:
      - Ingest
      operationId: pushQueries
      summary: Push query data
      description: Send one query object, or a JSON array of query objects for bulk ingestion. A 200 response means the message was accepted and will be processed.
      security:
      - RyftIngestToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Query'
              - type: array
                items:
                  $ref: '#/components/schemas/Query'
            examples:
              single:
                summary: Single query
                value:
                  context:
                    catalog: iceberg
                    schema: gold
                    queryType: SELECT
                    user: my-service
                    userAgent: my-client
                  timestamp: '2026-03-10T12:00:00.000Z'
                  duration_ms: 100
                  query: SELECT * FROM gold.my_table
                  queryId: test-001
                  queryState: FINISHED
                  tags:
                  - source:my-engine
      responses:
        '200':
          description: Message accepted and queued for processing.
components:
  schemas:
    Query:
      type: object
      required:
      - context
      - query
      - queryId
      - queryState
      - timestamp
      - duration_ms
      properties:
        context:
          $ref: '#/components/schemas/QueryContext'
        query:
          type: string
          description: The SQL query text.
        queryId:
          type: string
          description: Unique query identifier.
        queryState:
          type: string
          description: Terminal query state.
          enum:
          - FINISHED
          - SUCCEEDED
          - FAILED
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of query execution.
        duration_ms:
          type: number
          description: Execution time in milliseconds.
        tags:
          type: array
          items:
            type: string
          description: Free-form labels for filtering in Query Explorer.
        failureInfo:
          description: Only needed for failed queries (queryState FAILED).
          oneOf:
          - $ref: '#/components/schemas/FailureInfo'
          - type: array
            items:
              $ref: '#/components/schemas/FailureInfo'
    FailureInfo:
      type: object
      properties:
        errorCode:
          type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - USER_ERROR
              - INTERNAL_ERROR
              - INSUFFICIENT_RESOURCES
              - EXTERNAL
            code:
              type: number
              description: Numeric error code (free-form).
            name:
              type: string
              description: Error name (free-form).
        failureMessage:
          type: string
          description: Human-readable error description.
        failureType:
          type: string
          description: Exception or error class name.
    QueryContext:
      type: object
      description: Query environment context. All fields optional; pass {} if none.
      properties:
        catalog:
          type: string
          description: Catalog name (e.g. iceberg).
        schema:
          type: string
          description: Default namespace for unqualified table names.
        queryType:
          type: string
          enum:
          - SELECT
          - EXPLAIN
          - DESCRIBE
          - INSERT
          - UPDATE
          - DELETE
          - ANALYZE
          - DATA_DEFINITION
          - ALTER_TABLE_EXECUTE
          - MERGE
        serverVersion:
          type: string
          description: Query engine version.
        user:
          type: string
          description: User or service account that ran the query.
        userAgent:
          type: string
          description: Client identifier.
  securitySchemes:
    RyftIngestToken:
      type: apiKey
      in: header
      name: X-Ryft-Token
      description: Per-environment ingest token supplied by Ryft. Required to authenticate requests to the Ingest API.