> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List a test's revisions

> Every revision of a test, newest first, each as a spec. An attempt names the revision it ran (`testRevision`).



## OpenAPI

````yaml /api-reference/openapi.json get /v1/agents/{agentId}/tests/{testId}/revisions
openapi: 3.1.0
info:
  title: Signal API
  version: 1.0.0
  description: >-
    Signal reads a voice agent's production calls and says what to fix, then
    tests whether the fix worked.

    This API exposes the same data the web app shows: agents, calls and their
    traces, signals, issues,

    versions and their comparisons, tests, and test runs.


    Authenticate with `Authorization: Bearer sig_...` (an API key from the API
    keys page). Read keys may

    call every `read` operation; write keys may also call `write` operations,
    within their monthly budget.

    Each operation's scope is in `x-signal-scope`. Errors share one envelope
    (`Error`), lists share one

    cursor scheme (`limit`, `cursor`, `hasMore`, `nextCursor`), and every
    response carries `Request-Id`

    and `RateLimit-*` headers.
servers:
  - url: https://first-signal-api.fly.dev
    description: Production
  - url: http://localhost:43124
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Who the token belongs to and what it may do.
  - name: Agents
    description: Voice agents connected to the workspace.
  - name: Calls
    description: Production calls, their traces and per-call signals.
  - name: Signals
    description: What Signal noticed across calls.
  - name: Issues
    description: 'Problems worth fixing: where, why, and what to change.'
  - name: Versions
    description: Agent versions and how each one did.
  - name: Comparisons
    description: Stored comparisons between two versions.
  - name: Tests
    description: Tests, test sets, personas and coverage.
  - name: Runs
    description: Test runs and the attempts inside them.
paths:
  /v1/agents/{agentId}/tests/{testId}/revisions:
    get:
      tags:
        - Tests
      summary: List a test's revisions
      description: >-
        Every revision of a test, newest first, each as a spec. An attempt names
        the revision it ran (`testRevision`).
      operationId: listTestRevisions
      parameters:
        - schema:
            type: string
            format: uuid
            pattern: >-
              ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
            example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
            description: The agent's id.
          required: true
          description: The agent's id.
          name: agentId
          in: path
        - schema:
            type: string
            format: uuid
            pattern: >-
              ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
            example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
            description: The test's id.
          required: true
          description: The test's id.
          name: testId
          in: path
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
            description: Items per page, 1 to 100.
            example: 25
          required: false
          description: Items per page, 1 to 100.
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            description: '`nextCursor` from the previous page.'
          required: false
          description: '`nextCursor` from the previous page.'
          name: cursor
          in: query
      responses:
        '200':
          description: A page of revisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestRevisionList'
        '400':
          description: 'Invalid request: a parameter or the body failed validation.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or revoked credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not permitted for this principal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            The agent, or a resource under it, does not exist or is not visible
            to this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited. See Retry-After.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error. The message is generic; quote the request id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: bash
          label: curl
          source: >-
            curl
            "https://first-signal-api.fly.dev/v1/agents/6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b/tests/3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f/revisions"
            \
              -H "Authorization: Bearer $SIGNAL_API_KEY"
components:
  schemas:
    TestRevisionList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/TestRevision'
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - 'null'
          description: Pass as `cursor` for the next page; null on the last page.
      required:
        - object
        - data
        - hasMore
        - nextCursor
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/ErrorType'
            code:
              type: string
              example: agent_not_found
              description: The specific reason; stable within v1.
            message:
              type: string
              example: Agent not found.
            param:
              type:
                - string
                - 'null'
              description: The request field at fault, for a validation error.
            requestId:
              type:
                - string
                - 'null'
              example: req_8c1f0e2b4a6d9e3f7a5c1b0d
            quota:
              type: object
              properties:
                metric:
                  type: string
                  example: test_calls
                  description: analysed_calls, agents, copilot_messages or test_calls.
                limit:
                  type: integer
                used:
                  type: integer
                plan:
                  type: string
                  example: free_org
                  description: The workspace's plan slug.
                upgradePath:
                  type: string
                  example: /billing
                  description: Where in the web app the plan is changed.
              required:
                - metric
                - limit
                - used
                - plan
                - upgradePath
              description: >-
                Present when code is quota_exceeded: the plan limit the request
                would pass.
          required:
            - type
            - code
            - message
            - param
            - requestId
      required:
        - error
      example:
        error:
          type: not_found_error
          code: agent_not_found
          message: Agent not found.
          param: null
          requestId: req_8c1f0e2b4a6d9e3f7a5c1b0d
    TestRevision:
      type: object
      properties:
        object:
          type: string
          enum:
            - test_revision
        testId:
          type: string
          format: uuid
          pattern: >-
            ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
        revision:
          type: integer
        createdBy:
          type:
            - string
            - 'null'
          description: 'Who made it: a user id, or key:<id> for an API key.'
        createdAt:
          type: string
          format: date-time
          example: '2026-10-02T14:03:07.120Z'
        spec:
          $ref: '#/components/schemas/TestSpec'
      required:
        - object
        - testId
        - revision
        - createdBy
        - createdAt
        - spec
    ErrorType:
      type: string
      enum:
        - invalid_request_error
        - authentication_error
        - budget_error
        - permission_error
        - not_found_error
        - conflict_error
        - rate_limit_error
        - api_error
    TestSpec:
      type: object
      properties:
        specVersion:
          type: number
          enum:
            - 1
        testId:
          type: string
          format: uuid
          pattern: >-
            ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
          description: Output only.
        revision:
          type: integer
          description: Output only.
        source:
          type: object
          properties:
            kind:
              type: string
              enum:
                - production
                - custom
                - probe
              description: >-
                production: a stored call replayed. custom: written as a spec.
                probe: written for a brief line no call exercises; never gates.
            basedOnTestId:
              type:
                - string
                - 'null'
              format: uuid
              pattern: >-
                ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
              example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
              description: >-
                The test whose start, masking map and issue criterion this one
                borrows.
            basedOnCallId:
              type:
                - string
                - 'null'
              format: uuid
              pattern: >-
                ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
              example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f
              description: The stored call it is based on.
            briefLine:
              type:
                - object
                - 'null'
              properties:
                section:
                  type: string
                  enum:
                    - out_of_scope
                    - guardrails
                    - intent
                key:
                  type: string
                text:
                  type: string
              required:
                - section
                - key
                - text
              description: A probe's brief line.
            generated:
              type:
                - object
                - 'null'
              properties:
                generationId:
                  type: string
                kind:
                  type: string
                  enum:
                    - from_call
                    - written
                cell:
                  type: string
              required:
                - generationId
                - kind
                - cell
              description: Set when a test generation made it. Never read from input.
          required:
            - kind
            - basedOnTestId
            - basedOnCallId
        intentSlug:
          type:
            - string
            - 'null'
        lane:
          type:
            - string
            - 'null'
          enum:
            - hearing
            - understanding
            - flow
            - speaking
            - integrations
            - null
          description: >-
            The lane a defect lives in: hearing, understanding, flow, speaking
            or integrations.
        tier:
          type: string
          enum:
            - text
            - phone
        start:
          type: object
          properties:
            direction:
              type: string
              enum:
                - inbound
                - outbound
            agentSpeaksFirst:
              type:
                - boolean
                - 'null'
            variables:
              type: object
              additionalProperties:
                type: string
              description: Dynamic variables the call starts with, personal values masked.
            metadata:
              type: object
              additionalProperties: {}
          required:
            - direction
            - agentSpeaksFirst
            - variables
            - metadata
        caller:
          type: object
          properties:
            persona:
              type: string
              description: >-
                A persona slug from GET .../personas, or @source for the source
                call's own caller.
            goal:
              type: string
            lines:
              type:
                - array
                - 'null'
              items:
                type: string
              description: >-
                What the caller says. Null: the source call's own lines, read at
                run time.
            behaviours:
              type:
                - array
                - 'null'
              items:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                      - refuses
                      - asks_for_person
                      - off_topic
                      - repeats
                      - short_answers
                      - silent_after_question
                      - profile
                  atLine:
                    type:
                      - integer
                      - 'null'
                    description: 1-based caller line; null for the whole call.
                  detail:
                    type: string
                required:
                  - kind
                  - atLine
                  - detail
              description: 'Scripted caller behaviour. Null: the source call''s own.'
          required:
            - persona
            - goal
            - lines
            - behaviours
        fixtures:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/TestSpecFixture'
          description: Tool name to its mocked answers.
        criteria:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Stable across revisions.
              ref:
                type: string
                description: A brief reference, goal or issue. Exactly one of ref and text.
              text:
                type: string
              polarity:
                type: string
                enum:
                  - must
                  - must_not
              decidedBy:
                type: string
                enum:
                  - detector
                  - judge
                  - unmeasured
                description: >-
                  What decides the criterion: a check on the transcript and tool
                  calls, a reading of the conversation, or nothing a text run
                  can measure.
            required:
              - id
              - decidedBy
        expect:
          type: string
          enum:
            - pass
            - fail
        guard:
          type: boolean
        sets:
          type: array
          items:
            type: string
          description: Names of test sets it belongs to.
        tags:
          type: array
          items:
            type: string
        title:
          type:
            - string
            - 'null'
      required:
        - specVersion
        - source
        - intentSlug
        - lane
        - tier
        - start
        - caller
        - fixtures
        - criteria
        - expect
        - guard
        - sets
        - tags
      description: >-
        A test as a JSON document: who calls, what each tool answers, and what
        must hold. GET .../tests/schema has its JSON Schema; POST
        .../tests/validate checks one.
    TestSpecFixture:
      type: object
      properties:
        args:
          description: >-
            The arguments this answer is for. Absent or null: the answer for any
            arguments no other entry matches.
        response:
          description: What the tool returns.
        success:
          type: boolean
          description: Whether the tool call succeeds. Default true.
        provenance:
          type: object
          properties:
            from:
              type: string
              enum:
                - source_call
                - other_call
                - owner
            callId:
              type: string
          required:
            - from
          description: 'Read only: where the answer came from. Ignored on input.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`sig_...`), or a session token from the web app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.