Bots, executions, schedules, connections and the Agent Call door — over REST

One API 2.3.0 puts everything a saved bot needs on REST, under the same ozk_ key (Authorization: Bearer ozk_YOUR_KEY). The live contract is GET https://api.plungeai.com/v1/openapi.json (tags Workflows, Executions, Schedules, Triggers, Bots, Memory, Skills, Templates, Connections, Agent Call) — regenerate clients from it, never copy routes from this page. The classic planes (discovery, tools, agents, MCP, traces, models) are in route-map.md.

Rules on every route here: your rows only (another account's id answers 404 <thing>_not_found, same as a missing one) · JSON by default, YAML in (Content-Type: text/yaml) and out on the same routes; the format query or body field, or Accept, picks json | yaml | markdown | text (an unknown value is 400 invalid_format) · an error is {"error":{"code","message"}} rendered in that same format, and X-Error-Code: <code> is on every error: branch on the header · a storage or upstream failure is a generic 502 (storage_error, upstream_error, scheduler_error), never its text · a body over 1 MiB is 413 payload_too_large · reuse of an x-trace-id on an execute call is 409 duplicate_execution_id: send a fresh UUID.

Saved workflows and bots

The YAML is validated and linted for its kind before anything is written — on create, PATCH and restore: a bot is ONE type: harness task on agent: one-agent; a refusal is 422 invalid_workflow with errors and warnings, and the row is unchanged. A missing or malformed field is 422 invalid_params.

Bot policy, workspace, inbox, chats, groups (owner only)

The engine loads the stored policy once per run, so every door (REST, MCP, CLI, Studio, schedules, triggers, chat) stops at the same caps and holds. A run that reaches its cap says so in its result.

Executions (every run, whichever door started it)

By-id reads of a run made on a customer's behalf (POST /v1/execute with on_behalf_of) take ?on_behalf_of=<customer id>: GET /v1/executions/{id}, GET /v1/executions/{id}/output and GET /v1/executions/{id}/files only (a bad id is 400 invalid_on_behalf_of).

Schedules, triggers, hooks

Every trigger call names the schedule with schedule_id (body for mint and rotate, query for list and delete); a secret is shown once, on mint, and the mint answer is never cached; 404 trigger_not_found for a token not on that schedule, 404 schedule_not_found for a schedule that is not yours. A scheduler failure is 502 scheduler_error; a refused setting is 400 invalid_request.

Connections — your keys, or your customer's

provider is a connector id (google, azure for Microsoft 365, github, slack, stripe, …). A connection-tier agent with no connection answers 424 connection_required (or credential_required) with error.connect = {provider, method: oauth|api_key|wallet, link} naming where to connect it. on_behalf_of (1–128 chars of A-Za-z0-9_.-, no ..; 400 invalid_on_behalf_of otherwise) is accepted on POST /v1/execute among the execute routes: the run reads the credential connected under that customer id. /v1/workflows/{id}/execute, /v1/agents/{id}/execute and /v1/tools/{id}/execute refuse it with 400 invalid_body. 503 connections_unavailable where connections are off.

Other errors you will meet

503 not_enabled (bindings, bot groups, channel pairing before their migration or deploy) · 409 binding_limit, 409 unbind_failed, 422 not_paired (bind a chat you did not pair) · 409 name_taken, 422 invalid_name / invalid_members (bot groups) · 502 upstream_error (a store failed). The live spec lists each per operation.

Memory, skills, templates

Detail: plungeai-memory, plungeai-skills-plugins, plungeai-discovery.

The Agent Call door — POST /v1/execute (level 3)

The body (JSON, or YAML for any other Content-Type) is the program, and the call always runs through the engine, so a saved bot keeps its stored policy:

Root keys that steer the call and never reach an agent: format, input, inputs, user_context, stream (true answers as SSE), dry_run (200 {dry_run, kind, agent, tasks, warnings}: no run, no row, no spend), on_behalf_of. Answers carry x-ocean-agent, x-ocean-tasks, x-ocean-version (<n>, live or inline). A run answers {success, workflow_id, final_task_id, request_id, content}.

curl -s -X POST https://api.plungeai.com/v1/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"agent":"<saved bot id>@3","input":"Check the pricing page","dry_run":true}'

The per-resource execute routes (/v1/workflows/{id}/execute, /v1/agents/{id}/execute) answer exactly as before: the three levels all stay. Start with level 2; use the door when the body is the program.