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.

In your tool

plungeai-in-replit

Connect Replit Agent to PlungeAI (Ocean Studio) over MCP — the one-click install-page link, the Integrations → MCP Servers form, keeping the Agent's MCP key separate from a deployed app's Replit Secret, and a plungeai_whoami + plungeai_list_agents verify. Use when the user is in Replit and says connect / install / set up PlungeAI, mentions MCP Servers or Replit Secrets, or an app built in Replit 401s against PlungeAI. For another editor use its plungeai-in-<tool> skill; for an unlisted but MCP-capable client use plungeai-mcp-setup's generic client config.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

Replit talks to PlungeAI over the Streamable HTTP MCP server at https://mcp.plungeai.com/v1 — for the Agent while building. Apps the Agent ships call the One API (https://api.plungeai.com) directly with their own key in Replit Secrets.

Prerequisites

Connect (once)

One click

  1. Open https://mcp.plungeai.com/install (opens in a new tab), type the ozk_ key into the box at the top, then click Add to Replit — the integration imports with its Authorization header. Clicked without the key, add the header afterwards under the integration's Advanced settings.

By hand

Integrations → MCP Servers → + Add MCP server: Display name PlungeAI, Server URL https://mcp.plungeai.com/v1, then Advanced settings → custom header Authorization = Bearer ozk_YOUR_KEY.

The integration is account-level: the Agent gets the plungeai_* tools across all your projects, not just the current Repl.

Verify

  1. Ask the Agent: "use plungeai_whoami to confirm my identity" → an identity card.
  2. From the Repl shell: curl -H "Authorization: Bearer $PLUNGEAI_API_KEY" https://api.plungeai.com/v1/agents → HTTP 200 JSON (proves a Repl Secret is set and valid).
  3. "use plungeai_list_agents to search 'web search'" → live results from the active agent catalog.

Quirks

  • Two key locations — never mixed: the MCP integration's header (for the Agent) and Replit Secrets as PLUNGEAI_API_KEY (for the Repl's own code). Never in source files, .replit, or replit.nix.
  • A workspace app that 401s after deploy → check that the deployment's secrets carry PLUNGEAI_API_KEY too.
  • Tool approval: a tool that requires confirmation prompts before it runs. Money-verb PlungeAI operations still pause with a structured needs_approval outcome regardless — relay it, then plungeai_continue.
  • Standard split when the Agent is asked to "build an app that uses PlungeAI": it uses MCP to discover and test the right agent, then writes app code that calls the One API with the key from Replit Secrets.

What the Agent should know when it writes app code (One API 2.3.0)

The MCP integration serves the Agent while it builds; the Repl's own code calls the One API with PLUNGEAI_API_KEY from Replit Secrets. Put this block in replit.md (Agent reads it on every request; the file is part of the project, so never the key) or paste it into the prompt. The minimal saved-workflow body (workflow: / tasks: YAML) is in plungeai-api-setup.

PlungeAI One API 2.3.0. Base URL https://api.plungeai.com. Spec: GET /v1/openapi.json (no auth) - never invent a route.
AUTH: Authorization: Bearer ozk_YOUR_KEY on every call; key in an env var, server side only. When a connector attaches auth, NEVER add your own Authorization header.
ME: GET /v1/whoami -> {user_id, via, tier, key_label}. GET /v1/key -> {data:{label, limit, usage, rate_limit}}.
FIND (never from memory): GET /v1/discovery/search?q=<capability>&kind=agents -> {cards} (without kind, skill cards come first). POST /v1/discovery/resolve {task}. GET /v1/agents. GET /v1/tools. GET /v1/tools/{id} = the contract.
DOOR 1, one agent or tool: POST /v1/agents/{id}/execute {prompt|input, sync?, model?} -> 200 {content, workflow_id, task_id, request_id}.
  POST /v1/tools/{id}/execute {operation, params} -> {ok, content, outcome}; 422 invalid_params echoes the contract.
DOOR 2, saved workflow or bot: POST /v1/workflows/{id}/execute {input?, inputs?} -> {success, workflow_id, final_task_id, request_id, content}, synchronous.
  POST /v1/workflows/{id}/execute-stream = SSE. Inline YAML: POST /v1/workflows/execute. No content? GET /v1/workflows/results/{workflowId}/{taskId} (taskId = final_task_id).
DOOR 3, Agent Call: POST /v1/execute, the body is the program: {agent:"<saved id>[@n]", input} or {workflow:{...}} or {tasks:[...]}. dry_run:true plans without running;
  on_behalf_of:"<customer id>" uses that customer's connections.
ASYNC: POST /v1/agents/{id}/execute {sync:false} -> 202 {workflow_id, task_id, request_id}; redeem GET /v1/agents/results/{workflowId}/{taskId} -> {content}; 404 not_ready = poll, 2s+.
EXECUTIONS: the run id is the body's workflow_id (also the x-execution-id header, and your x-trace-id UUID if you sent one; replaying one is 409 duplicate_execution_id).
  GET /v1/executions (source, status, workflow_id). GET /v1/executions/{id}: running | completed | incomplete | failed | cancelled | needs_input | needs_approval.
  GET /v1/executions/{id}/output -> {content, steps}. GET /v1/executions/{id}/files. GET /v1/executions/{id}/conversation. DELETE /v1/executions/{id}. GET /v1/executions/{id}/stream = SSE.
  POST /v1/executions/{id}/continue {answer | approve, allow_scope: once|run|always}. POST /v1/executions/{id}/followup {text}. POST /v1/executions/{id}/cancel.
  POST /v1/executions/{id}/steer {text} queues a message for a live run (202), else 409 execution_finished.
WORKFLOWS: GET|POST /v1/workflows. GET|PATCH|DELETE /v1/workflows/{id}. GET|POST /v1/workflows/{id}/versions. POST /v1/workflows/{id}/versions/{versionId}/restore.
  Save needs {name, kind, yaml}; kind = workflow|agent|bot|campaign. GET /v1/workflows lists every kind unless ?kind=bot (or campaign). 422 invalid_workflow lists errors, writes nothing.
SCHEDULES: POST /v1/schedules {name, schedule, workflow_id, timezone?, parameters?}; schedule = a cron, or "@once" with run_at (ISO-8601 WITH a UTC offset, in the future);
  400 run_at_required | run_at_past. GET /v1/schedules. GET|PATCH|DELETE /v1/schedules/{id}. GET /v1/schedules/{id}/runs (execution_id per run).
  POST /v1/schedules/{id}/run. POST /v1/schedules/{id}/pause. POST /v1/schedules/{id}/resume. POST /v1/schedules/{id}/wake {note?, in?} fires it once, now or later.
TRIGGERS (every call names schedule_id; a secret is shown once): GET|POST /v1/triggers/webhook. DELETE /v1/triggers/webhook/{token}. POST /v1/triggers/webhook/{token}/rotate.
  The same four under /v1/triggers/email {allowed_from}. GET|POST /v1/triggers/hooks {url, events}. DELETE /v1/triggers/hooks/{id}.
PERMISSIONS: GET|PUT /v1/workflows/{id}/permissions {classes:{send|write|pay|delete: allow|ask|deny|hand_off}, locks, budget_usd_run, budget_usd_month}; locks need a team admin (403 lock_admin_required).
BOT DATA: GET /v1/workflows/{id}/workspace-files. GET /v1/workflows/{id}/workspace-files/download?path=. GET /v1/workflows/{id}/inbox. GET|POST /v1/workflows/{id}/bindings {channel, sender_id}.
  DELETE /v1/workflows/{id}/bindings/{channel}/{sender_id}. GET /v1/channels. POST /v1/channels/pair {channel}.
  GET|POST /v1/bot-groups {name, members = 2-6 of your bot ids}. PUT|DELETE /v1/bot-groups/{id}. GET /v1/bot-groups/{id}/thread.
MEMORY: GET /v1/memory/recall?q=. POST /v1/memory/remember {text, scope: memory|user}. POST /v1/memory/forget {id | text}. GET /v1/memory/runs?q= (q required). GET /v1/memory/runs/{id}.
SKILLS: GET /v1/skills. POST /v1/skills/learn {name, body} saves the body you send (it does not distill a URL). DELETE /v1/skills/{id}.
TEMPLATES: GET /v1/templates?kind=workflow|agent|bot. GET /v1/templates/{id}. POST /v1/templates/{id}/use {name?} -> 201 {workflow}.
CONNECTIONS: GET /v1/connections. POST /v1/connections/{provider} {api_key, on_behalf_of?}. DELETE /v1/connections/{provider}. POST /v1/connections/{provider}/link -> {url, expires_at}.
MODELS (OpenAI-shaped, Bearer only): GET /v1/models. POST /v1/chat/completions. POST /v1/embeddings.
TRACES: GET /v1/traces/{id}, id = the run's workflow_id.
LISTS: {workflows|executions|schedules|cards:[...], total, limit, offset, has_more}; POST /v1/schedules -> {schedule}.
ERRORS: {"error":{"code","message"}} plus an X-Error-Code header. 400 validation; 401 unauthorized; 403 refused | agent_not_active; 404 <thing>_not_found (a stranger's id too);
  409 approval_required, or not_paused | execution_finished | duplicate_execution_id | name_taken; 422 invalid_params; 429 rate_limited + Retry-After; 502/503 retry once.
  424 connection_required | credential_required carries error.connect {provider, method, link}: connect via POST /v1/connections/{provider} or its /link.
FENCES: 403 refused is final - surface it, never retry. 409 approval_required is a human boundary - never approve for the user. tools/{id}/execute: a human approves in Studio, then re-issue.
  A paused agent reply: re-send with approved:true plus its action_token (both). A run reading needs_approval: POST /v1/executions/{id}/continue, never the original call.

Where next

  • Operating the plungeai_* tools once connected: plungeai-mcp-setup.
  • Writing app code that calls https://api.plungeai.com directly: plungeai-api-setup.
  • Picking MCP vs the One API for a given job: choose-your-plungeai-door.
  • An unlisted but MCP-capable client, or the shared connect concepts (native remote vs. stdio bridge, key hygiene): plungeai-mcp-setup.
  • Full guide: https://mcp.plungeai.com/docs#3-connecting-clients (opens in a new tab)

Planned: TI-34

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