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

# Choose an API

> Find the right PlungeAI API for what you are building.


## What are you building?

Find your job in the first column, answer its question, and start with the API the answer names.

| Job | Question | Answer → start with |
|---|---|---|
| **Call a model from my code**: chat or embeddings in my app | Do you need one fixed model, or automatic fallback? | One model → [Chat completions](#start-with-chat-completions) · Fallback, cheapest or fastest → [Model routing](#start-with-model-routing) |
| **Run one capability**: search, scrape, send, look up | Do you already know which tool? | Yes → [Tools](#start-with-tools) · No → [Discovery](#start-with-discovery) |
| **Get an answer from an agent**: one prompt in, an answer out | Do you need the answer now, or can it arrive later? | Now (or streamed) → [Agents (sync)](#start-with-agents-sync) · Later → [Agents (async)](#start-with-agents-async) |
| **Chain several agents**: a pipeline with fixed steps, or an open goal | Should an agent choose the steps itself, within limits? | No, fixed steps → [Workflows](#start-with-workflows) · Yes → [Missions](#start-with-missions) |
| **Run something on a schedule**: every hour, every day, on a condition | none | [Scheduling](#start-with-scheduling) |
| **Work from my coding agent**: Claude Code, Cursor, Codex, VS Code | none | [the MCP server](#start-with-the-mcp-server) |

<Note>
The interactive chooser is planned (TI-74); until then this table and the results below carry the same data.
</Note>

### Start with Chat completions

You call one model you already chose through the OpenAI-compatible chat API, so any OpenAI SDK works once you change the base URL.

**How to start:** base URL `https://api.plungeai.com/v1`; key `$PLUNGE_MODEL_KEY` (an `sk-ocean-` key); `model` set to a slug from `GET /v1/models`; `stream: true` if you want SSE chunks. [Setup details →](/models/quickstart) · [Build with Chat completions →](/models/quickstart)

| | |
|---|---|
| What you send | `POST /v1/chat/completions` with `model`, `messages` and an `sk-ocean-` key |
| What you get back | `chat.completion` (or SSE chunks) with `usage` |
| What your app handles | Retries on 429 `rate_limit_exceeded` and 5xx; model choice |
| How long it takes | One model call; streaming starts at the first token |
| What you pay for | Tokens, billed at provider cost × your org markup ([Pricing](/getting-started/pricing)) |
| What to check | `x-request-id`, `usage`, served `model` ([Models quickstart](/models/quickstart)) |

**Before you build:** an `ozk_` key is rejected on the models plane with `invalid_api_key`; use an `sk-ocean-` key.

### Start with Model routing

The gateway tries your candidates in order, or sorts them by price, latency or throughput, so one failing provider does not fail the request.

**How to start:** the Chat completions setup plus `models: ["<first>", "<fallback>"]` and `sort` set to `price`, `latency` or `throughput`, or `model: "@preset/<slug>"` for a saved preset; the Python SDK passes these in `extra_body`. [Setup details →](/models/routing) · [Build with Model routing →](/models/routing)

| | |
|---|---|
| What you send | The same request, plus `models[]`, `sort` or `model: "@preset/<slug>"` |
| What you get back | The completion from the first candidate that succeeds; `model` names the one that served |
| What your app handles | Reading which model served |
| How long it takes | One call, plus failover attempts |
| What you pay for | Tokens of the model that served |
| What to check | The `model` field, and 502 "All routing candidates failed" |

**Before you build:** read the served `model` field before you log costs; it can differ from your first candidate.

### Start with Tools

You already know the capability, and one tool call gives typed params, one outcome object and the trust fence in a single request.

**How to start:** key `$PLUNGE_API_KEY` (an `ozk_` key); read `GET /v1/tools/{id}` for `operations[]` and `inputSchema`; send `{operation, params}` to `POST /v1/tools/{id}/execute`. [Setup details →](/tools/quickstart) · [Build with Tools →](/tools/quickstart)

| | |
|---|---|
| What you send | `POST /v1/tools/{id}/execute {operation, params}` with an `ozk_` key |
| What you get back | `{ok, content, outcome, execution_id, request_id}` |
| What your app handles | 422 `invalid_params`, 409 `approval_required`, 424 `connection_required` |
| How long it takes | One tool run; `mode: async` over MCP for long ones |
| What you pay for | Counts toward tier POST limits; per-call price TBD by owner (TI-31) |
| What to check | `outcome`, `execution_id`, the trace ([Outcomes](/tools/outcomes)) |

**Before you build:** search first; never hard-code a tool id. Handle 409 `approval_required` and 424 `connection_required` before you ship.

### Start with Discovery

You do not know the right tool or agent yet, and search returns ranked cards you can read before you spend a call.

**How to start:** `GET /v1/discovery/search` with `q` (your need in plain words), `kind` (for example `agents`), `mode` `hybrid` (or `keyword`, `vector`), `fields` `summary` and `limit`; page with `offset`. [Setup details →](/discovery/core-concepts/search-modes) · [Build with Discovery →](/discovery/quickstart)

| | |
|---|---|
| What you send | `GET /v1/discovery/search?q=&kind=` |
| What you get back | `{cards, count, searchMethod, query}` |
| What your app handles | Picking an id, then reading the contract |
| How long it takes | One synchronous GET |
| What you pay for | GETs are not rate-limited; price TBD by owner |
| What to check | `status:active` on the card ([Card status](/discovery/core-concepts/card-status)) |

**Before you build:** call only cards with `status: active`; search filters on `active` by default, so widen `status` only on purpose.

### Start with Agents (sync)

One prompt in and one answer out on the same connection is the shortest path to a registry agent, and `stream: true` shows tokens as they arrive.

**How to start:** key `$PLUNGE_API_KEY`; `POST /v1/agents/llm-agent/execute` with `prompt`, `sync: true` (the default) and `max_tokens`; add `stream: true` for OpenAI chunks. [Setup details →](/agents/quickstart) · [Build with Agents →](/agents/quickstart)

| | |
|---|---|
| What you send | `POST /v1/agents/{id}/execute {prompt, sync: true}` (or `stream: true`) |
| What you get back | `{content, workflow_id, task_id, request_id}` or OpenAI SSE chunks |
| What your app handles | Holding the connection; keepalives |
| How long it takes | One agent run on one connection |
| What you pay for | The model tokens the agent uses, within the tier limit; price TBD by owner (TI-31) |
| What to check | `X-Execution-Id`, `content` ([Agents quickstart](/agents/quickstart)) |

**Before you build:** search first; never hard-code agent ids. `harness-agent` is not callable; loop agents run as a `type: harness` task.

### Start with Agents (async)

The answer can arrive later, so the call returns at once with a 202 and you collect the result without holding a connection open.

**How to start:** the Agents (sync) request with `sync: false`; store `workflow_id` and `task_id` from the 202; poll `GET /v1/agents/results/{workflowId}/{taskId}` until it stops answering 404 `not_ready`. [Setup details →](/agents/features/async-results) · [Build with Agents →](/agents/features/async-results)

| | |
|---|---|
| What you send | The same, with `sync: false` |
| What you get back | 202 `{workflow_id, task_id}`, then the results route |
| What your app handles | Polling `GET /v1/agents/results/{workflowId}/{taskId}`; 404 `not_ready` means keep polling |
| How long it takes | Returns immediately; the result lands later |
| What you pay for | As Agents (sync) |
| What to check | 409 `execution_failed`, 422 `empty_completion` ([Async results](/agents/features/async-results)) |

**Before you build:** treat 409 `execution_failed` and 422 `empty_completion` as final answers, not as "not ready".

### Start with Workflows

A fixed multi-step pipeline across several agents belongs in one CNL workflow, where a parallel block costs only its slowest child.

**How to start:** `POST /v1/workflows/execute` with `workflow` (a CNL YAML string), `input` and `format` (`json`, `yaml`, `markdown` or `text`); `POST /v1/workflows/execute-stream` for SSE; `POST /v1/workflows/{id}/execute` for a saved workflow. [Setup details →](/workflows/quickstart) · [Build with Workflows →](/workflows/quickstart)

| | |
|---|---|
| What you send | `POST /v1/workflows/execute {workflow, input, format}` or `execute-stream` |
| What you get back | `{success, status: completed or incomplete, workflow_id, final_task_id, content}` or SSE engine events |
| What your app handles | Parsing SSE events; the `incomplete` status |
| How long it takes | The sum of its sequential tasks; a parallel block costs its slowest child |
| What you pay for | Every model call inside the run; price TBD by owner (TI-31) |
| What to check | `status`, `final_task_id`, the trace ([Results and traces](/workflows/core-concepts/results-and-traces)) |

**Before you build:** search first; never hard-code agent ids. Read `status: incomplete` as a result to inspect, not as a success.

### Start with Missions

An agent chooses its own steps, but only inside the tools you allow and the iteration cap you set.

**How to start:** over MCP, `plungeai_run_mission` with `goal`, `allowed_tools`, `max_iterations` (1 to 50, default 8), `success_criteria` and `mode` (default `async`); over REST, a `type: harness` task in `POST /v1/workflows/execute`. [Setup details →](/missions/bounds) · [Build with Missions →](/missions/quickstart)

| | |
|---|---|
| What you send | `plungeai_run_mission {goal, allowed_tools, max_iterations}` or a `type: harness` task |
| What you get back | An execution id (async by default), then the result |
| What your app handles | Polling status; relaying "AWAITING USER APPROVAL" and calling `plungeai_continue`; a trust-fence "NEEDS APPROVAL" runs only from Studio |
| How long it takes | Minutes; resumable legs of about ten minutes |
| What you pay for | The model calls in each iteration; price TBD by owner (TI-31) |
| What to check | `continuation` in the status output ([Bounds](/missions/bounds)) |

**Before you build:** the mission tool has no REST endpoint yet (TI-24). Relay "AWAITING USER APPROVAL" to the user before `plungeai_continue`.

### Start with Scheduling

Recurring agents, queries, workflows and heartbeats run on a cron schedule with notifications, with no server of your own.

**How to start:** `plungeai_schedule` with `action: create`, `name`, `job_type` (`agent`, `query`, `workflow` or `heartbeat`), `target`, `schedule` (cron), `timezone` and `notify_channel`; then `action: get` and `action: runs`. [Setup details →](/scheduling/quickstart) · [Build with Scheduling →](/scheduling/quickstart)

| | |
|---|---|
| What you send | `plungeai_schedule {action: create, job_type, target, schedule}` |
| What you get back | `job_id`; runs on the cron schedule |
| What your app handles | Verifying with `get` and `runs`; notification channel ids |
| How long it takes | Runs on the schedule |
| What you pay for | Each run, priced like the job type it runs (TI-31) |
| What to check | Run history ([Runs](/scheduling/runs)) |

**Before you build:** MCP only today (TI-24). Verify every job you create with `get` and `runs`.

### Start with the MCP server

Your coding agent gets all 20 `plungeai_*` tools from one server, so you write no client code.

**How to start:** URL `https://mcp.plungeai.com/v1`; header `Authorization: Bearer $PLUNGE_API_KEY` (an `ozk_` key); transport Streamable HTTP; one command or deeplink per client. [Setup details →](/developer-tools/mcp/quickstart#client-installation) · [Build with the MCP server →](/developer-tools/mcp/plungeai-mcp)

| | |
|---|---|
| What you send | One install command or deeplink ([Overview](/getting-started/overview)) |
| What you get back | 20 `plungeai_*` tools, 5 resources, 1 prompt in your client |
| What your app handles | Nothing: the client calls the tools |
| How long it takes | One install step, then the client is ready |
| What you pay for | Whatever the tools run |
| What to check | `plungeai_whoami` ([MCP quickstart](/developer-tools/mcp/quickstart)) |

**Before you build:** keep the key in your user-level client config or shell, never in a repo file; call `plungeai_whoami` to confirm the connection.

## Have your agent choose an API

The `choose-your-plungeai-door` skill teaches your agent the same choice.

<Tabs>
<Tab title="Claude Code">
Download [choose-your-plungeai-door.zip](https://skills.plungeai.com/choose-your-plungeai-door.zip) and add it as a skill.
</Tab>
<Tab title="Codex">
Download [choose-your-plungeai-door.zip](https://skills.plungeai.com/choose-your-plungeai-door.zip) and add it with your Codex skill installer.
</Tab>
</Tabs>

<CardGroup cols={2}>
<Card title="View the skill" icon="sparkles" href="/skills/choose-your-plungeai-door">
The skill as a docs page.
</Card>
<Card title="Browse the source" icon="file-code">
Source repository: TBD by owner (TI-12).
</Card>
</CardGroup>

## Go straight to a quickstart

- [Call any model](/models/quickstart)
- [Run a tool](/tools/quickstart)
- [Run an agent](/agents/quickstart)
- [Run a workflow](/workflows/quickstart)
- [Run a bounded mission](/missions/quickstart)
- [Schedule a job](/scheduling/quickstart)
- [Discover capabilities](/discovery/quickstart)

<Note>
Nothing you choose here is saved.
</Note>