SDK & codegen — typed clients, snippets, and the AGENTS.md block

npx openapi-typescript https://api.plungeai.com/v1/openapi.json -o src/plungeai-schema.d.ts
npm install openapi-fetch

import createClient from 'openapi-fetch'
import type { paths } from './plungeai-schema'

export const plungeai = createClient<paths>({
  baseUrl: 'https://api.plungeai.com',
  headers: { Authorization: `Bearer ${process.env.PLUNGEAI_API_KEY}` },
})

BASE=https://api.plungeai.com
AUTH='Authorization: Bearer ozk_YOUR_KEY'

curl -s $BASE/health                                            # liveness, no auth
curl -s $BASE/v1/openapi.json | head -50                        # live contract, no auth
curl -s "$BASE/v1/discovery/search?q=web%20search&limit=3" -H "$AUTH"
curl -s "$BASE/v1/tools?limit=5" -H "$AUTH"
curl -s $BASE/v1/tools/brave-agent -H "$AUTH"                   # contract (id from discovery)
curl -s -X POST $BASE/v1/agents/one-agent/execute -H "$AUTH" \
  -H 'Content-Type: application/json' -d '{"prompt":"Say: ok"}'
curl -s $BASE/v1/traces/REQUEST_ID_FROM_ABOVE -H "$AUTH"
curl -s "$BASE/v1/workflows?kind=bot&limit=5" -H "$AUTH"          # your saved bots
curl -s -X POST $BASE/v1/execute -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"agent":"<bot id>@1","input":"hi","dry_run":true}'        # the Agent Call door, planned not run
curl -s "$BASE/v1/executions?limit=3" -H "$AUTH"

## PlungeAI One API

This app calls the PlungeAI One API at https://api.plungeai.com.
Official SDKs (env `PLUNGEAI_API_KEY`): `@plungeai/one-api`, `plungeai` (PyPI), `github.com/PlungeAI/plungeai-go`, `plungeai` (crates.io).

- Auth: `Authorization: Bearer $PLUNGEAI_API_KEY` (an `ozk_` platform key) for
  /v1/discovery, /v1/tools, /v1/agents, /v1/workflows, /v1/executions, /v1/schedules,
  /v1/triggers, /v1/bot-groups, /v1/channels, /v1/connections, /v1/memory, /v1/skills,
  /v1/templates, /v1/execute, /v1/mcp, /v1/traces.
  The OpenAI-compatible models plane (/v1/chat/completions, /v1/embeddings,
  /v1/models) takes the same key, as `Authorization: Bearer` only.
  Keys live in env vars only — never commit or log them.
- Live contract: `GET /v1/openapi.json`. Live catalog: `GET /v1/agents`,
  `GET /v1/discovery/search?q=...`. Never hardcode agent/tool/model ids or
  counts — discover them, and re-discover on 404 `unknown_tool` /
  `workflow_not_found`.
- Sync vs async: agent execute defaults to sync; `sync:false` returns 202 +
  `{workflow_id, task_id}` — poll `GET /v1/agents/results/:wf/:task`
  (404 `not_ready` is normal in-flight, back off 2s+).
- HARD RULE — trust fences: `403 refused` (a gated/money verb refused
  outright) and `409 approval_required` (a human must approve before the
  action runs — this is implemented and produced today, not a placeholder)
  are both final for now — surface them to the user; never retry, rephrase,
  or route around a `403 refused`. For `409`, a human approves, by shape:
  a 409 from a tool call → Ocean Studio, then re-issue the identical request;
  a paused agent turn → re-send with `approved: true` + its `action_token`;
  a run reading `needs_approval` → `POST /v1/executions/{id}/continue`
  `{"approve": true}` (MCP `plungeai_continue`) — the held action runs inside
  that call, so do NOT re-issue the original request afterwards.
  A separate, unrelated `403 agent_not_active` (a parked/inactive agent id)
  is a lifecycle state, not a fence — re-discover a fresh id and retry with
  that instead.
- `422 invalid_params` echoes the tool contract — self-correct once, then stop.
- Errors carry `X-Error-Code`; branch on it. Send a fresh UUID as `x-trace-id` (a reused one is
  `409 duplicate_execution_id`). Bots, schedules, executions and the `POST /v1/execute` door:
  `GET /llms-full.txt` §16.
- Rate limits: execution-plane `429 rate_limited` carries `Retry-After` —
  honour it. The models plane's separate `429 rate_limit_exceeded` has no
  Retry-After — use a fixed ~1s backoff there instead.
- 502 `upstream_error` / 500 `internal_error` can come from any route —
  retry once with backoff.
- Correlation: send `x-trace-id` on writes; debug via `GET /v1/traces/:id`.
- Full docs for agents: `GET https://api.plungeai.com/llms-full.txt`.