For AI agents: a documentation index is available at https://www.plungeai.com/docs/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. Setup instructions for agents are at https://www.plungeai.com/docs/agents.md. One ozk_ key opens every plane, models included.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.

One API

Quickstart

Thirty-five calls you can paste into a terminal and run as they are. Every ozk_ sample below is live-verified on the build date (the verifier runs the ones marked in the source; the create/run/delete ones mutate state and are run by hand). Two minutes of setup:

  1. Get an ozk_ key: Dashboard → One API → Keys (https://dashboard.plungeai.com), copy it once.
  2. Export it, and paste the four helpers once per terminal. live prints a stream's text as it arrives (OpenAI-shaped chunks or engine token frames), frames prints the raw SSE, mcp sends one MCP call, mcptext prints its rendered answer.
export PLUNGE_API_KEY=ozk_…            # paste your key here once per terminal

live() { python3 -u -c '
import sys, json
for line in iter(sys.stdin.readline, ""):
    if not line.startswith("data:"): continue
    b = line[5:].strip()
    if b == "[DONE]": break
    try: d = json.loads(b)
    except Exception: continue
    t = ((d.get("choices") or [{}])[0].get("delta") or {}).get("content") if "choices" in d else d.get("delta")
    if t: sys.stdout.write(t); sys.stdout.flush()
print()'; }
frames() { grep --line-buffered -E '^(event|data|id):'; }
mcp() { curl -sN https://api.plungeai.com/v1/mcp -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d "$1"; }
mcptext() { python3 -c 'import sys,json;raw=sys.stdin.read();fr=[l[5:].strip() for l in raw.splitlines() if l.startswith("data:")];d=json.loads(fr[-1] if fr else raw);r=d.get("result") or d;print(r["content"][0]["text"] if isinstance(r,dict) and r.get("content") else json.dumps(r,indent=1))'; }
uuid() { grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' | head -1; }

The wires are independent: send JSON or YAML, get json, yaml, markdown or text back (format in the body, ?format= on the URL, or an Accept header — see Workflows plane § response formats). Streams have one fixed shape per plane. The same $PLUNGE_API_KEY opens every plane, the models plane (OpenAI SDK) included, which is at the end of this chapter.

1.1 Your first three calls

An agent, synchronous, JSON in → JSON out:

curl -s -X POST https://api.plungeai.com/v1/agents/one-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 same agent, streamed — OpenAI-shaped chunks, ends with data: [DONE]:

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Write two markdown bullets about glaciers.","provider":"openai","model":"gpt-4o-mini","max_tokens":100,"stream":true}'

The same agent, YAML in → Markdown out:

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
prompt: "In two markdown bullets, what does a content delivery network do? Bold the key term in each."
provider: openai
model: gpt-4o-mini
maxTokens: 150
sync: true
format: markdown
EOF

The same first call in Python and TypeScript (plain HTTP, no SDK):

import requests
r = requests.post(
    "https://api.plungeai.com/v1/agents/one-agent/execute",
    headers={"Authorization": "Bearer <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/one-agent/execute', {
  method: 'POST',
  headers: { Authorization: 'Bearer <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)

1.2 YAML in → Markdown out (10)

A1 — direct agent call, sync: true + format: markdown. The body is the Markdown itself, then --- and an execution: footer with the run id.

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
prompt: "Reply with exactly this markdown line: **yaml-md-ok**"
provider: openai
model: gpt-4o-mini
maxTokens: 24
sync: true
format: markdown
EOF

A2 — format: text: the bare content, no footer.

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
prompt: "Reply with exactly this markdown line: **yaml-md-ok**"
provider: anthropic
model: claude-sonnet-4-5-20250929
maxTokens: 24
sync: true
format: text
EOF

A3 — no format: in the body; ask with the Accept header. Precedence: body format → ?format= → Accept → mirror of the request Content-Type (YAML in, YAML out).

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' -H 'Accept: text/markdown' --data-binary @- <<'EOF'
prompt: "Reply with exactly this markdown line: **yaml-md-ok**"
provider: gemini
maxTokens: 24
sync: true
EOF

A4 — stream: true, Markdown streamed live. format: never applies to a stream; the Markdown is what the model writes and live joins the delta.content pieces (what Studio and the CLI do).

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF' | live
prompt: "Reply with exactly: stream-ok"
provider: openai
model: gpt-4o-mini
maxTokens: 24
stream: true
EOF

A5 — the same stream as raw frames.

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF' | frames
prompt: "Name two lakes in one markdown bullet each."
provider: openai
model: gpt-4o-mini
maxTokens: 80
stream: true
EOF

A6 — a tool, operation: + its fields bare at the root → a Markdown document (Brave news). (params: still wraps them if you prefer.)

curl -s -X POST https://api.plungeai.com/v1/tools/brave-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
operation: news
query: "Cloudflare Workers"
freshness: pw
count: 3
format: markdown
EOF

A7 — a tool → Markdown (weather forecast). Requires nothing beyond the key.

curl -s -X POST https://api.plungeai.com/v1/tools/weather-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
operation: forecast
params:
  lat: 43.697
  lon: -114.352
  units: imperial
  cnt: 8
format: markdown
EOF

A8 — a whole workflow document with format: markdown and input: → the result as Markdown. format:, input: and inputs: next to workflow: are the envelope fields (the same ones Studio sends); {input} is substituted. Without format: you get the YAML pointer envelope (ids only).

curl -s -X POST https://api.plungeai.com/v1/workflows/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF'
format: markdown
input: "wf-md-ok"
workflow:
  name: md-inline
  tasks:
    - type: task
      id: t1
      agent: one-agent
      maxTokens: 40
      prompt: "Reply with exactly this markdown line: **{input}**"
EOF

A9 — the same workflow on the stream. The gateway follows the provider's stream_url for you and injects the deltas as event: token frames — one connection. Pipe through frames to see the named engine events around them.

curl -sN -X POST https://api.plungeai.com/v1/workflows/execute-stream \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF' | live
input: "wf-md-ok"
workflow:
  name: md-stream
  tasks:
    - type: task
      id: t1
      agent: one-agent
      provider: openai
      model: gpt-4o-mini
      maxTokens: 40
      prompt: "Reply with exactly this markdown line: **{input}**"
EOF

A10 — MCP: the YAML travels inside the JSON-RPC frame; the answer is Markdown by default.

mcp '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_workflow","arguments":{"user_request":"yaml in, markdown out","mode":"sync","input":"wf-md-ok","workflow_yaml":"workflow:\n  name: md-mcp\n  tasks:\n    - type: task\n      id: t1\n      agent: one-agent\n      maxTokens: 40\n      prompt: \"Reply with exactly this markdown line: **{input}**\""}}}' | mcptext

1.3 JSON in → JSON out (10)

B1 — agent, sync → JSON envelope (content, workflow_id, task_id, request_id).

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"In one sentence: what is a Cloudflare Worker?","sync":true,"max_tokens":60}' | python3 -m json.tool

B2 — the generation knobs: provider, model, temperature, max_tokens. The Markdown sits inside the JSON content string.

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"List three facts about the moon as a markdown list.","provider":"openai","model":"gpt-4o-mini","temperature":0,"max_tokens":120,"sync":true}' | python3 -m json.tool

B3 — stream: true → OpenAI-shaped chunk stream, raw. An OpenAI SDK streaming client works against this URL.

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Write two markdown bullets about glaciers.","provider":"openai","model":"gpt-4o-mini","max_tokens":100,"stream":true}' | frames

B4 — the same stream, text only, live.

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Reply with exactly: json-stream-ok","provider":"openai","model":"gpt-4o-mini","max_tokens":24,"stream":true}' | live

B5 — a tool, JSON body (operation + params) → JSON envelope.

curl -s -X POST https://api.plungeai.com/v1/tools/exa-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"operation":"search","params":{"query":"latest developments in quantum computing","numResults":3,"searchType":"auto"}}' | python3 -m json.tool | head -40

B6 — a tool's invocation contract (operations, params, gates, examples).

curl -s https://api.plungeai.com/v1/tools/brave-agent -H "Authorization: Bearer $PLUNGE_API_KEY" | python3 -m json.tool | head -60

B7 — a workflow as a JSON object, sync → JSON pointer, then the result as JSON.

R=$(curl -s -X POST https://api.plungeai.com/v1/workflows/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"workflow":{"name":"json-wf","tasks":[{"type":"task","id":"t1","agent":"one-agent","maxTokens":60,"prompt":"Explain {input} in one sentence."}]},"input":"edge computing"}')
echo "$R" | python3 -m json.tool
WF=$(echo "$R" | python3 -c 'import sys,json;print(json.load(sys.stdin)["workflow_id"])')
curl -s "https://api.plungeai.com/v1/workflows/results/$WF/t1" -H "Authorization: Bearer $PLUNGE_API_KEY" | python3 -m json.tool

B8 — a workflow JSON body on the stream → the engine's named SSE events, every data: is JSON: request_received → workflow_loaded → workflow_started → task_dispatched → streaming_started → token… → task_completed → workflow_completed → workflow_result.

curl -sN -X POST https://api.plungeai.com/v1/workflows/execute-stream \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"workflow":{"name":"json-stream","tasks":[{"type":"task","id":"t1","agent":"one-agent","provider":"openai","model":"gpt-4o-mini","maxTokens":80,"prompt":"Explain {input} in two markdown bullets."}]},"input":"edge computing"}' | frames

B9 — discovery: hybrid search over the capability registry → JSON cards.

curl -s "https://api.plungeai.com/v1/discovery/search?q=web+search&kind=agents&limit=3" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" | python3 -m json.tool | head -40

B10 — MCP with format: "json": the tool text is a JSON document and structuredContent carries the same object. MCP's format enum is markdown | json; the JSON-RPC exchange arrives as SSE frames (progress first, the result last) — MCP does not token-stream.

mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"plungeai_execute_agent","arguments":{"user_request":"json please","agent":"one-agent","prompt":"Reply with exactly: mcp-json-ok","format":"json"}}}' | sed -n 's/^data: //p' | tail -1 | python3 -m json.tool

1.4 Mixed wires (2)

M1 — JSON in → Markdown out.

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Two markdown bullets about tides.","provider":"openai","model":"gpt-4o-mini","max_tokens":100,"sync":true,"format":"markdown"}'

M2 — YAML in → JSON out.

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF' | python3 -m json.tool
prompt: "One sentence about tides."
provider: openai
model: gpt-4o-mini
maxTokens: 60
sync: true
format: json
EOF

1.5 Run, then create and run — always streaming (10)

These create rows in your account (the same D1 rows Studio writes) and delete them at the end. Run them top to bottom in one terminal: the ids flow from one step to the next.

C1 — run an agent, streamed (Anthropic this time).

curl -sN -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' --data-binary @- <<'EOF' | live
prompt: "Reply with exactly: run-ok"
provider: anthropic
model: claude-sonnet-4-5-20250929
maxTokens: 24
stream: true
EOF

C2 — CREATE a workflow (plungeai_workflow create, kind: workflow).

STAMP=$(date -u +%H%M%S)
R=$(mcp "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"plungeai_workflow\",\"arguments\":{\"user_request\":\"create\",\"action\":\"create\",\"kind\":\"workflow\",\"name\":\"Quickstart workflow $STAMP\",\"yaml\":\"workflow:\\n  name: quickstart-workflow\\n  tasks:\\n    - type: task\\n      id: t1\\n      agent: one-agent\\n      provider: openai\\n      model: gpt-4o-mini\\n      maxTokens: 160\\n      prompt: \\\"Write three markdown bullets about {input}.\\\"\"}}}")
echo "$R" | mcptext
WF_ID=$(echo "$R" | mcptext | uuid); echo "WF_ID=$WF_ID"

C3 — run it, streamed as text.

curl -sN -X POST "https://api.plungeai.com/v1/workflows/$WF_ID/execute-stream" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' -d '{"input":"the Rhine"}' | live

C4 — CREATE a bot (kind: bot).

R=$(mcp "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"plungeai_workflow\",\"arguments\":{\"user_request\":\"create\",\"action\":\"create\",\"kind\":\"bot\",\"name\":\"Quickstart bot $STAMP\",\"yaml\":\"workflow:\\n  name: quickstart-bot\\n  tasks:\\n    - type: task\\n      id: t1\\n      agent: one-agent\\n      provider: openai\\n      model: gpt-4o-mini\\n      maxTokens: 160\\n      prompt: \\\"You are a friendly bot. Answer in markdown: {input}\\\"\"}}}")
echo "$R" | mcptext
BOT_ID=$(echo "$R" | mcptext | uuid); echo "BOT_ID=$BOT_ID"

C5 — run the bot, streamed as text.

curl -sN -X POST "https://api.plungeai.com/v1/workflows/$BOT_ID/execute-stream" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"input":"What should I pack for a week in Iceland in October?"}' | live

C6 — CREATE an agentic agent (kind: agent): a harness mission on one-agent with a tool fence and an iteration cap.

R=$(mcp "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"plungeai_workflow\",\"arguments\":{\"user_request\":\"create\",\"action\":\"create\",\"kind\":\"agent\",\"name\":\"Quickstart agentic agent $STAMP\",\"yaml\":\"workflow:\\n  name: quickstart-agentic-agent\\n  tasks:\\n    - type: harness\\n      id: run\\n      agent: one-agent\\n      goal: \\\"Explain {input} in three markdown bullets, then call task_complete with the bullets.\\\"\\n      mission: \\\"You are a concise explainer. Answer in Markdown only.\\\"\\n      allowed_tools: [task_complete]\\n      max_iterations: 3\"}}}")
echo "$R" | mcptext
AGENT_ID=$(echo "$R" | mcptext | uuid); echo "AGENT_ID=$AGENT_ID"

C7 — run the agentic agent, streamed. A harness run streams its engine events (task_dispatched → task_completed → workflow_completed); read the final Markdown from the results route with the workflow_id in the frames.

curl -sN -X POST "https://api.plungeai.com/v1/workflows/$AGENT_ID/execute-stream" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"input":"how a harness bounds an agent run"}' | frames

C8 — BUILD a workflow from a goal (plungeai_build_workflow — the LLM writes the CNL).

R=$(mcp '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"plungeai_build_workflow","arguments":{"user_request":"build it","goal":"Search the web for the latest Cloudflare Workers news and summarise the top three items in markdown bullets"}}}')
echo "$R" | mcptext
BUILT_ID=$(echo "$R" | mcptext | uuid); echo "BUILT_ID=$BUILT_ID"

C9 — run the built workflow, streamed.

curl -sN -X POST "https://api.plungeai.com/v1/workflows/$BUILT_ID/execute-stream" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' -d '{"input":"Cloudflare Workers"}' | frames

C10 — list what you created, delete it, prove it is gone.

mcp '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"plungeai_list_workflows","arguments":{"user_request":"mine","search":"Quickstart "}}}' | mcptext
for id in $WF_ID $BOT_ID $AGENT_ID $BUILT_ID; do
  mcp "{\"jsonrpc\":\"2.0\",\"id\":8,\"method\":\"tools/call\",\"params\":{\"name\":\"plungeai_workflow\",\"arguments\":{\"action\":\"delete\",\"workflow_id\":\"$id\"}}}" | mcptext
done
mcp '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"plungeai_list_workflows","arguments":{"user_request":"verify","search":"Quickstart "}}}' | mcptext

1.6 The models plane with the OpenAI SDK

The models plane is OpenAI-compatible and takes the same ozk_ key as every other plane. Point the official SDK at https://api.plungeai.com/v1 and pass a provider/model slug from GET /v1/models.

from openai import OpenAI
client = OpenAI(api_key="<PLUNGE_API_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_API_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)
curl -s https://api.plungeai.com/v1/chat/completions \
  -H "Authorization: Bearer $PLUNGE_API_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 response model is the slug that actually served the request — after a failover it can differ from what you asked for. Add "stream": true for SSE. Ordered fallback (models[]), sort, @preset/<slug>, guardrails and the response cache are in Models plane.

1.7 Request ids and traces

Every response echoes a server-minted x-request-id. Send your own UUID x-trace-id to correlate several calls, and read the persisted trace at GET /v1/traces/{id} (Traces & observability). An id none of your calls used — or another account's — is 404 not_found:

curl -s "https://api.plungeai.com/v1/traces/$(uuidgen)" -H "Authorization: Bearer $PLUNGE_API_KEY"

Where to next: Tools plane for contracts and the trust fence, Agents plane for every body field, Workflows plane for the CNL primer, Streaming for the SSE vocabulary, MCP plane to use the platform from Claude, Cursor or any MCP client.

Planned: TI-34

The docs assistant is not available yet. You can hand these docs to your own assistant instead.