Pins

Replace a pin request

Replaces the old request with a new queued request and returns its new requestid. If name is omitted or empty, the old name is retained. Filebase responds with HTTP 200, although retrieval remains asynchronous. The old pin record is removed during replacement; do not assume its content stays pinned until the new pin completes. If continuity is required, create a separately named pin, wait for pinned, update references, then delete the old request. Poll the new requestid, not the old one.

post/pins/{requestid}

Request

  • Base URL: https://api.filebase.io/v1/ipfs
  • URL: https://api.filebase.io/v1/ipfs/pins/{requestid}
  • 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

Replacement created; use its new requestid to poll completion.

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.