AFS over HTTP

A client that cannot speak MCP can reach the same AFS operations over plain JSON-RPC at /api/afs/rpc. It is the same data plane and the same access tiers; only the envelope differs.

Use it when the caller is a script, a language without an MCP library, or a model that can issue an HTTP request but has no tool-calling harness.

Call it

curl -s -X POST https://<host>/api/afs/rpc \
  -H 'Content-Type: application/json' \
  -d '{"type":"list","path":"/"}'

{
  "ok": true,
  "data": [
    {
      "id": "instance",
      "path": "/instance",
      "summary": "DID-scoped persistent storage with CID-based content deduplication…",
      "meta": { "childrenCount": -1 }
    }
  ]
}

The request names an operation in type and its arguments alongside. Responses are wrapped in { "ok": …, "data": … }.

No credential was sent in the request above; anonymous read works here exactly as it does on /mcp.

Inspect a path before you read it

stat returns what a provider will actually accept, which saves a round of failed calls:

curl -s -X POST https://<host>/api/afs/rpc \
  -H 'Content-Type: application/json' \
  -d '{"type":"stat","path":"/packages"}'

{
  "ok": true,
  "data": {
    "id": "arcblock",
    "path": "/packages",
    "meta": {
      "kind": "did-space:directory",
      "capabilities": ["list", "read", "stat", "search", "write", "delete", "exec", "explain"],
      "accessMode": "readonly",
      "projection": { "base": "arcblock" }
    }
  }
}

capabilities is what the provider implements. accessMode is what this caller gets. The two are separate: a provider can implement write while the path is readonly for you.

Read capabilities before making an operation part of your integration; a provider is not required to implement all of them. See AFS.

Relationship to the MCP tools

Both endpoints are listed in the host's API catalog, pointing at the same service description.

Prefer /mcp when your client supports it: the tool schemas tell an agent what the arguments are, which stat does not.

Writes

Writes over this endpoint follow the same rules as /mcp: a credential is required, and the blocklet must have published the path to network clients. See Access tiers.

The full operation set and its argument shapes belong to the AFS contract.