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

# How PlungeAI works

> The seven planes, the MCP endpoint and how a request flows.


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](/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](/mcp-reference/overview).

## How a request flows

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

```mermaid
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)]
```

1. The router checks the `ozk_` key, mints the `x-request-id`, and adopts your UUID `x-trace-id` or generates a trace id.
2. The CNL engine loads the agent card from the registry and refuses any agent that is not `status:active` before it runs.
3. 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

<CardGroup cols={3}>
<Card title="Status" icon="server" href="/resources/status">
Service health.
</Card>
<Card title="Warnings and errors" icon="triangle-alert" href="/resources/warnings-and-errors">
Error codes and what to do.
</Card>
<Card title="Docs for agents" icon="robot" href="/resources/docs-for-agents">
llms.txt, markdown pages and /agents.md.
</Card>
</CardGroup>

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