# Olaa Public API

Create threads, run tasks, and download result files from your own applications.

Base URL: `https://api.olaa.com/api/public/v1`

## Authentication

Create a key in Settings → API keys. Personal keys act as you; team keys act as the workspace (admin-only, required for audit:read). Send `Authorization: Bearer ol_live_sk_…` or `x-api-key`.

```
curl https://api.olaa.com/api/public/v1/me -H "Authorization: Bearer $OLAA_API_KEY"
```

## Core workflow

Create a thread → post a message (starts a run, returns 202) → poll the run → fetch the result → download files with a short-lived URL.

```
POST /threads
POST /threads/{id}/messages  { "content": "Build the weekly recap as PDF", "speed": "balanced" }
GET  /runs/{id}                → status: queued | running | requires_action | completed | failed
GET  /runs/{id}/result         → { text, files: [{ token, filename }] }
GET  /files/{token}/download-url
```

## Idempotency, pagination, limits

Send `Idempotency-Key` on POSTs (24h). Lists are keyset-paginated with `limit` and `starting_after`. Rate limits are per key with `X-RateLimit-*` headers and `Retry-After` on 429. 402 means the workspace is out of credits.

## Errors

All errors use `{ "detail": { "error": "<code>", "message": "<human>" } }` with codes unauthorized, insufficient_scope, not_found, validation_error, rate_limit_exceeded, insufficient_credits, thread_busy, run_timed_out, internal.

## Endpoints

| Method | Path | Scope | Note |
|---|---|---|---|
| GET | `/me` | any | Key owner and workspace |
| POST | `/threads` | threads:create |  |
| GET | `/threads` | threads:read |  |
| GET | `/threads/{id}` | threads:read |  |
| POST | `/threads/{id}/messages` | messages:create + runs:create | 202 with run |
| GET | `/threads/{id}/messages` | messages:read |  |
| GET | `/threads/{id}/runs` | runs:read |  |
| GET | `/runs/{id}` | runs:read |  |
| GET | `/runs/{id}/result` | runs:read | terminal runs only |
| POST | `/runs/{id}/cancel` | runs:create |  |
| GET | `/files/{token}/download-url` | files:read | 15-minute URL |
| GET | `/credits` | usage:read |  |
| GET | `/usage/summary` | usage:read |  |
| GET | `/usage/daily` | usage:read |  |
| GET | `/audit/events` | audit:read (team key) |  |