Skip to main content
POST
Pin IPFS content
Pins a CID on Nexus’ self-hosted node so it stays available. The pin is recorded against your API key and returns { cid, pinned, sizeBytes }. Idempotent — pinning the same CID twice is a no-op.
Requires the IPFS add-on. Pinning is API-key only — a browser/cookie session returns 403. Oversized content (above the server limit) returns 413.
Each organization has a storage limit of 5 GiB (5,368,709,120 bytes) across all its API keys. A pin that does not fit returns 403 with errorCode: "IPFS_STORAGE_LIMIT_EXCEEDED"; your existing pins stay. Unpin something to free space, then pin again. Pinning again a CID your key already holds is never refused when its size is already counted. A CID whose earlier pin failed is measured and counted like a new pin. On the Blockfrost-compatible API (/api/v0/ipfs/pin/add) the size is only known after the request is queued, so a pin that does not fit ends in state failed; send the same request again once there is room.
Pins are reference-counted per key: see List pins and Unpin. The node only physically unpins a CID once no API key references it anymore — one tenant can never drop another tenant’s content.
Example

Authorizations

X-Api-Key
string
header
required

API key (programmatic access — recommended)

Send your API key in the X-Api-Key header. Keys start with nxs_ and are created in the dashboard (or via POST /api/keys with a session JWT).

Each key is scoped to one chain and one network (for example CARDANO_MAINNET), fixed at creation time. It cannot query a different network on the same chain, and it cannot query a different chain at all. A mismatched network parameter returns 400 Network Mismatch. Create one key per chain and network under the same account.

This is the credential most integrations should use.

Query Parameters

path
string
required
Maximum string length: 500

Response

200 - application/json

OK

cid
string
pinned
boolean
sizeBytes
integer<int64>