# Cero Labs API Reference

> Base URL: `https://api-production-cd65.up.railway.app`
> Auth: `X-API-Key: cero_<key>` header on all endpoints except registration.

## Authentication

### POST /auth/register
Register a tenant and receive an API key. No auth required.

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Tenant or agent name |
| email | string | yes | Contact email (unique) |
| company | string | no | Company name |

**Response (201):**
```json
{
  "tenant_id": "uuid",
  "api_key": "cero_<48hex>",
  "tier": "free",
  "next_steps": { ... }
}
```

### POST /auth/api-key
Generate an additional API key. Requires auth.

**Response:**
```json
{ "api_key": "cero_<48hex>", "tenant_id": "uuid", "tier": "free" }
```

### GET /auth/usage
Get usage metrics. Requires auth.

**Response:**
```json
{
  "tenant_id": "uuid",
  "tier": "free",
  "escalations_today": 5,
  "escalations_this_month": 45,
  "avg_resolution_time": 120.5,
  "limits": { "escalations_per_day": 10, "escalations_per_month": 100 }
}
```

**Tier limits:**
| Tier | Per Day | Per Month |
|------|---------|-----------|
| free | 10 | 100 |
| pro | 500 | 10,000 |
| enterprise | unlimited | unlimited |

---

## Escalations

### POST /escalations
Create an escalation. Requires auth.

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| domain | string | yes | Expert domain (e.g. `healthcare.rcm`, `legal.compliance`) |
| query | string | yes | Question or case for expert review |
| context | object | no | Structured context for the expert |
| priority | string | no | `urgent` (5min), `standard` (30min, default), `batch` (24hr) |
| output_schema | object | no | JSON Schema the response must conform to |
| callback_url | string | no | Webhook URL for async delivery |
| metadata | object | no | Caller-defined tracking data |

**Response (201):**
```json
{
  "id": "uuid",
  "status": "pending",
  "priority": "standard",
  "domain": "healthcare.rcm",
  "sla_deadline": "2026-04-13T14:23:00Z",
  "created_at": "2026-04-13T13:53:00Z"
}
```

### GET /escalations/{escalation_id}
Get escalation status and resolution. Requires auth.

**Status lifecycle:** `pending` → `routed` → `in_review` → `resolved`
Also: `expired` (SLA breached), `cancelled` (caller cancelled)

**Response (resolved):**
```json
{
  "id": "uuid",
  "domain": "healthcare.rcm",
  "query": "...",
  "status": "resolved",
  "resolution": {
    "answer": { ... },
    "confidence": 0.95,
    "reasoning": "...",
    "expert_id": "uuid",
    "resolved_at": "2026-04-13T14:01:00Z"
  }
}
```

### GET /escalations
List escalations. Requires auth.

**Query params:** `status`, `domain`, `limit` (default 50, max 200), `offset` (default 0)

### POST /escalations/{escalation_id}/cancel
Cancel a pending/routed escalation. Requires auth.

### POST /escalations/{escalation_id}/feedback
Rate a resolution. Requires auth.

**Query params:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| score | float | yes | Rating 0.0–1.0 |
| comment | string | no | Free-text feedback |

---

## Experts

### POST /experts
Register a new expert. Requires auth.

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Expert name |
| email | string | yes | Contact email |
| domains | string[] | yes | Domain specialties |
| credentials | string[] | no | Certifications/licenses |
| tier | string | no | `standard` (default), `senior`, `principal` |
| max_concurrent | integer | no | Max simultaneous escalations (default 3) |

**Response (201):**
```json
{
  "id": "uuid",
  "name": "Dr. Alice Chen",
  "domains": ["healthcare.rcm"],
  "tier": "senior",
  "status": "available",
  "quality_score": null,
  "resolution_count": 0
}
```

### GET /experts
List experts (tenant + platform-wide). Requires auth.

**Query params:** `domain`, `status` (`available`, `busy`, `offline`), `limit` (default 50, max 200)

Ordered by `quality_score` descending.

### GET /experts/{expert_id}
Get expert profile. Requires auth.

### PATCH /experts/{expert_id}
Update expert. Requires auth.

**Request body (all optional):** `status`, `domains`, `credentials`, `tier`, `max_concurrent`

### POST /experts/me/escalations/{escalation_id}/resolve
Submit a resolution from the expert portal. Requires `X-Expert-Token`.

**Request body:**
```json
{
  "answer": { "approved_cpts": ["99213", "99214"] },
  "confidence": 0.94,
  "reasoning": "Short explanation of the coding rationale",
  "source_candidate_id": "uuid-or-null",
  "candidate_action": "edited"
}
```

Returns `422` when the Quality Gate rejects the answer (for example, schema mismatch).

### POST /experts/me/escalations/{escalation_id}/decline
Decline a case and return it to the routing pool. Requires `X-Expert-Token`.

**Request body:**
```json
{
  "reason": "need_more_context",
  "notes": "Optional free-text notes for routing/admin review",
  "source_candidate_id": "uuid-or-null"
}
```

---

## Webhooks

When `callback_url` is set on an escalation, Cero delivers the resolution via POST:

```json
{
  "event": "escalation.resolved",
  "escalation_id": "uuid",
  "domain": "healthcare.rcm",
  "status": "resolved",
  "resolution": {
    "answer": { ... },
    "confidence": 0.95,
    "reasoning": "...",
    "expert_id": "uuid",
    "resolved_at": "2026-04-13T14:01:00Z"
  }
}
```

Timeout: 30 seconds.

### GET /webhooks/deliveries/{escalation_id}
Check webhook delivery status. Requires auth.

---

## Errors

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Validation error |
| 401 | Missing or invalid API key |
| 404 | Not found or unauthorized |

```json
{ "detail": "Invalid API key" }
```

---

## Quick Start

```bash
# 1. Register
curl -X POST https://api-production-cd65.up.railway.app/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "email": "dev@example.com"}'

# 2. Escalate
curl -X POST https://api-production-cd65.up.railway.app/escalations \
  -H "X-API-Key: cero_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "healthcare.rcm", "query": "CPT code review", "priority": "standard"}'

# 3. Poll
curl https://api-production-cd65.up.railway.app/escalations/ESCALATION_ID \
  -H "X-API-Key: cero_YOUR_KEY"
```

## SDKs

- Python source install: `pip install "git+https://github.com/os1123/cero-labs.git#subdirectory=sdk/python"`
- TypeScript: `npm install cerolabs-sdk`
- MCP server: `npx -y cerolabs-mcp`
- Agent discovery: `https://cerolabs.ai/llms.txt`