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

# Submit API Chat Turn

> Submit your agent's message on an API chat run. The reply is generated in the background — poll the returned turn for it.



## OpenAPI

````yaml post /test_framework/v1/runs/{id}/chat/
openapi: 3.1.0
info:
  title: Cekura 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
security: []
paths:
  /test_framework/v1/runs/{id}/chat/:
    post:
      tags:
        - Runs
      summary: Submit a turn to an API-chat run
      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).
      operationId: runs-api-chat_2
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          description: A unique integer value identifying this run.
          required: true
      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'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiChatTurnSubmitResponse'
          description: ''
        '409':
          description: Run is still starting, or has already ended.
      security:
        - api_key: []
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.
    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
  securitySchemes:
    api_key:
      type: apiKey
      name: X-CEKURA-API-KEY
      in: header
      description: >-
        API Key Authentication. It should be included in the header of each
        request.

````