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

# Overview

> REST and MCP APIs for AI-powered staff scheduling

Erna exposes a scheduling API with these parts:

* **Playbooks and connectors** for API discovery
* **Connections** for service authorization
* **Pipelines** for reusable scheduling definitions
* **Runs** for asynchronous pipeline execution
* **Billing** for credits and checkout
* **MCP** for interactive scheduling in Claude and ChatGPT

## Base URLs

REST and billing use:

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

MCP uses:

```text theme={null}
https://mcp.erna.ai
```

## REST API

### Create a pipeline

Use `POST /v1/workspaces/{workspaceId}/pipelines` to create a reusable pipeline.

```bash theme={null}
curl -X POST https://api.erna.ai/v1/workspaces/ws_123/pipelines \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly rota",
    "playbook": "scheduling",
    "instructions": "Keep 2 servers on lunch and 1 bartender on dinner every day.",
    "services": {
      "planday": { "connection": "conn_123" }
    }
  }'
```

### Run a pipeline

Use `POST /v1/workspaces/{workspaceId}/pipelines/{pipelineId}/runs` to invoke the latest ready revision.

```bash theme={null}
curl -X POST https://api.erna.ai/v1/workspaces/ws_123/pipelines/pln_123/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "dateRange": {
        "start": "2026-04-21",
        "end": "2026-04-27"
      }
    }
  }'
```

Typical response:

```json theme={null}
{
  "id": "run_123",
  "status": "running",
  "pipeline": "pln_123",
  "revision": "rev_123",
  "links": {
    "self": "/v1/runs/run_123",
    "events": "/v1/runs/run_123/events",
    "artifacts": "/v1/runs/run_123/artifacts"
  }
}
```

Runs can also return actionable states such as `auth_required`, `input_required`, or `unsupported`.

### Check run status

Use `GET /v1/runs/{runId}` to poll the current run state.

```bash theme={null}
curl https://api.erna.ai/v1/runs/run_123 \
  -H "Authorization: Bearer $TOKEN"
```

### Billing

Billing endpoints:

* `GET /v1/billing/balance`
* `GET /v1/billing/transactions`
* `POST /v1/billing/checkout`
* `POST /v1/billing/webhook`

Example:

```bash theme={null}
curl https://api.erna.ai/v1/billing/balance \
  -H "Authorization: Bearer $TOKEN"
```

## MCP API

Erna also exposes an MCP server for interactive scheduling:

* Base URL: `https://mcp.erna.ai`
* `POST /mcp`
* `GET /sse`
* `POST /sse/message`
* `GET /.well-known/oauth-protected-resource`

The MCP tools are:

* `search`
* `execute`

## Errors

All error responses follow a consistent format:

```json theme={null}
{
  "error": "Human-readable error message",
  "details": [{ "path": "input.dateRange.start", "message": "Required" }]
}
```

| Status | Meaning                           |
| ------ | --------------------------------- |
| 400    | Invalid request body              |
| 401    | Missing or invalid authentication |
| 402    | Insufficient credits              |
| 403    | Missing required scope            |
| 404    | Resource not found                |
| 409    | Conflicting or not-ready resource |
| 422    | Invalid run input                 |
| 500    | Internal error                    |