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

# Call Agent

> Send a request to an agent and get their response

Call an agent to get a response to your request.

### Endpoint

```bash
POST /call/{agent_id}
```

### Parameters

<ParamField path="agent_id" type="string" required>
  ID of the agent to call
</ParamField>

### Request Body

<ParamField body="request" type="string" required>
  The prompt or request to send to the agent
</ParamField>

<ParamField body="conversation_id" type="string">
  Optional conversation ID for continuing an existing conversation
</ParamField>

### Response

<ResponseField name="thread_id" type="string" required>
  Unique identifier for this interaction thread
</ResponseField>

<ResponseField name="conversation_id" type="string" required>
  Identifier for the conversation
</ResponseField>

<ResponseField name="agent_id" type="string" required>
  ID of the agent that was called
</ResponseField>

<ResponseField name="success" type="boolean" required>
  Whether the call was successful
</ResponseField>

<ResponseField name="response" type="string" required>
  The agent's response text
</ResponseField>

<ResponseField name="function_result" type="object">
  Optional structured data returned by the agent, null if no structured data
</ResponseField>

```json
{
  "thread_id": "50cc9455b84d48ffad6b4c9fd41b561e",
  "conversation_id": "bc8e506e4a6f49ad",
  "agent_id": "2ec10f28abac4e01",
  "success": true,
  "response": "I am a greeting assistant designed to help with welcoming users...",
  "function_result": null
}
```


## OpenAPI

````yaml POST /call/{agent_id}
openapi: 3.0.0
info:
  title: Headless Agents API
  description: >-
    The Headless Agents API allows you to interact with AI agents
    programmatically. 

    This API provides endpoints for health checking, calling agents, and
    retrieving agent statistics.


    ## Authentication

    All API requests (except /health) require authentication using your Headless
    Agents API key provided as an `X-API-Key` header.


    Example:

    ```bash

    curl -H "X-API-Key: your_api_key"
    https://api.headlessagents.ai/call/your_agent_id

    ```
  version: 1.0.0
  contact:
    name: Headless Agents Support
    url: https://headlessagents.ai
    email: support@headlessagents.ai
servers:
  - url: https://api.headlessagents.ai
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: Health check endpoints
  - name: Agents
    description: Endpoints for interacting with agents
paths:
  /call/{agent_id}:
    post:
      tags:
        - Agents
      summary: Call an agent
      description: Send a request to an agent and get their response
      operationId: callAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
          description: ID of the agent to call
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCallRequest'
            example:
              request: What is the weather like in San Francisco?
              conversation_id: bc8e506e4a6f49ad
      responses:
        '200':
          description: Successful response from agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCallResponse'
              example:
                thread_id: 50cc9455b84d48ffad6b4c9fd41b561e
                conversation_id: bc8e506e4a6f49ad
                agent_id: 2ec10f28abac4e01
                success: true
                response: Hi there! How can I help you today?
                function_result: null
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AgentCallRequest:
      type: object
      properties:
        request:
          type: string
          description: The prompt or request to send to the agent
        conversation_id:
          type: string
          description: Optional conversation ID for continuing an existing conversation
      required:
        - request
    AgentCallResponse:
      type: object
      properties:
        thread_id:
          type: string
          description: Unique identifier for this interaction thread
        conversation_id:
          type: string
          description: Identifier for the conversation
        agent_id:
          type: string
          description: ID of the agent that was called
        success:
          type: boolean
          description: Whether the call was successful
        response:
          type: string
          description: The agent's response text
        function_result:
          type: object
          description: >-
            Optional structured data returned by the agent, null if no
            structured data
          nullable: true
          additionalProperties: true
      required:
        - thread_id
        - conversation_id
        - agent_id
        - success
        - response
        - function_result
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message detailing what went wrong
      required:
        - detail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key provided by Headless Agents

````