Protocol Reference

Every stdin/stdout line is a JSON object with a code field that identifies its type. Runtime protocol/log events are emitted on stdout only; stderr is not a protocol channel.

In CLI mode (afhttp METHOD URL [flags]), output is the same schema but id and tag fields are omitted. Use --output yaml or --output plain for human-readable output (server response body is never modified). See cli.md for CLI usage.

In pipe mode (afhttp --mode pipe), all fields including id and tag are present.

Input (stdin)

request

body, body_base64, body_file, body_multipart, and body_urlencoded are mutually exclusive. body with object/array/number/bool values automatically sets Content-Type: application/json; all other body types require an explicit Content-Type header. (body_multipart and body_urlencoded always set their respective Content-Type automatically.)

Multipart parts (body_multipart)

Each part: name (required), plus one of value (text string), value_base64 (binary), or file (path). Optional filename and content_type overrides.

URL-encoded fields (body_urlencoded)

Array of {"name": "...", "value": "..."} objects. afhttp percent-encodes both name and value per the application/x-www-form-urlencoded spec: unreserved chars (A-Z a-z 0-9 - _ . *) pass through unchanged; spaces → +; all other bytes → %XX. Duplicate names are supported — use separate array entries.

{"code":"request","id":"1","method":"POST","url":"https://api.example.com/token",
 "body_urlencoded":[
   {"name":"grant_type","value":"authorization_code"},
   {"name":"code","value":"abc123"},
   {"name":"redirect_uri","value":"https://app.example.com/cb"}
 ]}

Options

config

Partial update — only provided fields change. Deep-merged for nested objects (defaults.headers_for_any_hosts, host_defaults). Echoes full config after applying.

Global config fields

“Triggers client rebuild” — the connection pool is recreated; existing pooled connections are dropped.

TLS settings are not applied to WebSocket connections — wss:// uses the system certificate store. A log event (websocket_tls_config_ignored) is emitted in the request log category when a WebSocket request is made while non-default TLS config is active.

Request defaults (defaults)

Applied to every request; overridable per-request via options.

Per-host defaults (host_defaults)

{"code":"config","host_defaults":{"api.example.com":{"headers":{"Authorization":"Bearer sk-xxx"}}}}

Merge order for every request: global defaults → host_defaults[host] → per-request headers.

Credential headers (for example Authorization, x-api-key, cookies) must be configured in host_defaults, never in defaults.headers_for_any_hosts.

Other input commands

Output (stdout)

Agent Consumption Contract

For each request id, consume events as a finite state machine:

• HTTP buffered: response or error (exactly one terminal event).
• Chunked/download/WebSocket: chunk_start → zero or more chunk_data/log → chunk_end or error.
• log events are non-terminal and may appear between lifecycle events.
• id values are unique among active requests/connections; duplicate active id returns error_code: "invalid_request" immediately.
• On close, afhttp cancels active work and attempts to emit terminal events for any remaining id values before process exit.

Response codes

response

Body selection rules (when response_parse_json: true):

• JSON content-type → body (parsed object; parse failure + valid UTF-8 → string + body_parse_failed: true; parse failure + invalid UTF-8 → body_base64 + body_parse_failed: true)
• text/* + valid UTF-8 → body (string)
• text/* + invalid UTF-8 → body_base64 (bytes preserved exactly)
• Binary ≤ response_save_above_bytes → body_base64
• Any content-type > response_save_above_bytes → body_file
• response_save_file set → body_file always
• No body (204, 304, HEAD) → none of the above

error

code: "response" with any HTTP status (including 4xx/5xx) is not an error — it means the transport succeeded. code: "error" means the transport itself failed.

Error codes

Retryable errors are automatically retried up to retry with exponential backoff: delay for attempt N = retry_base_delay_ms × 2^(N-1).

chunk_start

chunk_data

chunk_end

Trace

duration_ms is always present. Other fields are best-effort.

pong

{"code":"pong","trace":{"uptime_s":42,"requests_total":100,"connections_active":3}}

log

All diagnostic output uses code: "log" with an event field identifying the category. Emitted only when the category is enabled in config.log. In CLI mode, use --log <categories> or --verbose to enable.

{"code":"log","event":"startup","version":"<version>","argv":["afhttp","--mode","pipe","--log","startup"],"config":{...}}
{"code":"log","event":"progress","id":"dl-1","received_bytes":10485760,"total_bytes":104857600,"percent":10,"eta_s":27}
{"code":"log","event":"request","id":"req-1","implicit_headers":{"Content-Type":"application/json","Accept-Encoding":"gzip, deflate, br"}}
{"code":"log","event":"retry","id":"req-3","host":"api.example.com","reason":"connection_reset","attempt":1,"delay_ms":100}
{"code":"log","event":"redirect","id":"req-5","status":301,"from":"http://example.com/api","to":"https://example.com/api"}

startup fields

progress fields

Progress is emitted during file downloads. Both progress_ms (time-based) and progress_bytes (byte-count-based) triggers work simultaneously — whichever fires first emits a progress event.

request fields