> ## 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.

# Shilo API Reference: Base URL, Auth & Status Codes

> The Shilo External API is organized around REST. Covers the base URL, authentication methods, response format, and standard HTTP status codes.

The Shilo External API gives you programmatic access to call recordings, AI-generated coaching and analysis, contacts, users, and more. All endpoints follow REST conventions — you interact with them using standard HTTP methods, and every response is returned as JSON. This page covers the foundational concepts you need before diving into individual endpoints.

## Base URL

All API requests are made to the following base URL:

```text theme={null}
https://api.shilo.ai/api/v1
```

Every endpoint path in this reference is relative to this base. For example, the calls list endpoint is accessed at `https://api.shilo.ai/api/v1/calls`.

## Authentication

The Shilo API uses API keys to authenticate requests. You must include your API key on every request using one of the two supported header formats:

```http theme={null}
x-api-key: YOUR_API_KEY
```

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Both formats are equivalent. Each API key is scoped to a single Shilo integration within your organization, so it can only access data belonging to that integration, and it carries specific read-only or read-write permissions. Keep it secret and never expose it in client-side code or public repositories.

<Note>
  **Read-only vs. write keys** — Shilo issues both read-only and write-enabled API keys. Read-only keys may call `GET` endpoints but will receive a `403 Forbidden` response if they attempt any write operation such as `POST /calls`. Use a write-enabled key when submitting call recordings or creating resources.
</Note>

## Response Format

Responses that include a body use `application/json`. Successful `204 No Content` responses have no body. Successful responses that do return a body follow a consistent envelope shape for collection endpoints:

```json theme={null}
{
  "data": [ /* array of resource objects */ ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmV..."
  }
}
```

Single-resource endpoints return the resource object directly, without a wrapping envelope.

## HTTP Status Codes

Shilo uses standard HTTP status codes to indicate the outcome of every request.

| Code                        | Meaning                                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                    | The request succeeded and the response body contains the requested resource or collection.                                                   |
| `201 Created`               | A new resource was successfully created. The response body contains the created object.                                                      |
| `202 Accepted`              | The request was accepted for asynchronous processing (e.g., a new call submitted for AI analysis).                                           |
| `204 No Content`            | The request succeeded and there is no response body (common for deletions).                                                                  |
| `400 Bad Request`           | The request was malformed or contained invalid parameters. Check the response body for details.                                              |
| `401 Unauthorized`          | No API key was provided, or the key is invalid or expired.                                                                                   |
| `403 Forbidden`             | Your API key does not have permission to perform this action (e.g., a read-only key on a write endpoint, or an unsupported CRM integration). |
| `404 Not Found`             | The requested resource does not exist.                                                                                                       |
| `409 Conflict`              | The request conflicts with the current state of a resource (e.g., transcript not yet ready).                                                 |
| `500 Internal Server Error` | An unexpected error occurred on Shilo's servers. Retry with exponential back-off.                                                            |

## Example Request and Response

The following example retrieves your most recent call recording:

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/calls?limit=1&sort=desc" \
  --header "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "type": "call",
      "created_date": "2030-09-24T12:34:56Z",
      "duration": 120,
      "external_user_id": "432",
      "user_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "source": "Broker",
      "stage": "Agents"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

## API Resources

The Shilo API is organized into the following resource groups. Select a section to explore the available endpoints.

<CardGroup cols={2}>
  <Card title="Calls" icon="phone" href="/api-reference/calls/list-calls">
    List, submit, retrieve, and analyze call recordings with full AI coaching output.
  </Card>

  <Card title="Appointments" icon="calendar" href="/api-reference/appointments">
    Manage scheduled appointments tied to contacts and sales stages.
  </Card>

  <Card title="Roleplays" icon="microphone" href="/api-reference/roleplays">
    Access AI-powered roleplay sessions used for agent practice and scoring.
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts">
    Create and manage contacts (leads) associated with your calls and appointments.
  </Card>

  <Card title="Users" icon="user" href="/api-reference/users">
    Manage agent user accounts, roles, and external ID mappings.
  </Card>

  <Card title="Invitations" icon="envelope" href="/api-reference/invitations">
    Send and track invitations for new agents to join your Shilo organization.
  </Card>

  <Card title="Metrics" icon="chart-bar" href="/api-reference/metrics">
    Query aggregated performance metrics for agents and teams over time.
  </Card>

  <Card title="Coaching" icon="chalkboard-user" href="/api-reference/coaching">
    Retrieve AI-generated coaching insights, improvement areas, and top moments.
  </Card>
</CardGroup>