# OATDA — One API to Direct Agents

> Agent-native multi-modal AI infrastructure (text, vision, image, video, audio).
> 10+ providers (OpenAI, Anthropic, Google, DeepSeek, Moonshot, ...) behind a single API key.
> EU-based. Credit-based pay-as-you-go billing. Min top-up €1.
> MCP-native: full Model Context Protocol server built in.

## Quick Start

- Base URL (OpenAI-compat): https://oatda.com/api/v1
- Base URL (Anthropic-compat): https://oatda.com/api/v1/anthropic
- MCP Server URL: https://oatda.com/api/v1/mcp
- Auth header: `Authorization: Bearer $OATDA_API_KEY`
- Get an API key: https://oatda.com/dashboard/api-keys
- Top up credits (min €1): https://oatda.com/dashboard/credits
- Machine-readable pricing: GET https://oatda.com/api/v1/pricing

## Endpoints (OpenAI-compatible)

- POST /api/v1/chat/completions — chat (stream + non-stream)
- POST /api/v1/systemone — TypeSafe Jev System One (ADR-0029; catalog `endpoint: systemone`)
- POST /api/v1/embeddings — text embeddings (ADR-0027; catalog `endpoint: embeddings`)
- POST /api/v1/responses — Responses API for Codex CLI (ADR-0018; catalog opt-in via `responses_api_support`)
- GET  /api/v1/responses/v1/models — list Responses-capable models (no auth)
- POST /api/v1/llm — native chat (direct cost in response)
- GET  /api/v1/models — list models
- **Virtual model `oatda-auto` / `oatda-auto:{configId}`** — point IDE clients (Cline/Cursor) at bare `oatda-auto` (newest enabled Gateway Router agent) or pin a specific agent with `oatda-auto:{uuid}` from the dashboard (ADR-0023). Vision→controller, text→coder.
- GET  /api/v1/pricing — machine-readable pricing catalog (no auth required)
- POST /api/v1/llm/generate-image — image generation (DALL-E, Imagen, ...)
- POST /api/v1/llm/generate-video — video generation (MiniMax, Veo, Seedance, ...). Optional webhook param `webhook_url` (HTTPS, public IP only): OATDA generates the signing secret server-side (32 bytes, base64url) and returns it ONCE as `webhook_secret` in the create response — signed `video.completed` POST on completion. Failed deliveries are retried up to 5 attempts with exponential backoff (1m/5m/30m/2h cap); dedup on taskId+event (see Video Jobs & Webhooks example below)
- GET  /api/v1/jobs — list your video tasks (paginated, `?status=pending|processing|completed|failed|canceled`; dashboard session cookie auth)
- GET  /api/v1/jobs/{id} — one video task detail (videoUrl/costs when completed, errorMessage when failed; session auth)
- POST /api/v1/jobs/{id}/cancel — cancel a queued or in-flight video task (canceled becomes terminal; already-terminal tasks → 409 `TASK_ALREADY_TERMINAL`; billing unchanged, no refund; session auth)
- POST /api/v1/llm/speech — text-to-speech
- POST /api/v1/llm/transcriptions — audio transcription
- POST /api/v1/llm/translations — audio translation
- POST /api/v1/llm — vision/image analysis (contents[] multimodal). Legacy /llm/image alias deprecated.
- POST /api/v1/compare — compare multiple models in one call

## Endpoints (Anthropic-compatible)

- POST /api/v1/anthropic/v1/messages — Messages API (Cline, Claude Code, Aider)
- GET  /api/v1/anthropic/v1/models

## MCP Server (Streamable HTTP)

- URL: https://oatda.com/api/v1/mcp
- Transport: Streamable HTTP, JSON-RPC 2.0 (MCP spec)
- Auth: `Authorization: Bearer $OATDA_API_KEY`
- 13 tools: `chat_completion`, `system_one`, `vision_analysis`, `generate_image`, `generate_video`, `get_video_status`, `list_jobs`, `get_job`, `cancel_job`, `generate_speech`, `transcribe_audio`, `translate_audio`, `list_models`
- `generate_video` accepts optional `webhook_url` (same rules as the HTTP route — a `webhook_secret` param is rejected; the generated secret is returned once in the tool result); `list_jobs` / `get_job` / `cancel_job` mirror the Jobs API over Bearer auth.
- No install required: API key + credits is enough.

## A2A Gateway (Agent-to-Agent)

- Agent Card: https://oatda.com/.well-known/agent-card.json
- JSON-RPC: POST https://oatda.com/api/v1/a2a
- Auth: `Authorization: Bearer $OATDA_API_KEY` only (no `x-api-key` on A2A)
- Skills: `llm-chat`, `vision-compare`, `billing-audit`, `oneagent` (internal orchestrate); SSE `message/stream`; `CancelTask` / `GetTask` (Redis ~24h); optional signed card (`A2A_CARD_JWK`, JWKS `/.well-known/a2a-jwks.json`)
- Spec: https://a2a-protocol.org/latest/
- Human docs: https://oatda.com/docs (section A2A Gateway)

## Pricing

- Per-model, pay-as-you-go. No subscription, no free tier.
- Min top-up: €1. Methods: credit card, PayPal.
- JSON catalog: GET /api/v1/pricing (no auth required, rate-limited)
- Per-model pricing in model list: GET /api/v1/llm/models (requires Authorization: Bearer $OATDA_API_KEY)
- Human-readable: https://oatda.com/pricing

## Agent Capabilities

- `agents.md`: https://oatda.com/agents.md
- `.well-known/agent.json`: https://oatda.com/.well-known/agent.json

## Docs

- Full markdown (all 5 locales, EN/DE/ES/FR/IT): https://oatda.com/llms-full.txt
- Per-section markdown: GET /api/v1/docs/markdown?sectionId=<sectionId>
  Sections: gettingStarted, authentication, coreEndpoints, videoJobsWebhooks,
  openaiCompatible, anthropicCompatible, extraBody, mcp, a2a, skills, useCases,
  examples, errorHandling
- Human docs: https://oatda.com/docs

## Code Examples

```bash
# OpenAI-compat chat
curl https://oatda.com/api/v1/chat/completions \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "hi"}]}'
```

```bash
# OpenAI-compat embeddings
curl https://oatda.com/api/v1/embeddings \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "The food was delicious"}'
```

```bash
# Anthropic-compat messages
curl https://oatda.com/api/v1/anthropic/v1/messages \
  -H "x-api-key: $OATDA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 1024, "messages": [{"role": "user", "content": "hi"}]}'
```

```bash
# MCP server (JSON-RPC)
curl https://oatda.com/api/v1/mcp \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

```bash
# Video with completion webhook + jobs list (session cookie for /jobs)
curl -X POST https://oatda.com/api/v1/llm/generate-video?async=true \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"google","model":"veo-3-fast-001","prompt":"A sunset","webhook_url":"https://example.com/hooks/oatda"}'
# Response contains "webhook_secret" ONCE (server-generated, 32 bytes base64url) — save it now.
# OATDA then POSTs {event:"video.completed", taskId, videoUrl, model, costs}
# signed: X-OATDA-Signature = HMAC-SHA256(webhook_secret, "X-OATDA-Timestamp" + "." + rawBody)
# Retries: non-2xx/timeout → up to 5 attempts, backoff 1m/5m/30m/2h (cap). Any 2xx stops.
# Dedup: taskId+event is the idempotency key — retries may redeliver the same event.
curl "https://oatda.com/api/v1/jobs?status=completed&perPage=20" -b cookies.txt
```

```bash
# OpenAI Responses API (Codex CLI native)
curl https://oatda.com/api/v1/responses \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","input":[{"role":"user","content":"hi"}]}'
```

## Codex CLI (Responses API)

OATDA is a drop-in backend for OpenAI Codex CLI. Use DeepSeek or Alibaba/Qwen models as the Codex engine.

```toml
# ~/.codex/config.toml
model = "deepseek-v4-flash"
model_provider = "oatda"

[model_providers.oatda]
name = "OATDA"
base_url = "https://oatda.com/api/v1"
wire_api = "responses"   # mandatory: Codex needs Responses, not chat/completions
env_key = "OATDA_API_KEY"
```

Responses-capable models (catalog opt-in, ADR-0018): deepseek-v4-flash, qwen3-coder-plus, qwen3-coder-flash, qwen3-max, qwen3.7-max (+preview), qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen3.6-flash, qwen3.5-flash, qwen-plus, qwen-flash.

## Provider notes

- Provider prefix in `model` field (e.g. `openai/gpt-4o-mini`, `anthropic/claude-sonnet-4-20250514`).
- Streaming via SSE on all chat endpoints (`stream: true`).
- Native endpoint `/api/v1/llm` returns direct cost info in response (simpler for scripts).

## Agent skills (drop-in integration)

- **Claude Code plugin**: https://github.com/devcsde/oatda-skills
  Install: `/plugin marketplace add devcsde/oatda-skills` → browse → Install.
  9 skills: text, vision, image, video, video-status, speech, transcribe, translate, list-models.
- **OpenClaw skills**: https://github.com/devcsde/oatda-openclaw-skills
  Install: `clawhub install oatda-text-completion` (and 8 more; see README).
- **MCP (Cursor, Cline, Claude Code, etc.)**: https://oatda.com/api/v1/mcp — no install needed.

## Optional

[Links]: https://oatda.com/llms-full.txt | https://oatda.com/agents.md | https://oatda.com/.well-known/agent.json | https://oatda.com/docs | https://oatda.com/pricing | https://oatda.com/models