Cekura Runs API

openapi: 3.2.0
info:
  title: Cekura Runs API
  version: v1
  description: Complete API documentation for the Cekura platform. This API provides endpoints for testing, observing, and evaluating AI voice agents — including managing agents, running evaluators, defining metrics, and analyzing call quality.
servers:
- url: https://api.cekura.ai
tags:
- name: Runs
paths:
  /test_framework/v1/runs/{id}/chat/:
    post:
      operationId: runs-api-chat_2
      description: 'Submit your agent-under-test''s latest message on a customer-driven (API chat) run. The simulated user''s reply is generated in the background — the response returns a `turn_id` immediately; poll GET /runs/{run_id}/chat/{turn_id}/ until its `status` is `ready` to read the reply, then submit the next turn. Submitting a new turn while one is still generating interrupts it: the older turn is marked `dropped` but its message is kept, and the newest turn''s reply answers all messages received since the last reply. Repeat until `ended` is true (or call end-chat).'
      summary: Submit a turn to an API-chat run
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiChatTurn'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ApiChatTurn'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ApiChatTurn'
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiChatTurnSubmitResponse'
          description: ''
        '409':
          description: Run is still starting, or has already ended.
  /test_framework/v1/runs/{id}/chat/{turn_id}/:
    get:
      operationId: runs-api-chat-turn_2
      description: 'Poll for the simulated user''s reply to a turn submitted via POST /runs/{run_id}/chat/. `status` is `generating` until the reply is ready, then `ready` (with `message` and `ended`). `dropped` means the turn was superseded by a newer submission — its message is kept and the newer turn''s reply answers both; `error` means generation failed. Turn 0 is the run''s opening: `message` is the evaluator''s first message, or null when your agent speaks first. Any turn stays pollable until the run''s turn history expires, so the last reply is still retrievable after the run finishes.'
      summary: Poll a submitted API-chat turn
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      - in: path
        name: turn_id
        schema:
          type: string
          pattern: ^[0-9]+$
        required: true
      tags:
      - Runs
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiChatTurnPollResponse'
          description: ''
        '404':
          description: Unknown turn.
  /test_framework/v1/runs/{id}/end-chat/:
    post:
      operationId: runs-api-chat-end_2
      summary: Finish an API-chat run
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiChatFinish'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ApiChatFinish'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ApiChatFinish'
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiChatFinishResponse'
          description: ''
  /test_framework/v1/runs/{id}/end_call/:
    post:
      operationId: end-call_2
      summary: End a single call
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
      x-mcp-tool-name: end_call
  /test_framework/v1/runs/{id}/mark_metric_vote/:
    post:
      operationId: runs-mark-metric-vote-create_2
      description: Record a thumbs-up or thumbs-down vote on a specific metric evaluation for this run and optionally provide an expected value and free-text feedback. Updates the metric evaluation and marks the run as reviewed.
      summary: Submit a metric vote for a run
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
        required: true
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkMetricVoteRunResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  field_name:
                    type: array
                    items:
                      type: string
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
      x-mcp-tool-name: runs_mark_metric_vote_create
  /test_framework/v2/runs/{id}/end_call/:
    post:
      operationId: end-call_3
      summary: End a single call
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
      x-mcp-expose: true
      x-mcp-tool-name: end_call
      x-mint:
        mcp:
          enabled: true
          name: end-call
          description: End a single call
  /test_framework/v2/runs/{id}/mark_metric_vote/:
    post:
      operationId: runs-mark-metric-vote-create_3
      description: Record a thumbs-up or thumbs-down vote on a specific metric evaluation for this run and optionally provide an expected value and free-text feedback. Updates the metric evaluation and marks the run as reviewed.
      summary: Submit a metric vote for a run
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this run.
        required: true
      tags:
      - Runs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkMetricVote'
        required: true
      security:
      - api_key: []
      - oauth2: []
      - embedded_session: []
      - shareable_link: []
      - supabase_session: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkMetricVoteRunResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  field_name:
                    type: array
                    items:
                      type: string
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
      x-mcp-expose: true
      x-mcp-tool-name: runs_mark_metric_vote_create
      x-mint:
        mcp:
          enabled: true
          name: runs-mark-metric-vote-create
          description: Record a thumbs-up or thumbs-down vote on a specific metric evaluation for this run and optionally provide an expected value and free-text feedback. Updates the metric evaluation and marks the run as reviewed.
components:
  schemas:
    ApiChatTurn:
      type: object
      description: 'Request body for POST /runs/{run_id}/chat/ (submit one turn). Same message shape

        as the websocket chat integration: a normal message (`content`), optional `metadata`

        merged into the run, and/or a function call (`role` + `data`).'
      properties:
        content:
          type: string
          description: Your agent-under-test's latest message. Submitting it returns a `turn_id`; poll GET /runs/{run_id}/chat/{turn_id}/ for the simulated user's reply.
        metadata:
          type: object
          additionalProperties: {}
          description: Optional metadata merged into the run (last-write-wins). Can be sent alone.
        role:
          enum:
          - Function Call
          - Function Call Result
          type: string
          x-spec-enum-id: 96979c0bc176b860
          description: 'Set to record a tool call instead of a message (no reply is generated).


            * `Function Call` - Function Call

            * `Function Call Result` - Function Call Result'
        data:
          type: object
          additionalProperties: {}
          description: 'Function-call payload: {id, name, arguments} for a call, {id, result} for a result.'
    MarkMetricVote:
      type: object
      properties:
        metric_id:
          type: integer
          description: ID of the metric to vote on
        thumbs_up:
          type:
          - boolean
          - 'null'
          description: True for thumbs up, False for thumbs down
        expected_value:
          oneOf:
          - {}
          - type: 'null'
          description: Expected value for the metric
        feedback:
          type:
          - string
          - 'null'
          description: Feedback for the metric review
      required:
      - expected_value
      - metric_id
      - thumbs_up
    ApiChatFinishResponse:
      type: object
      description: Response for POST /runs/{run_id}/end-chat/.
      properties:
        run_id:
          type: integer
        result_id:
          type: integer
        status:
          type: string
      required:
      - result_id
      - run_id
      - status
    ApiChatTurnPollResponse:
      type: object
      description: Response for GET /runs/{run_id}/chat/{turn_id}/ (poll for the reply).
      properties:
        run_id:
          type: integer
        result_id:
          type: integer
        turn_id:
          type: integer
        status:
          type: string
          description: '''generating'' until ready, then ''ready'' (or ''error'').'
        message:
          type:
          - string
          - 'null'
          description: The simulated user's reply; null until status is 'ready'.
        ended:
          type: boolean
          description: True when the conversation has ended.
        ended_reason:
          type:
          - string
          - 'null'
      required:
      - ended
      - ended_reason
      - message
      - result_id
      - run_id
      - status
      - turn_id
    ApiChatFinish:
      type: object
      description: Request body for POST /runs/{run_id}/end-chat/ (finish the chat).
      properties:
        reason:
          type: string
          description: Optional end reason, e.g. 'main_agent_ended_call'.
    ApiChatTurnSubmitResponse:
      type: object
      description: Response for POST /runs/{run_id}/chat/ (turn accepted).
      properties:
        run_id:
          type: integer
        result_id:
          type: integer
        turn_id:
          type: integer
          description: Poll this turn for the simulated user's reply.
        status:
          type: string
          description: Turn status; poll for the reply if 'generating'.
      required:
      - result_id
      - run_id
      - status
      - turn_id
    MarkMetricVoteRunResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-CEKURA-API-KEY
      description: API Key Authentication. It should be included in the header of each request.
    embedded_session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Embedded-dashboard session token. Internal.
    oauth2:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token issued by Cekura for connected apps.
    shareable_link:
      type: apiKey
      in: header
      name: X-VOCERA-SHAREABLE-LINK-TOKEN
      description: Share-link token scoped to a single shared resource.
    supabase_session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Cekura dashboard session token. Not a customer API credential.
x-mint:
  mcp:
    enabled: true