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

# API Overview

> Understand response envelopes, auth boundaries, and generated-versus-handwritten contract ownership in the public API docs.

# Build against contracts that are explicit about ownership.

Callaro API responses follow stable envelope conventions so your integration can process list, detail, and mutation responses consistently. This section combines:

* generated path contracts from `openapi.yaml`
* handwritten workflow guides for implementation patterns and operational handling

<CardGroup cols={3}>
  <Card title="OpenAPI endpoints" icon="sparkles">Use generated endpoint pages when you need request and response schema details.</Card>
  <Card title="Interactive testing" icon="flask-conical">Use the playground guidance page before enabling authenticated interactive requests.</Card>
  <Card title="Postman onboarding" icon="package">Use the Postman collection for fast request discovery and team-shared smoke tests.</Card>
</CardGroup>

## Best first steps

1. Review [`playground-access`](./playground-access) if you want browser-based testing.
2. Open [`../sdks/postman`](../sdks/postman) if you want downloadable request collections and environments.
3. Move into resource guides or generated endpoints once your auth model is chosen.

## Standard success envelope

<Snippet file="snippets/success-envelope.mdx" />

## Standard error envelope

<Snippet file="snippets/error-envelope.mdx" />

## Authentication headers

<Snippet file="snippets/auth-headers.mdx" />

## Known contract status

The current docs set intentionally distinguishes source-of-truth boundaries while backend OpenAPI coverage is being expanded.

<AccordionGroup>
  <Accordion title="Generated contract (authoritative for request/response schema)">
    * Endpoint operation signatures under generated API reference pages.
    * Response and parameter shape where present in `openapi.yaml`.
    * Security requirements attached to generated operations.
  </Accordion>

  <Accordion title="Handwritten contract notes (authoritative for operations guidance)">
    * Webhook receiver behavior (retries, idempotency, ordering guidance).
    * Scope planning and role-to-key decision guidance.
    * Cross-endpoint workflows (for example campaign launch to analytics pull).
  </Accordion>

  <Accordion title="Known temporary gap">
    Some backend route families exist in application routes and permission matrix but are still being fully represented in source `openapi.yaml`. Those families are documented in handwritten guides with explicit caveats until generated coverage catches up.
  </Accordion>
</AccordionGroup>

<Warning>
  Treat generated endpoint schemas as the first source for validation logic. Use handwritten guides for operational strategy, retries, and rollout safety.
</Warning>

## API shape at a glance

* Campaign execution is centered around `bulk_call_campaigns`.
* Number inventory and provisioning flow through `phone_numbers`.
* Contact lifecycle and compliance controls span contacts, segments, imports, exports, and DNC endpoints.
* Call logs and operational audit data are exposed through `voice_sessions`, trace endpoints, and export jobs.
* Partner-specific provisioning and multi-tenant actions live under partner route families.

## High-value workflow example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns" \
    -H "X-Api-Key: $CALLARO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"Workflow Example Campaign","agent_id":42,"timezone":"Asia/Kolkata","campaign_phone_number_ids":[101]}'

  curl -X POST "https://api.callaro.ai/api/v1/contacts/import" \
    -H "X-Api-Key: $CALLARO_API_KEY" \
    -F "file=@contacts.csv" \
    -F 'column_mapping={"Phone":"phone_e164","First Name":"first_name"}'

  curl -X POST "https://api.callaro.ai/api/v1/bulk_call_campaigns/123/launch" \
    -H "X-Api-Key: $CALLARO_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const createCampaign = await fetch('https://api.callaro.ai/api/v1/bulk_call_campaigns', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.CALLARO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Workflow Example Campaign',
      agent_id: 42,
      timezone: 'Asia/Kolkata',
      campaign_phone_number_ids: [101]
    })
  });
  const { data: campaign } = await createCampaign.json();
  ```

  ```python Python theme={null}
  import requests

  campaign = requests.post(
      'https://api.callaro.ai/api/v1/bulk_call_campaigns',
      headers={
          'X-Api-Key': 'YOUR_CALLARO_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'name': 'Workflow Example Campaign',
          'agent_id': 42,
          'timezone': 'Asia/Kolkata',
          'campaign_phone_number_ids': [101],
      },
      timeout=30,
  )
  print(campaign.json().get('data', {}).get('id'))
  ```
</CodeGroup>

<Note>
  For production rollout, pair generated schema validation with staged integration tests in sandbox before enabling write scopes in production.
</Note>