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

# One API guide

> The Ocean One API is a single HTTPS front door to the Ocean platform. One base URL, one router, and every capability the platform exposes reachable from it:


The **Ocean One API** is a single HTTPS front door to the Ocean platform. One base URL,
one router, and every capability the platform exposes reachable from it:

    https://api.plungeai.com

Everything in this guide is a real route on that host. The router is a thin Hono worker
(`orchestration/api-gateway/api-gateway.ts`) that fronts the registry, the CNL engine, the
MCP gateway, the MCP executor, and the inference gateway over internal service bindings —
you never address those services directly.

## Start here — one call, 30 seconds

Get an `ozk_` key at Dashboard → **One API → Keys** (`https://dashboard.plungeai.com`), then:

```bash
curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"In one sentence: what is a content delivery network?","sync":true,"max_tokens":60}'
```

Add `"stream": true` and you get OpenAI-shaped chunks; send the same fields as YAML with
`format: markdown` and you get Markdown back. Thirty-five more pasteable calls — streaming and
not, JSON and YAML, tools, workflows, MCP, create-and-run — are in the [Quickstart](/one-api/quickstart).

## Three levels

The One API has three levels. All three stay: none is deprecated in favour of another, and they share the
one `ozk_` key, the request ids and the error envelope.

| Level | What it is | Use it when | Details |
|---|---|---|---|
| **1. The compatible wire** | OpenAI-shaped `POST /v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, `GET /v1/models`, and the OpenRouter drop-in base `/api/v1`. Models only | you already have an OpenAI or OpenRouter client: swap the base URL | [Models plane](/one-api/models), [OpenRouter compatibility](/one-api/openrouter-compat) |
| **2. Standard REST** | resources with JSON bodies; YAML is accepted and returned on the same routes. Workflows (create, version, run), executions, schedules, triggers, bot policy and budgets, workspace, inbox, bindings, groups, memory, skills, templates, connections, tools, agents, discovery, traces | you manage things or call one by id: create a bot, cap its spend, answer a paused run, list schedules | the plane chapters, and [Bots](/one-api/bots) for the bot surface |
| **3. The Agent Call door** | `POST /v1/execute`: the body is the program. A bare task, a `workflow:`, or a saved agent `agent: <id>[@n]`; always through the engine; `dry_run`, `stream`, and headers that say what ran | the body is the program: one call, no resource to create first | [The one door](/one-api/bots#169-the-one-door) |

**Start with level 2; use level 3 when the body is the program.** Level 2 gives every resource its own
route, status codes and ids, so it is the one to build on. Level 3 is one route that takes whatever you
send and runs it; it is also how an agent calls another agent by id. The same machine-readable contract
covers all three: `GET /v1/openapi.json` tags the operations `Compat` (level 1), `Workflows`, `Executions`,
`Schedules`, `Triggers`, `Bots`, `Memory`, `Skills`, `Templates`, `Connections` (level 2) and `Agent Call`
(level 3). The older level 2 planes (discovery, tools, agents, MCP, traces) and the meta routes carry no tag.

A level 2 call, read-only and live-verified:

```bash
curl -s "https://api.plungeai.com/v1/workflows?limit=1" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

## The seven planes

The router groups the routes of levels 1 and 2 into planes. Every plane takes the same `ozk_` platform key;
six are the **execution planes**, and the **models plane** is OpenAI-compatible. The resources that manage
bots (saved workflows, executions, schedules, triggers, permissions, memory, skills, templates, connections)
are level 2 as well and are in [Bots](/one-api/bots).

| Plane | What it does | Key routes | Key |
|---|---|---|---|
| **Models** | OpenAI-compatible chat, embeddings, model catalog — a transparent proxy to the inference gateway with ordered fallback, `sort`, `@preset/<slug>`, guardrails, and an opt-in response cache | `POST /v1/chat/completions` · `POST /v1/messages` (Anthropic wire, [3.16](/one-api/models#316-anthropic-messages-post-v1messages)) · `POST /v1/embeddings` · `GET /v1/models` · the same routes under `/api/v1` (OpenRouter drop-in, [5.0](/one-api/openrouter-compat#50-drop-in-mode)) | `ozk_` |
| **Tools** | List tool agents, read a tool's invocation contract, execute one operation behind a trust fence | `GET /v1/tools` · `GET /v1/tools/{id}` · `POST /v1/tools/{id}/execute` | `ozk_` |
| **Agents** | Execute a registry agent from a prompt — sync, async pointer, or OpenAI-shaped SSE | `GET /v1/agents` · `POST /v1/agents/{id}/execute` · `GET /v1/agents/results/{workflowId}/{taskId}` | `ozk_` |
| **Workflows** | Run a multi-agent CNL workflow, inline or saved, with optional SSE | `POST /v1/workflows/execute` · `POST /v1/workflows/execute-stream` · `POST /v1/workflows/{id}/execute` | `ozk_` |
| **MCP** | The platform *as* an MCP server (inbound Streamable HTTP), plus outbound MCP runs against catalog servers — full guide: [MCP developer guide](https://www.plungeai.com/docs/mcp) | `POST /v1/mcp` · `GET /v1/mcp/tools` · `POST /v1/mcp/runs` | `ozk_` |
| **Discovery** | Search and recommend across the capability registry (agents, skills, connectors, models, MCP servers, …) | `GET /v1/discovery/search` · `POST /v1/discovery/recommend` · `GET /v1/discovery/cards/{type}/{id}` | `ozk_` |
| **Traces** | Read the persisted execution trace (spans + gateway request log) for one trace id | `GET /v1/traces/{id}` | `ozk_` |

The full machine-readable route list and schemas are served at `GET /v1/openapi.json`
(source: `orchestration/api-gateway/openapi.ts`). There is also a signed, internal-only
capability plane that customer keys cannot open —
it is not one of the seven and is not documented here.

## Positioning

Think of the One API as **an OpenRouter-compatible models plane plus everything a model
router cannot do.** The models plane speaks the OpenAI wire format, so an existing OpenAI or
OpenRouter integration points at it with a base-URL swap (see [OpenRouter compatibility](/one-api/openrouter-compat)).
The execution planes are the part a router has no answer for: real tools with contracts and
a trust fence, registry agents, multi-agent workflows, discovery, MCP, and a persisted trace
for every run.

## One key

| Prefix | Opens | How you get it |
|---|---|---|
| `ozk_` | Every plane: models, tools, agents, workflows, MCP, discovery, traces, and the connector proxy | Your **Ocean account key**, at Dashboard → **One API → Keys** (`https://dashboard.plungeai.com`), or fetched by `ocean-cli login` / `oceancode login --provider ocean` after a browser sign-in; bound to your account and tier, and billed to the account's one wallet |

Everything is on `https://api.plungeai.com` (MCP also on `https://mcp.plungeai.com`). The
legacy `sk-ocean-` (models) and `sk-conn-` (connector proxy) keys are still accepted on their
own plane while integrations move over, no longer created in the Dashboard. A legacy key sent
to an execution plane is a `401` — see [Authentication & keys](/one-api/authentication). Full
key mechanics are in that chapter; this guide writes the key as the shell variable
`$PLUNGE_API_KEY` (`ozk_`).

## How a request flows

An execution-plane call is not a thin proxy to a model. The path is **router → CNL engine →
agent**:

1. The router authenticates the `ozk_` key, mints a server-side `x-request-id`, and either
   adopts your UUID `x-trace-id` or generates the trace id (`api-gateway.ts`).
2. It dispatches over an internal service binding to the CNL engine, which loads the agent
   card from the registry, refuses anything not `status:active` before dispatch, recalls
   memory, and runs the agent.
3. The agent's result is stored in SharedMemory and returned; the whole run is persisted as
   trace spans.

The engine hop exists on purpose: it gives every call the same history, outcome vocabulary
(`ok | needs_input | needs_connection | needs_api_key | needs_approval | unavailable |
error`), and trust fence, whether the caller is a workflow, Ocean Studio, or you over HTTP.
The rationale is recorded in `orchestration/api-gateway/log/API-SURFACE-DECISION-AND-PLAN.md`
(everything routes through the engine so there is one execution path, not two).

## What "live-verified" means in this guide

Every example that carries a hidden `# verify` / `# expect:` marker was run against the
deployed API and its output checked. The docs build strips the marker; a verifier
(`orchestration/api-gateway/docs/guide-3.0/verify-examples.mjs`) re-runs those examples with
one `ozk_` key. A markered chat example sends one small request (`max_tokens` ≤ 16); examples
that spend more, need a connected account or change state carry no marker and say so.

## 60-second tour

Set your key once, then hit three planes. These three are live-verified:

```bash
curl -s https://api.plungeai.com/health
```

```bash
curl -s "https://api.plungeai.com/v1/discovery/search?q=web+search&kind=agents&limit=3" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

```bash
curl -s "https://api.plungeai.com/v1/agents?limit=3" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"
```

For a first tool call, agent call, workflow, and model completion, go straight to the
[Quickstart](/one-api/quickstart).

## What's new in 3.1

- **Three levels** — the compatible wire, standard REST in JSON or YAML, and the Agent Call door
  `POST /v1/execute`; start with level 2 ([Three levels](#three-levels)).
- **The bot surface over REST** — a bot is a saved `kind: bot` workflow that runs on the `one-agent`
  runtime. Save and version it, set its permissions and budgets, answer and approve its runs, schedule
  and trigger it, read its workspace, inbox, bindings and groups, and use memory, skills and
  templates ([Bots](/one-api/bots)). The same operations are MCP actions
  ([MCP developer guide](https://www.plungeai.com/docs/mcp)) and `ocean-cli` verbs.

## What's new in 3.0

- **Full field-level models reference** — every `/v1/chat/completions` field with its
  support status ([Models plane](/one-api/models)).
- **OpenRouter compatibility matrix** — endpoint and field parity, same / differs / missing
  / Ocean-only ([OpenRouter compatibility](/one-api/openrouter-compat)).
- **Connectors chapter** — OAuth vs API-key connectors, connected accounts, the
  connector proxy ([Connectors](/one-api/connectors)).
- **Agent tiers** — tool agents, `one-agent` (the runtime: call mode and loop mode),
  `concierge-agent`, `claude-managed-agent` ([Agents plane](/one-api/agents)).
- **Capability injection** — skills, experts, persona, backgrounds, plugins, and MCP on
  harness missions ([Skills, plugins & capability injection](/one-api/skills-plugins-capabilities)).
- **SDK matrix** — OpenAI SDKs, `@plungeai/one-api`, LiteLLM, Vercel AI SDK, LangChain, and
  MCP clients ([SDKs & clients](/one-api/sdks-and-clients)).
- **Website copy** — this guide is also published at `https://plungeai.com/docs`.

## Where to get help

- **Docs:** `https://www.plungeai.com/docs/one-api` (this guide) · `GET /llms.txt` and
  `GET /llms-full.txt` for LLM tooling · `GET /v1/openapi.json` for the contract.
- **Keys and support:** [Requests](https://www.plungeai.com/request/new?kind=question).
- **Every response** carries an `x-request-id` — include it when you report a problem
  ([Traces & observability](/one-api/traces-observability)).