Pins

Pin an existing CID

Queues retrieval and recursive pinning of an existing CID. An omitted or empty name defaults to the CID. Submitting the same name and CID again returns the existing pin and requestid with HTTP 202; it does not create a second request. Reusing a name with a different CID returns HTTP 409. Use a distinct name or explicitly replace the existing pin. HTTP 202 does not guarantee completion; poll the returned requestid. A retry returning an existing failed pin does not restart it.

post/pins

Request

  • Base URL: https://api.filebase.io/v1/ipfs
  • URL: https://api.filebase.io/v1/ipfs/pins
  • Auth: HTTP bearer

Request body

cidstring required

Valid IPFS CIDv0 or CIDv1 identifying the root DAG. Supply the raw CID, without an ipfs:// prefix, /ipfs/ path, or gateway URL.

namestring

Display name. Filebase limits names to 1,024 UTF-8 bytes (which may be fewer than 1,024 characters). Defaults to the CID on create or to the old name on replacement. Creation conflicts on the same name with a different CID.

originsstring[]

Optional multiaddrs of peers providing the content. Include /p2p/<peer-id>; create rejects entries without /p2p/. Use publicly reachable provider addresses. Empty if no hints were supplied.

metaPinMeta

Optional JSON metadata. Prefer string values for interoperability. Filebase exposes S3-style x-amz-meta- keys without that prefix in responses and reserves origins for provider hints.

Example request

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "example.txt",
  "origins": [],
  "meta": {
    "app": "example"
  }
}

Response

New request accepted, or the existing pin with the same name and CID returned.

requestidstring required

Opaque request identifier used for status, replacement, and deletion. It is not a CID or UUID.

status'queued' | 'pinning' | 'pinned' | 'failed' required

queued: waiting for retrieval; pinning: retrieving content; pinned: retained successfully; failed: retention failed. Keep providers reachable until pinned.

createdstring date-time required

Immutable timestamp indicating when a pin request entered a pinning service; can be used for filtering results and pagination

delegatesstring[] required

Multiaddrs of Filebase peers that can receive content over Bitswap. May be empty.

Example response

{
  "requestid": "opaque-pin-request-id",
  "status": "queued",
  "created": "2026-09-30T12:00:00Z",
  "pin": {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "name": "example.txt",
    "origins": [],
    "meta": {
      "app": "example"
    }
  },
  "delegates": [],
  "info": {
    "size": "0"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.