openapi: 3.0.1
info:
  title: Agenta Applications Testsets API
  description: Agenta is an open-source LLMOps platform for prompt management, LLM evaluation, and LLM observability. This specification documents the public cloud REST API surface used to manage applications and variants, fetch and deploy versioned prompt configurations, run evaluations and configure evaluators, manage testsets, and ingest and query observability traces. All endpoints are authenticated with an Agenta API key passed in the Authorization header. Agenta is MIT licensed and may also be self-hosted.
  termsOfService: https://agenta.ai/terms
  contact:
    name: Agenta Support
    url: https://agenta.ai/
    email: team@agenta.ai
  license:
    name: MIT
    url: https://github.com/Agenta-AI/agenta/blob/main/LICENSE
  version: '1.0'
servers:
- url: https://cloud.agenta.ai/api
  description: Agenta Cloud (US)
- url: https://eu.cloud.agenta.ai/api
  description: Agenta Cloud (EU)
security:
- ApiKeyAuth: []
tags:
- name: Testsets
  description: Manage evaluation datasets (testsets).
paths:
  /testsets/:
    post:
      operationId: createTestset
      tags:
      - Testsets
      summary: Create a testset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestsetCreateRequest'
      responses:
        '200':
          description: The created testset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Testset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /testsets/query:
    post:
      operationId: queryTestsets
      tags:
      - Testsets
      summary: List and filter testsets.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestsetQueryRequest'
      responses:
        '200':
          description: A list of testsets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Testset'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /testsets/{testset_id}:
    get:
      operationId: fetchTestset
      tags:
      - Testsets
      summary: Fetch a single testset by id.
      parameters:
      - name: testset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested testset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Testset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /simple/testsets/upload:
    post:
      operationId: createTestsetFromFile
      tags:
      - Testsets
      summary: Create a testset from an uploaded CSV or JSON file.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                name:
                  type: string
      responses:
        '200':
          description: The created testset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Testset'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Testset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        data:
          type: object
          properties:
            testcases:
              type: array
              items:
                type: object
                additionalProperties: true
        lifecycle:
          $ref: '#/components/schemas/Lifecycle'
    Lifecycle:
      type: object
      description: Audit metadata attached to most Agenta resources.
      properties:
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by_id:
          type: string
          format: uuid
        updated_by_id:
          type: string
          format: uuid
    TestsetCreateRequest:
      type: object
      required:
      - testset
      properties:
        testset:
          type: object
          required:
          - slug
          properties:
            slug:
              type: string
            name:
              type: string
            data:
              type: object
              properties:
                testcases:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
    TestsetQueryRequest:
      type: object
      properties:
        include_archived:
          type: boolean
          default: false
        windowing:
          $ref: '#/components/schemas/Windowing'
    Windowing:
      type: object
      description: Cursor / time-window pagination controls.
      properties:
        next:
          type: string
        limit:
          type: integer
          default: 100
        oldest:
          type: string
          format: date-time
        newest:
          type: string
          format: date-time
        order:
          type: string
          enum:
          - ascending
          - descending
    Error:
      type: object
      properties:
        detail:
          oneOf:
          - type: string
          - type: object
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Agenta API key sent in the Authorization header. Generate keys from the Agenta web app under Settings > API keys. The value is passed as `Authorization: ApiKey <key>` (Bearer-style header credential).'