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

# OlivIA API overview

> Overview of the OlivIA API: channels, environments, authentication, and integration conventions

The **OlivIA API** lets an external system —an EHR/HIS, a CRM, or your own backend— integrate Omniloy's clinical voice follow-up: enroll patients in protocols, read the outcome of each call, and receive real-time events.

## Two channels

OlivIA works in two directions. The API focuses on the part an integrator needs to drive and read:

* **Outbound calls — follow-up.** You enroll a patient in a protocol and OlivIA calls them to complete the **follow-up questionnaire**, with automatic scheduling and retries. Driven **from the API**.
* **Inbound calls — triage.** A phone number is configured so that, when the patient calls, OlivIA runs a **triage questionnaire**. The number is set up **with the Omniloy team**; results arrive through the same read endpoints and webhooks.

### Follow-up flow (outbound)

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant C as Your system
  participant O as OlivIA
  participant P as Patient
  C->>O: POST /v1/enrollments/enroll-patient
  O-->>C: 201 Enrollment (first call scheduled)
  O->>P: Follow-up call (questionnaire)
  P-->>O: Answers
  O-->>C: webhook run.status_changed (completed)
  C->>O: GET /v1/protocol-runs/{runId} (answers + score)
```

### Triage flow (inbound)

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant P as Patient
  participant O as OlivIA
  participant C as Your system
  P->>O: Calls the triage number
  O->>P: Runs the triage questionnaire
  O-->>C: webhooks (session.start, question.answered, run.status_changed)
  C->>O: GET /v1/protocol-runs/{runId} (triage outcome)
```

## Environments

| Environment | URL                            |
| ----------- | ------------------------------ |
| Production  | `https://{your-prod-endpoint}` |
| Staging     | `https://{your-dev-endpoint}`  |

Contact [soporte@omniloy.com](mailto:soporte@omniloy.com) to get your credentials and your tenant's real URLs.

## Base path and version

All endpoints live under the **`/v1`** prefix. For example:

```bash theme={null}
https://{your-prod-endpoint}/v1/protocols
```

## Authentication

Every operation uses a **personal API key** as a bearer token:

```
Authorization: Bearer oc_sk_...
```

See the [Authentication](/olivia/en/api/auth) guide.

## Response format

Successful responses wrap the payload in `data`:

```json theme={null}
{ "data": { "id": "…" } }
```

Lists add `pagination`:

```json theme={null}
{ "data": [ … ], "pagination": { "total": 128, "limit": 50, "offset": 0 } }
```

Every response carries an `x-request-id` header, useful for support and tracing.

## Errors

Errors use a single envelope:

```json theme={null}
{ "error": { "code": "validation_error", "message": "Invalid request", "details": [] } }
```

| HTTP status | When                                                               |
| ----------- | ------------------------------------------------------------------ |
| `400`       | Invalid request (`validation_error` with `details`)                |
| `401`       | Missing or invalid API key                                         |
| `403`       | The key lacks the role required for the operation                  |
| `404`       | Resource not found or not owned by your organization               |
| `409`       | State conflict (e.g. archiving a protocol with active enrollments) |