How PlungeAI works

The One API is one HTTPS front door, https://api.plungeai.com, with one router behind it. The MCP server, https://mcp.plungeai.com/v1, gives coding agents the same capabilities as tools.

The seven planes

Plane	What it does	Key routes	Key
Models	OpenAI-compatible chat, embeddings and model catalog, with ordered fallback, `sort`, `@preset/<slug>`, guardrails and an opt-in response cache	`POST /v1/chat/completions` · `POST /v1/embeddings` · `GET /v1/models`	`sk-ocean-`
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	Outbound MCP runs against catalog servers; coding agents connect to the MCP server	`GET /v1/mcp/tools` · `POST /v1/mcp/runs`	`ozk_`
Discovery	Search and recommend across the capability registry	`GET /v1/discovery/search` · `POST /v1/discovery/recommend` · `GET /v1/discovery/cards/{type}/{id}`	`ozk_`
Traces	Read the persisted execution trace for one trace id	`GET /v1/traces/{id}`	`ozk_`

The machine-readable route list is GET /v1/openapi.json; this site serves the same operations at /openapi.json.

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 OpenAI or OpenRouter integration moves over with a base-URL swap. 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.

The MCP endpoint

The MCP server is https://mcp.plungeai.com/v1: Streamable HTTP, JSON-RPC over POST, 20 plungeai_* tools, one prompt and five resources plus three resource templates. The pre-2026-09-20 path /mcp on the same host still answers with the same handler as a legacy alias; configure /v1. Details: MCP Reference.

How a request flows

An execution-plane call runs router → CNL engine → agent:

flowchart LR
  client[Your code] -->|ozk_ key| router[One API router]
  router -->|service binding| engine[CNL engine]
  engine --> agent[Registry agent]
  agent --> memory[(Result and trace)]

The router checks the ozk_ key, mints the x-request-id, and adopts your UUID x-trace-id or generates a trace id.
The CNL engine loads the agent card from the registry and refuses any agent that is not status:active before it runs.
The agent's result is stored and returned, and the whole run is persisted as trace spans.

Every call gets the same outcome vocabulary (ok, needs_input, needs_connection, needs_api_key, needs_approval, unavailable, error) and the same trust fence, whether it comes from a workflow, Ocean Studio or your code.

Tool families

Family	MCP tools
Discover	`plungeai_list_agents`, `plungeai_get_tool_contract`, `plungeai_templates` (list, get)
Run a tool	`plungeai_execute_tool`
Run an agent	`plungeai_execute_agent`, `plungeai_run_mission`
Workflows	`plungeai_list_workflows`, `plungeai_execute_workflow`, `plungeai_workflow`, `plungeai_build_workflow`, `plungeai_templates` (use)
Runs and results	`plungeai_get_result`, `plungeai_get_workflow_status`, `plungeai_executions`, `plungeai_followup`, `plungeai_continue`
Chat, memory, skills	`plungeai_chat`, `plungeai_memory`, `plungeai_learn`
Scheduling	`plungeai_schedule`
Identity	`plungeai_whoami`

A registry agent is a platform building block in the catalog; "your workflows" are the CNL workflows you saved.

Live-verified examples

Execution-plane examples on this site come from the One API and MCP guides, whose read-only examples were run against the deployed API and are re-run by the guides' example verifier. Models-plane (sk-ocean-) examples are verified against code, not live. Examples that run a model or spend credits say so in the text.

Where to get help

Status

Service health.

Warnings and errors

Error codes and what to do.

Docs for agents

llms.txt, markdown pages and /agents.md.

Every response carries an x-request-id: include it when you report a problem. Support contact: TBD by owner (TI-62).