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

# Call with Prompt

> Create and trigger an AI phone call from a natural language prompt. Generates a workflow, initiates the call, and optionally delivers results to a callback URL.

## Overview

Create and trigger an AI phone call from a natural language prompt in a single request. The system generates a workflow from your prompt, initiates the call, and optionally delivers results to a callback URL.

This is ideal for agent-to-agent orchestration, where external agents can make calls without pre-creating workflows.

## Callback

If you provide a `callback_url`, the API will POST call results to that URL when the call completes **or fails** (including not picked up, busy, voicemail).

Callback delivery is best-effort (single attempt, 30-second timeout). For guaranteed delivery, poll the call status as a fallback.

### Callback payload

```json theme={null}
{
  "call_id": "abc-123",
  "workflow_id": "def-456",
  "call_status": "success",
  "provider_status": "completed",
  "call_summary": "Customer booked a reservation for Friday 7pm, party of 2.",
  "messages": [],
  "context": null,
  "form_fills": [],
  "created_at": "2026-03-30T12:00:00.000Z"
}
```

If you provided a `callback_secret`, the callback request includes an `Authorization: Bearer <your_secret>` header.

### Terminal statuses

| `call_status`   | `provider_status` | Meaning                                 |
| --------------- | ----------------- | --------------------------------------- |
| `success`       | `completed`       | Call completed normally                 |
| `not_picked_up` | `no-answer`       | No one answered                         |
| `not_picked_up` | `busy`            | Line was busy                           |
| `not_picked_up` | `failed`          | Call failed (bad number, carrier error) |
| `not_picked_up` | `canceled`        | Call was canceled                       |
| `voicemail`     | `completed`       | Went to voicemail                       |

## Idempotency

To prevent duplicate calls from retries, pass an optional `idempotency_key`. If the same key is sent within a 5-minute window, the API returns the cached response without creating a new call.

```json theme={null}
{
  "prompt": "Book a reservation at Friday 7pm for Josh for 2",
  "recipient_phone": "+14155552671",
  "idempotency_key": "agent-task-12345"
}
```


## OpenAPI

````yaml POST /call-prompt
openapi: 3.1.0
info:
  title: CallCow Workflow API
  description: API to trigger AI phone call workflows
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://www.callcow.ai/api
security:
  - bearerAuth: []
paths:
  /call-prompt:
    post:
      summary: Call with Prompt
      description: >-
        Create and trigger an AI phone call from a natural language prompt.
        Generates a workflow, initiates the call, and optionally delivers
        results to a callback URL.
      operationId: callWithPrompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallPromptRequest'
      responses:
        '200':
          description: Call successfully created and triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallPromptSuccess'
        '400':
          description: Validation failed (invalid phone, SSRF callback URL, missing prompt)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Workflow already used (single-use enforcement)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Workflow expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Could not generate workflow from prompt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded (60 requests/minute per organization)
          headers:
            Retry-After:
              description: Seconds until rate limit resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Failed to initiate call
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CallPromptRequest:
      type: object
      required:
        - prompt
        - recipient_phone
      properties:
        prompt:
          type: string
          description: >-
            Natural language description of the call task. The system generates
            an AI workflow from this prompt.
          example: Book a reservation at Friday 7pm for Josh for 2
        recipient_phone:
          type: string
          description: Phone number of the call recipient in E.164 format
          example: '+14155552671'
        callback_url:
          type: string
          format: uri
          description: >-
            HTTPS URL to receive call results when the call completes or fails.
            Must not point to private/reserved IP ranges.
          example: https://agent.example.com/results
        callback_secret:
          type: string
          description: >-
            Optional bearer token included in the Authorization header of
            callback requests
          example: my-secret-token
        idempotency_key:
          type: string
          description: >-
            Optional unique key to prevent duplicate calls on retries. Scoped to
            your organization with a 5-minute TTL.
          example: agent-task-12345
    CallPromptSuccess:
      type: object
      properties:
        success:
          type: boolean
          example: true
        workflow_id:
          type: string
          description: ID of the generated workflow
          example: b8f40b44-3b7a-425b-a2ae-1327471b0410
        call_id:
          type: string
          nullable: true
          description: ID of the initiated call, if available
          example: c9e50c55-4c8b-536c-b3bf-2438582c1521
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        details:
          type: object
          description: Zod validation error details
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key generated from Settings → API Keys. Format: `ck_live_...`'

````