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

# Get Started with the Shilo API in Minutes

> Submit your first call recording to Shilo and retrieve AI-generated analysis in five steps. Covers authentication, call creation, and polling for results.

This guide walks you through the complete lifecycle of a Shilo API call: generating a key, submitting a recording, and reading back the AI analysis. By the end you will have a working integration pattern you can adapt to any language or framework. The five steps below cover everything from authentication to inspecting the available analysis fields.

## Step 1: Generate an API key

In the Shilo dashboard, navigate to **Settings > API Keys > Generate API Key** and create a **read-write** key. Copy the key immediately, it is only shown once. Store it as a secret in your environment (for example, `SHILO_API_KEY`) and never commit it to source control.

## Step 2: Prepare a recording URL

Host your call recording at a publicly accessible URL that Shilo can fetch over HTTPS. Common patterns include a signed S3 URL, a Cloudflare R2 public link, or any CDN-hosted audio file. Make sure the URL resolves without additional authentication for the duration of processing.

## Step 3: Submit the call

Send a `POST` to `https://api.shilo.ai/api/v1/calls` with your API key in the `x-api-key` header and a JSON body containing every required field.

```bash cURL theme={null}
curl -X POST https://api.shilo.ai/api/v1/calls \
  -H "x-api-key: $SHILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording_id": "rec_2f7a91",
    "recording_url": "https://cdn.example.com/calls/rec_2f7a91.mp3",
    "duration_seconds": 842,
    "ai_category": "sales",
    "external_user_id": "usr_alex_01",
    "user_name": "Alex Rivera",
    "user_email": "alex@example.com",
    "external_contact_id": "cnt_jordan_42",
    "contact_name": "Jordan Lee"
  }'
```

A successful submission returns `202 Accepted` with the queued call event.

```json 202 Accepted theme={null}
{
  "call_event_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "status": "QUEUED"
}
```

## Step 4: Poll for analysis

Save the `call_event_id` and poll `GET /api/v1/calls/call_event_id:{call_event_id}/analysis` using the same API key. Continue polling until `progress` reaches `100`.

```bash cURL theme={null}
curl https://api.shilo.ai/api/v1/calls/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31/analysis \
  -H "x-api-key: $SHILO_API_KEY"
```

`progress: 100` means processing is complete. Individual analysis objects can still be absent or `null` depending on the call's content and length, so treat each sub-object as optional in your integration.

## Step 5: Inspect the analysis

Once processing is complete, read the fields your workflow needs. The analysis response can include:

* `rating`, a numeric quality score for the call.
* `summary`, an AI-generated recap.
* `coaching`, structured coaching feedback for the rep.
* `disposition`, the call outcome classification.
* `objections`, buyer objections detected in the conversation.
* `action_items`, follow-ups surfaced from the discussion.
* `speakers`, AI-resolved user and client names.

Any of these may be missing or `null` on a given call, so check for presence before accessing nested fields.

For deeper coverage of every request and response field, see the [Submit Calls](/guides/submitting-calls) and [Retrieve Analysis](/guides/retrieving-analysis) guides.

## Next Steps

<CardGroup cols={2}>
  <Card title="Submit Calls" icon="upload" href="/guides/submitting-calls">
    Learn all required and optional fields for the call creation endpoint.
  </Card>

  <Card title="Retrieve Analysis" icon="chart-bar" href="/guides/retrieving-analysis">
    Deep-dive into every analysis field and the polling pattern.
  </Card>

  <Card title="Identifiers" icon="fingerprint" href="/concepts/identifiers">
    Understand the prefix:value identifier system used across all resources.
  </Card>

  <Card title="Pagination" icon="list" href="/concepts/pagination">
    Page through large result sets with cursor-based pagination.
  </Card>
</CardGroup>