Shilo API Reference: Base URL, Auth & 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:

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:

x-api-key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Both formats are equivalent. Your API key is tied to your Shilo organization and carries specific permissions. Keep it secret and never expose it in client-side code or public repositories.

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.

Response Format

All responses — including errors — are returned as application/json. Successful responses follow a consistent envelope shape for collection endpoints:

{
  "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:

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

{
  "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.

Calls

List, submit, retrieve, and analyze call recordings with full AI coaching output.

Appointments

Manage scheduled appointments tied to contacts and sales stages.

Roleplays

Access AI-powered roleplay sessions used for agent practice and scoring.

Contacts

Create and manage contacts (leads) associated with your calls and appointments.

Users

Manage agent user accounts, roles, and external ID mappings.

Invitations

Send and track invitations for new agents to join your Shilo organization.

Metrics

Query aggregated performance metrics for agents and teams over time.

Coaching

Retrieve AI-generated coaching insights, improvement areas, and top moments.

​Base URL

​Authentication

​Response Format

​HTTP Status Codes

​Example Request and Response

​API Resources

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

Base URL

Authentication

Response Format

HTTP Status Codes

Example Request and Response

API Resources