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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Create Call



## OpenAPI

````yaml POST /api/v1/agents/{id}/call
openapi: 3.1.0
info:
  title: LangWatch API
  description: LangWatch openapi spec
  version: 1.0.0
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/v1/agents/{id}/call:
    post:
      summary: Send one conversation turn to an online connected agent
      operationId: callConnectedAgent
      parameters:
        - in: path
          name: id
          schema:
            type: string
            minLength: 1
          required: true
          description: The agent id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        minLength: 1
                    required:
                      - role
                    additionalProperties: {}
                  description: The whole conversation so far, OpenAI style.
                newMessages:
                  description: >-
                    The messages added since the agent's last turn. Defaults to
                    the last message.
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        minLength: 1
                    required:
                      - role
                    additionalProperties: {}
                threadId:
                  description: >-
                    The conversation id. Turns of one conversation share it; a
                    new id starts a new one.
                  type: string
                  maxLength: 255
                params:
                  description: Run parameter values by name, as JSON scalars.
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                  additionalProperties:
                    type:
                      - string
                      - number
                      - boolean
                session:
                  description: >-
                    The session the agent returned on its previous turn of this
                    conversation, echoed back as is.
                traceparent:
                  description: >-
                    The W3C trace context the agent adopts, so its spans join
                    this turn's trace.
                  type: string
                  maxLength: 255
                run:
                  description: The simulation run this turn belongs to, if any.
                  type: object
                  properties:
                    scenarioRunId:
                      type: string
                    scenarioName:
                      type: string
                    batchRunId:
                      type: string
                kind:
                  description: >-
                    A turn, or a scenario run's setup or teardown hook. Defaults
                    to a turn.
                  type: string
                  enum:
                    - turn
                    - setup
                    - teardown
                state:
                  description: >-
                    The scenario run's test data: what setup returned, or a
                    turn's latest update.
                  anyOf:
                    - type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                    - type: 'null'
                timeoutMs:
                  description: >-
                    A setup or teardown hook's budget in milliseconds. A turn
                    runs under the agent's own timeout.
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 300000
              required:
                - messages
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    anyOf:
                      - type: string
                      - type: object
                        properties:
                          role:
                            type: string
                            minLength: 1
                        required:
                          - role
                        additionalProperties: {}
                      - type: array
                        items:
                          type: object
                          properties:
                            role:
                              type: string
                              minLength: 1
                          required:
                            - role
                          additionalProperties: {}
                    description: >-
                      What the function answered: text, one message, or a list
                      of messages.
                  session:
                    description: >-
                      The agent's per-conversation memory, to send on the next
                      turn.
                  state:
                    description: >-
                      Setup's state, a turn's state update, or the object
                      teardown returned.
                    anyOf:
                      - type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      - type: 'null'
                  instance:
                    type: object
                    properties:
                      hostname:
                        type: string
                      label:
                        type:
                          - string
                          - 'null'
                    required:
                      - hostname
                      - label
                    additionalProperties: false
                  durationMs:
                    type: number
                required:
                  - output
                  - instance
                  - durationMs
                additionalProperties: false
      security:
        - project_api_key: []
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.

````

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