← Pepper 0.2.0

HTTP API

The version-1 JSON API is served by each agent on its loopback-only api.bind_addr. The pepper CLI is the supported native client, while these routes are useful for integrations and operational tooling.

Authentication and conventions

  • When auth.api_bearer_token is configured, send Authorization: Bearer <token> to /v1/* routes. The CLI reads --api-token or PEPPER_API_TOKEN.
  • /healthz, /readyz, and /metrics do not require the bearer token. S3 routes use SigV4 credentials rather than the API bearer token.
  • JSON requests use Content-Type: application/json. Object, block, and directory upload/download routes use bounded binary or multipart bodies as implemented by the CLI.
  • An ingress node forwards namespace-backed work to the current leader when necessary. Treat NamespaceUnavailable and NotLeader as retryable after bounded backoff.
curl -H 'Authorization: Bearer <token>' \
+  http://127.0.0.1:9080/v1/node/status

Node, storage, and pins

GET /v1/node/status

Local identity, configuration summary, metadata schema, and uptime.

GET /v1/node/peers

Known authenticated P2P peers.

POST /v1/blocks

Put a raw block; replication_factor query parameter is optional.

GET|HEAD /v1/blocks/{cid}

Retrieve a verified raw block or test local presence.

POST /v1/objects

Put an object; optional erasure shard query parameters and pin control.

GET /v1/objects/{cid}

Retrieve a verified object.

POST /v1/dirs / GET /v1/dirs/{cid}

Put or retrieve a directory snapshot.

POST /v1/pins

Create a durable root pin.

GET|DELETE /v1/pins/{cid}

Inspect or delete locally owned pins.

Namespaces and KV

POST /v1/namespaces

Create a namespace and optional alias.

GET /v1/namespaces/{namespace}

Inspect descriptor and current revision/root/commit.

GET .../status|replicas|history

Inspect Raft state, voters, or immutable revision history.

POST .../diff|rollback

Compare revisions or publish an older root as a new revision.

GET|POST .../snapshots

List, create, or delete named snapshots.

POST /v1/kv/get|scan

Linearizable or selected historical reads.

POST /v1/kv/put|delete

Conditional, idempotent single-key mutation.

POST /v1/kv/transactions

Atomic version-1 transaction with explicit base revision and root.

Buckets and filesystems

POST /v1/buckets

Create a bucket namespace.

POST /v1/bucket/put|get|head|delete|list|versions

Native versioned bucket operations.

POST /v1/filesystems

Create a filesystem namespace.

POST /v1/fs/commit|checkout|restore|diff|rollback|clone

Immutable filesystem tree operations.

GET /v1/fs/history/{filesystem}

List filesystem revisions.

/* when S3 is enabled

SigV4-authenticated S3 path-style or virtual-hosted requests are dispatched outside /v1.

Compute and administration

POST /v1/compute/jobs

Submit a Firecracker job.

GET /v1/compute/jobs/{job_id}

Read job state and receipt.

GET .../{job_id}/logs

Read captured stdout and stderr.

POST .../{job_id}/cancel

Request cancellation.

POST /v1/admin/gc|repair

Run garbage collection or repair.

GET /v1/admin/status|storage|erasure

Read subsystem, capacity, and erasure summaries.

POST /v1/admin/corruption-scan

Verify and recover/quarantine corrupt blocks.

POST /v1/admin/quarantine/purge

Permanently purge quarantined files.

POST /v1/admin/namespaces/{namespace}/checkpoint|rebalance|replace-replica|recover

Namespace operator workflows.

Diagnostics, health, and metrics

GET /v1/admin/diagnostics exposes bounded block inventory, GC explanation, publication intents, provider/erasure/read/repair/RPC evidence, and namespace replica state. GET /v1/admin/dag/{cid} inspects bounded reachability. See Operations for the complete diagnostic paths and readiness behavior.

Stable error envelope

{
  "code": "generation_conflict",
  "error": "generation precondition did not match"
}

Non-success JSON responses use code and error. Stable codes include invalid_request, not_found, conflict, unauthorized, forbidden, payload_too_large, capacity_exceeded, rate_limited, integrity_failure, unavailable, upstream_failure, unsupported_codec, generation_conflict, namespace_unavailable, not_leader, stale_membership, durability_not_met, transaction_expired, invalid_cursor, staging_unavailable, and internal.