Literal AI GraphQL API

openapi: 3.0.1
info:
  title: Literal AI GraphQL 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: []
tags:
- name: GraphQL
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:
  schemas:
    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'
    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.
    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
  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.