Four wires

The One API returns one payload and lets you pick the wire it travels on. The execute routes (tools, agents, workflows and the agent call door) and the bot routes under /v1/workflows, /v1/schedules and /v1/executions all share one format rule, so a script, a shell pipeline and an LLM can each read the same answer in the shape that suits them.

Choose the wire

The first rule that applies wins:

1. format in the body, or ?format= in the query.
2. The Accept header. The highest q value that names a known type wins; ties go to the first listed. */* and unknown types are skipped, and an Accept is a preference, never a 400.
3. The request's Content-Type: text/yaml, application/yaml or application/x-yaml answers in YAML, anything else in JSON.

An explicit format that is not one of json, yaml, markdown or text is 400 invalid_format, answered as JSON. Streams (stream: true, execute-stream) are exempt and always send server-sent events.

Send JSON or YAML

A request body is JSON or YAML, whichever its Content-Type says. Tool fields can be sent with or without the params wrapper.

The same call on the tools door, once with JSON and once with YAML:

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"params":{"expression":"7*6"}}'

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: text/yaml' \
  --data-binary $'expression: "7*6"\n'

On a workflow route, format, input and inputs sit at the top of the YAML next to workflow:. They mean exactly what the JSON fields mean and are removed before the engine sees the workflow:

format: markdown
workflow:
  name: w
  tasks:
    - id: t1
      type: task
      agent: calculator-tool-agent
      expression: "7*6"

A bare agent: body works on the agent call door, POST /v1/execute: agent: calculator-tool-agent, the agent's own fields and format: text. See Agent call.

Read it on four wires

The same run, asked four ways:

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"params":{"expression":"7*6"}}'

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -H 'Accept: text/yaml' -d '{"params":{"expression":"7*6"}}'

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -H 'Accept: text/markdown' -d '{"params":{"expression":"7*6"}}'

curl -s -X POST "https://api.plungeai.com/v1/tools/calculator-tool-agent/execute?format=text" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"params":{"expression":"7*6"}}'

The json answer:

{"ok":true,"content":"# Calculator: 7*6\n\n## 1. Expression\n7*6\n\n## 2. Result\n42\n\n*2 results*","execution_id":"…","request_id":"…"}

The yaml answer carries the same fields:

ok: true
content: |-
  # Calculator: 7*6

  ## 1. Expression
  7*6

  ## 2. Result
  42

  *2 results*
execution_id: …
request_id: …

The markdown answer is the content followed by a footer naming the execution, so a reader can quote the id:

# Calculator: 7*6

## 1. Expression
7*6

## 2. Result
42

*2 results*

---
execution: `…` — use this id for plungeai_get_result / plungeai_followup on this run.

The text answer is only the content, from # Calculator: 7*6 to *2 results*.

A route that answers with a pointer instead of a result (an async run) has no content. Its markdown and text wires then list the pointer's top-level keys (workflow_id, execution_id, task_id, status), one per line, so nothing is dropped.

Response headers

• x-request-id is on every answer, on every wire.
• X-Execution-Id is on every answer that belongs to an execution.
• X-Error-Code is on every error.

Errors on four wires

An error keeps its code and message on every wire. The extra fields travel too: missing, contract, hint and the execution id render on markdown, missing on text, and every field survives json and yaml.

A missing field, asked as text:

curl -s -X POST https://api.plungeai.com/v1/tools/calculator-tool-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -H 'Accept: text/plain' -d '{"params":{}}'

invalid_params: params failed card validation
missing: expression

An unknown format is always JSON, with X-Error-Code: invalid_format:

{"error":{"code":"invalid_format","message":"format must be one of: json, yaml, markdown, text"}}

MCP and the CLI

The MCP tools answer markdown by default. Pass format: "json" for the same outcome as a JSON document in text plus structuredContent. The CLI takes --json on every verb for one JSON document on stdout.

Next steps