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.

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, format= or Accept picks json | yaml | markdown | text · errors are {"error":{"code","message"}} · a storage or upstream failure is a generic 502, never its text.

Saved workflows and bots

The YAML is validated and linted for its kind before anything is written: a bot is ONE type: harness task on agent: one-agent; a refusal is 422 invalid_workflow with errors.

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)

Schedules, triggers, hooks

Every trigger call names the schedule with schedule_id; a secret is shown once, on mint.

Connections — your keys, or your customer's

A connection-tier agent with no connection answers 424 connection_required with a connect pointer. on_behalf_of (1–128 chars of A-Za-z0-9_.-, no ..) is accepted on POST /v1/execute among the execute routes: the run reads the credential connected under that customer id.

Other errors you will meet

503 not_enabled (bindings, bot groups, channel pairing before their migration or deploy) and 503 unavailable (outbound hooks) · 409 binding_limit, 422 not_paired (bind a chat you did not pair) · 409 name_taken, 422 invalid_name / invalid_members (bot groups) · 400 invalid_path, 404 file_not_found, 413 file_too_large (workspace download) · 404 trigger_not_found · 410 result_expired · 409 execution_failed · 502 upstream_error. The live spec lists each per operation.

Memory, skills, templates

GET /v1/memory/recall, POST /v1/memory/remember, POST /v1/memory/forget, GET /v1/memory/runs, GET /v1/memory/runs/{id} · GET /v1/skills, POST /v1/skills/learn, DELETE /v1/skills/{id} · GET /v1/templates, GET /v1/templates/{id}, POST /v1/templates/{id}/use. Detail: plungeai-memory, plungeai-skills-plugins, plungeai-discovery.

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

The body (JSON or YAML) 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 (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).

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.