Input & Output | IPFS

Shared Input Pattern

Every operation takes resource and operation as the top-level config keys that select the DTO, plus the Kubo connection fields (and, for some, the Cluster connection fields) — see Configuration. Everything else is specific to the chosen resource + operation pair.

Shared Output Shape

Every operation writes an outputData object with:

Field	Present On	Description
`status`	All	`"success"` on the success path.
`resource`	All	Echoes the operation's `resource`.
`operation`	All	Echoes the operation's `operation`.
`count`	List-shaped operations only	Number of items in the list (e.g. `pin/list`, `swarm/peers`, `bootstrap/list`).
`items`	All	An array wrapping the result record(s) — a single-object result uses `WrapSingleObjectIntoItems`, a list result uses `WrapListIntoItems`.

Binary I/O

Operations that move raw bytes follow one of two symmetric patterns:

Direction	Operations	Mechanism
Input (upload)	`content/add`, `dag/put`, `dag/import`, `block/put`, `files/write`, `key/import`, `cluster/add`, `storage/uploadAndPin`	Bytes resolved from the upstream node's `InputData[inputDataKey]` (already-`byte[]` passes through as-is; a string is decoded per `dataMode`), falling back to `inlineContent` when the input key is empty.
Output (download)	`content/cat`, `content/get`, `block/get`, `files/read`, `dag/export`	The raw `byte[]` is placed directly under `data` in the items record for downstream nodes to consume.

Binary-Input Error Codes

Code	Meaning
`MISSING_CONTENT` / `MISSING_FILE_DATA`	Nothing found under `InputData[inputDataKey]` and no `inlineContent` fallback provided.
`INVALID_CONTENT_ENCODING` / `INVALID_FILE_DATA_ENCODING`	The resolved string content could not be decoded per `dataMode` (e.g. malformed base64).

How Errors Surface

Situation	What happens
Missing required config field	A `CFG_MISSING_` (or `CFG_CONFIRM_`) validation error, routed to the `error` output port before any network call.
Missing/malformed binary content	`MISSING_CONTENT`/`INVALID_CONTENT_ENCODING` (see above), also before any network call.
Kubo/Cluster returns a non-2xx response	Surfaces as `"<resource>/<operation> failed: <message> (<code>)"` on the error port.
Kubo returns 200 with an embedded per-item error (e.g. `block/remove`)	Surfaces as an `ok: false`/similar field in a successful response — see the operation's own page.
Transient network failure or 408/429/5xx	Retried automatically (up to 3 attempts, exponential backoff) before surfacing as an error — see Connecting.

Idempotent-by-design retries: because retried operations are either idempotent (pin/unpin/stat/list) or content-addressed (identical bytes always yield the identical CID), a transparent retry never produces a divergent result — you don't need to build your own dedup logic around network blips.