openapi: 3.0.1
info:
  title: Literal AI API
  description: >-
    HTTP transport model for the Literal AI observability, evaluation, and
    analytics platform. The Literal AI API is GraphQL: a single POST endpoint
    at /api/graphql accepts a GraphQL query/mutation document and variables.
    This OpenAPI document models that single endpoint so the GraphQL surface is
    discoverable in REST tooling; the full type system lives in
    graphql/literalai-schema.graphql. Authentication uses the x-api-key header.
  termsOfService: https://www.literalai.com/terms
  contact:
    name: Literal AI Support
    url: https://docs.literalai.com
  version: '1.0'
servers:
  - url: https://cloud.getliteral.ai
    description: Literal AI Cloud
  - url: '{baseUrl}'
    description: Self-hosted Literal AI deployment
    variables:
      baseUrl:
        default: https://cloud.getliteral.ai
        description: LITERAL_API_URL for self-hosted / enterprise installs.
security:
  - ApiKeyAuth: []
paths:
  /api/graphql:
    post:
      operationId: graphql
      tags:
        - GraphQL
      summary: Execute a GraphQL query or mutation.
      description: >-
        Single GraphQL endpoint for all Literal AI operations - threads, steps,
        generations, datasets, experiments, prompts, and scores. The request
        body carries a GraphQL document and an optional variables object;
        responses follow the standard GraphQL { data, errors } envelope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              getThread:
                summary: Fetch a thread with steps
                value:
                  query: >-
                    query GetThread($id: String!) { thread(id: $id) { id name
                    steps { id type input output } } }
                  variables:
                    id: thread_123
              createScore:
                summary: Attach a score to a step
                value:
                  query: >-
                    mutation CreateScore($name: String!, $type: ScoreType!,
                    $value: Float!, $stepId: String) { createScore(name: $name,
                    type: $type, value: $value, stepId: $stepId) { id value } }
                  variables:
                    name: relevance
                    type: HUMAN
                    value: 1
                    stepId: step_456
      responses:
        '200':
          description: >-
            GraphQL response. HTTP 200 is returned even for GraphQL-level
            errors, which appear in the errors array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid x-api-key.
        '429':
          description: Rate limit / log-unit quota exceeded.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key from the Literal AI dashboard, supplied via the
        LITERAL_API_KEY environment variable in the SDKs.
  schemas:
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation document.
        operationName:
          type: string
          description: Name of the operation to run when the document defines several.
        variables:
          type: object
          additionalProperties: true
          description: Variables referenced by the GraphQL document.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
          additionalProperties: true
          description: Result payload keyed by the requested fields.
        errors:
          type: array
          description: GraphQL execution errors, when present.
          items:
            $ref: '#/components/schemas/GraphQLError'
    GraphQLError:
      type: object
      properties:
        message:
          type: string
        path:
          type: array
          items:
            type: string
        locations:
          type: array
          items:
            type: object
            properties:
              line:
                type: integer
              column:
                type: integer
        extensions:
          type: object
          additionalProperties: true