{"openapi":"3.1.0","info":{"title":"ipfs.family API","version":"1.0.0","description":"Pin files on IPFS, pay per GB per month on Robinhood Chain (4663). See /llms.txt for signing and the pin flow."},"servers":[{"url":"https://api.ipfs.family"}],"paths":{"/health":{"get":{"summary":"ok, database, ipfs node (peer id, peers), latest block, worker heartbeat age","description":"ok, database, ipfs node (peer id, peers), latest block, worker heartbeat age","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/config":{"get":{"summary":"chain, the payment wallet, pricing (per GB a month, minimum, free tier, holder tier), limits, gateway, MCP","description":"chain, the payment wallet, pricing (per GB a month, minimum, free tier, holder tier), limits, gateway, MCP","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/stats":{"get":{"summary":"files pinned, distinct CIDs, bytes stored, floppies worth, wallets, payments, USD paid, opens in 7 days, node peers","description":"files pinned, distinct CIDs, bytes stored, floppies worth, wallets, payments, USD paid, opens in 7 days, node peers","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/quote":{"get":{"summary":"price for bytes kept for months: ?bytes=&months=&token=&owner= (owner applies your free 100 MB and credit) -> {usd, dueU","description":"price for bytes kept for months: ?bytes=&months=&token=&owner= (owner applies your free 100 MB and credit) -> {usd, dueUsd, tier, pay:{sym, amount}}","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"bytes","in":"query","required":false,"schema":{"type":"string"}},{"name":"months","in":"query","required":false,"schema":{"type":"string"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}}]}},"/tokens":{"get":{"summary":"coins you can pay with, live USD prices: ETH, USDG, stock tokens and more","description":"coins you can pay with, live USD prices: ETH, USDG, stock tokens and more. ?q= name, ticker or a 0x address","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}}]}},"/orders":{"post":{"summary":"start a pin: {items:[{name, bytes, cid, mime?, dir?, private?, listed?} | {url}], months, token}","description":"start a pin: {items:[{name, bytes, cid, mime?, dir?, private?, listed?} | {url}], months, token}. Free inside your allowance (smallest files first), else returns pay:{to, value, data} to send as is. Then upload each file (PUT /orders/{id}/files/{pin}). A link item is fetched by our node right away (up to 250 MB). A CID already on our node needs no upload. Action \"pin.order\". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_...","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\npin.order\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"pin.order"}},"/orders/{id}/files/{pin}":{"put":{"summary":"the raw bytes of one file (body = the file, Content-Length = its declared bytes, up to 2 GB)","description":"the raw bytes of one file (body = the file, Content-Length = its declared bytes, up to 2 GB). Our node hashes it with the same settings as the site (CIDv1, raw leaves, 256 KiB chunks), so the CID matches the one you saw. The order id is the capability: no signature needed","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"pin","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}}},"/orders/{id}":{"get":{"summary":"an order: status (open, done, expired), uploadsLeft, paid, pay (the tx to send while due), payTx (the receipt) and its p","description":"an order: status (open, done, expired), uploadsLeft, paid, pay (the tx to send while due), payTx (the receipt) and its pins","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/orders/{id}/pay":{"post":{"summary":"{tx}: point the API at your payment tx (the worker also finds it on its own within ~15 s)","description":"{tx}: point the API at your payment tx (the worker also finds it on its own within ~15 s). Returns {state: paid | partial | credited | pending}","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{}}}}}}},"/orders/{id}/quote":{"post":{"summary":"{token?}: a fresh price and tx for what is still due (price moved, or pay with another coin)","description":"{token?}: a fresh price and tx for what is still due (price moved, or pay with another coin). Action \"order.quote\". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_...","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\norder.quote\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"order.quote"}},"/pins":{"get":{"summary":"public files people chose to share: ?sort=new|big|opens ?kind= ?q= (name, wallet or CID) ?owner= ?limit= ?offset=","description":"public files people chose to share: ?sort=new|big|opens ?kind= ?q= (name, wallet or CID) ?owner= ?limit= ?offset=. Also kinds and top pinners this week","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"string"}}]}},"/pins/{cid}":{"get":{"summary":"one CID: file (name, size, kind), keepers, paid until, every pin row, receipts (payment txs), opens by day, gateway link","description":"one CID: file (name, size, kind), keepers, paid until, every pin row, receipts (payment txs), opens by day, gateway links. Private names show only to their owner (?owner=&ts=&sig=, action \"read\")","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"cid","in":"path","required":true,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"ts","in":"query","required":false,"schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"schema":{"type":"string"}}]}},"/pins/{cid}/dag":{"get":{"summary":"the root block's links: the 256 KiB blocks (or files of a folder) under a pinned CID, first 64, with their CIDs and size","description":"the root block's links: the 256 KiB blocks (or files of a folder) under a pinned CID, first 64, with their CIDs and sizes","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"cid","in":"path","required":true,"schema":{"type":"string"}}]}},"/pins/renew":{"post":{"summary":"{cid | cids, months, token}: keep pins longer","description":"{cid | cids, months, token}: keep pins longer. Free-tier pins renew free up to 12 months ahead; paid pins cost the same rate. Returns an order (paid from credit first). Action \"pin.renew\". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_...","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\npin.renew\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"pin.renew"}},"/pins/unpin":{"post":{"summary":"{cid | cids}: stop keeping it","description":"{cid | cids}: stop keeping it. Our node drops it when nobody else pins it. Unused paid time comes back as credit. Action \"pin.unpin\". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_...","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\npin.unpin\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"pin.unpin"}},"/credit":{"post":{"summary":"{usd, token}: top up your credit (0.5 to 1000 USD); returns an order with the tx to send","description":"{usd, token}: top up your credit (0.5 to 1000 USD); returns an order with the tx to send. Credit pays orders, renewals and PSA pins first. Action \"credit.topup\". signed: body {owner, ts, sig, ...args}, or Authorization: Bearer ipfs_sk_...","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\ncredit.topup\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"credit.topup"}},"/vault/{address}":{"get":{"summary":"a wallet: files, ends soon, usage (stored, free allowance used and left, credit, holder), payments, open orders","description":"a wallet: files, ends soon, usage (stored, free allowance used and left, credit, holder), payments, open orders. Private names and API keys only for the owner (?owner=&ts=&sig=, action \"read\", or an API key)","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"owner","in":"query","required":false,"schema":{"type":"string"}},{"name":"ts","in":"query","required":false,"schema":{"type":"string"}},{"name":"sig","in":"query","required":false,"schema":{"type":"string"}}]}},"/activity":{"get":{"summary":"latest pins and renewals (private files without names): ?limit=","description":"latest pins and renewals (private files without names): ?limit=","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}]}},"/contracts":{"get":{"summary":"on-chain addresses: the payment wallet (and $IPFS once live), what each does and cannot do","description":"on-chain addresses: the payment wallet (and $IPFS once live), what each does and cannot do","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/keys":{"post":{"summary":"a new API key for your wallet (shown once): {label}","description":"a new API key for your wallet (shown once): {label}. Action \"key.create\". signed: body {owner, ts, sig, ...args}","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"owner":{"type":"string","description":"wallet 0x address"},"ts":{"type":"number","description":"Date.now() ms"},"sig":{"type":"string","description":"personal_sign of ipfs.family\\nkey.create\\n<canonical args>\\nts:<ts>"}}}}}},"x-signed-action":"key.create"}},"/psa/pins":{"get":{"summary":"IPFS Pinning Service API (Bearer ipfs_sk_...): list your remote pins","description":"IPFS Pinning Service API (Bearer ipfs_sk_...): list your remote pins. ?cid= ?name= ?match= ?status=queued,pinning,pinned,failed ?before= ?after= ?limit=","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"cid","in":"query","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","required":false,"schema":{"type":"string"}},{"name":"match","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}]},"post":{"summary":"Pinning Service API: {cid, name?, origins?, meta?: {months}}","description":"Pinning Service API: {cid, name?, origins?, meta?: {months}}. Our node fetches it from IPFS, then it is paid from your free allowance or credit (else failed with the amount needed)","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{}}}}}}},"/psa/pins/{requestid}":{"get":{"summary":"Pinning Service API: one pin request","description":"Pinning Service API: one pin request","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"requestid","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"summary":"Pinning Service API: replace a pin request","description":"Pinning Service API: replace a pin request","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"requestid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{}}}}}},"delete":{"summary":"Pinning Service API: remove a pin","description":"Pinning Service API: remove a pin","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[{"name":"requestid","in":"path","required":true,"schema":{"type":"string"}}]}},"/events":{"get":{"summary":"SSE: pinned, renewed, unpinned, payment, order","description":"SSE: pinned, renewed, unpinned, payment, order. ?types=pinned,payment","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/mcp":{"get":{"summary":"MCP server info + config snippet","description":"MCP server info + config snippet","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]},"post":{"summary":"MCP over streamable HTTP (JSON-RPC)","description":"MCP over streamable HTTP (JSON-RPC). Tools: get_quote, pin_url, pin_cid, get_order, submit_payment, get_pin, list_my_pins, list_public_pins, renew_pin, unpin, top_up, list_tokens, get_stats, list_contracts","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{}}}}}}},"/llms.txt":{"get":{"summary":"this file","description":"this file","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}},"/openapi.json":{"get":{"summary":"OpenAPI 3.1","description":"OpenAPI 3.1","responses":{"200":{"description":"JSON"},"400":{"description":"{error}"},"401":{"description":"{error}"},"404":{"description":"{error}"},"429":{"description":"{error, retry_after}"}},"parameters":[]}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"ipfs_sk_... from POST /keys"}}}}