Getting started
Your first calls
One key, one agent call, one model call, one MCP connection.
Four steps from no account to a working agent call, model call and MCP connection. Every command reads its key from an environment variable; no example contains a key.
1. Get a key
- Create an ozk_ key
Sign in at https://dashboard.plungeai.com (opens in a new tab) and open Dashboard → One API → Keys. Name the key and pick an expiry: never, or 7, 30, 90, 180 or 365 days.
- Copy it once
The key starts with
ozk_and is shown exactly once. Create ansk-ocean-key on the same page for step 3. - Put both in your shell
export PLUNGE_API_KEY=ozk_... # execution planes and MCP export PLUNGE_MODEL_KEY=sk-ocean-... # models plane
Which key opens which route is on Authentication & keys.
2. Call an agent
One prompt to the registry agent llm-agent, answered on the same connection:
import os, requests
r = requests.post(
"https://api.plungeai.com/v1/agents/llm-agent/execute",
headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"},
json={"prompt": "In one sentence: what is a content delivery network?", "sync": True, "max_tokens": 60},
)
print(r.json()["content"])const r = await fetch('https://api.plungeai.com/v1/agents/llm-agent/execute', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt: 'In one sentence: what is a content delivery network?', sync: true, max_tokens: 60 }),
})
console.log((await r.json()).content)var client = java.net.http.HttpClient.newHttpClient();
var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://api.plungeai.com/v1/agents/llm-agent/execute"))
.header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY"))
.header("Content-Type", "application/json")
.POST(java.net.http.HttpRequest.BodyPublishers.ofString("{\"prompt\":\"In one sentence: what is a content delivery network?\",\"sync\":true,\"max_tokens\":60}"))
.build();
System.out.println(client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString()).body());curl -s -X POST https://api.plungeai.com/v1/agents/llm-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}'The answer is in content. Add "stream": true to get OpenAI-shaped chunks that end with data: [DONE].
3. Call a model
The models plane is OpenAI-compatible: point the OpenAI SDK at https://api.plungeai.com/v1 and pass a provider/model slug from GET /v1/models.
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["PLUNGE_MODEL_KEY"], base_url="https://api.plungeai.com/v1")
resp = client.chat.completions.create(
model="anthropic/claude-sonnet-4-6",
messages=[{"role": "user", "content": "Reply with exactly the word: pong"}],
max_tokens=16,
)
print(resp.choices[0].message.content)import OpenAI from 'openai'
const client = new OpenAI({ apiKey: process.env.PLUNGE_MODEL_KEY, baseURL: 'https://api.plungeai.com/v1' })
const resp = await client.chat.completions.create({
model: 'anthropic/claude-sonnet-4-6',
messages: [{ role: 'user', content: 'Reply with exactly the word: pong' }],
max_tokens: 16,
})
console.log(resp.choices[0].message.content)var client = java.net.http.HttpClient.newHttpClient();
var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://api.plungeai.com/v1/chat/completions"))
.header("Authorization", "Bearer " + System.getenv("PLUNGE_MODEL_KEY"))
.header("Content-Type", "application/json")
.POST(java.net.http.HttpRequest.BodyPublishers.ofString("{\"model\":\"anthropic/claude-sonnet-4-6\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with exactly the word: pong\"}],\"max_tokens\":16}"))
.build();
System.out.println(client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString()).body());curl -s https://api.plungeai.com/v1/chat/completions \
-H "Authorization: Bearer $PLUNGE_MODEL_KEY" -H 'Content-Type: application/json' \
-d '{"model":"anthropic/claude-sonnet-4-6","messages":[{"role":"user","content":"Reply with exactly the word: pong"}],"max_tokens":16}'The model field of the response names the model that served the request; after a failover it can differ from the one you asked for. These models-plane examples are verified against code, not live.
4. Connect your coding agent
One command connects Claude Code to the MCP server and its 20 plungeai_* tools:
claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 \
--header "Authorization: Bearer $PLUNGE_API_KEY" --scope user--scope user keeps the entry in ~/.claude.json, outside your repository; never use --scope project with a literal key. Run /mcp in a session to see plungeai, then ask: use plungeai_whoami to confirm my identity. Every other client is on the MCP quickstart.
Request ids and traces
Every response carries a server-minted x-request-id; quote it when you report a problem. To group several calls into one trace, send your own UUID in x-trace-id and read the trace with GET /v1/traces/{id}:
curl -s "https://api.plungeai.com/v1/traces/$(uuidgen)" -H "Authorization: Bearer $PLUNGE_API_KEY"A trace id you already used on an execution returns 409 duplicate_execution_id: send a fresh UUID each time.