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:

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:

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.

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.

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:

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.

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). 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

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. 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:

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

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

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.

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).
• 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). The same operations are MCP actions (MCP developer guide) 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).
• OpenRouter compatibility matrix — endpoint and field parity, same / differs / missing / Ocean-only (OpenRouter compatibility).
• Connectors chapter — OAuth vs API-key connectors, connected accounts, the connector proxy (Connectors).
• Agent tiers — tool agents, one-agent (the runtime: call mode and loop mode), concierge-agent, claude-managed-agent (Agents plane).
• Capability injection — skills, experts, persona, backgrounds, plugins, and MCP on harness missions (Skills, plugins & capability injection).
• SDK matrix — OpenAI SDKs, @plungeai/one-api, LiteLLM, Vercel AI SDK, LangChain, and MCP clients (SDKs & 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 (opens in a new tab).
• Every response carries an x-request-id — include it when you report a problem (Traces & observability).