Getting started
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 · Fallback, cheapest or fastest → Model routing |
| Run one capability: search, scrape, send, look up | Do you already know which tool? | Yes → Tools · No → 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) · Later → 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 · Yes → Missions |
| Run something on a schedule: every hour, every day, on a condition | none | Scheduling |
| Work from my coding agent: Claude Code, Cursor, Codex, VS Code | none | the MCP server |
The interactive chooser is planned (TI-74); until then this table and the results below carry the same data.
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 → · Build with Chat completions →
| 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) |
| What to check | x-request-id, usage, served model (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 → · Build with Model 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 → · Build with Tools →
| 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) |
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 → · Build with Discovery →
| 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) |
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 → · Build with Agents →
| 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) |
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 → · Build with Agents →
| 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) |
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 → · Build with Workflows →
| 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) |
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 → · Build with Missions →
| 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) |
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 → · Build with Scheduling →
| 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) |
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 → · Build with the MCP server →
| What you send | One install command or deeplink (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) |
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.
Download choose-your-plungeai-door.zip (opens in a new tab) and add it as a skill.
Download choose-your-plungeai-door.zip (opens in a new tab) and add it with your Codex skill installer.
The skill as a docs page.
Source repository: TBD by owner (TI-12).
Go straight to a quickstart
- Call any model
- Run a tool
- Run an agent
- Run a workflow
- Run a bounded mission
- Schedule a job
- Discover capabilities
Nothing you choose here is saved.