Pins

List pin requests

Returns matching pins ordered by creation time, newest first. The default limit is 10. Without a valid status filter, Filebase excludes failed pins and returns queued, pinning, and pinned requests. Specify status=failed to find failed pins. The count is the total matching the filters before the limit is applied. For older pages, pass the final result's created timestamp as before and retain the other filters. Timestamp boundaries are exclusive: records sharing the boundary timestamp can be skipped; this is not a snapshot or a unique cursor. Do not assume the first page is complete. Avoid simultaneous before and after filters unless intentionally selecting a time window.

get/pins

Request

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

Query parameters

cidstring[]

Comma-separated CIDs. Only the first 10 are used; send at most 10 per request.

namestring

Filter by name, using the match strategy.

match'exact' | 'iexact' | 'partial' | 'ipartial'

Name matching: exact is the default; iexact ignores case; partial searches within the name; ipartial combines partial matching and case folding.

Matching strategy applied when name is present. Defaults to exact.

statusStatus[]

Comma-separated statuses. Omitted or entirely unrecognized values exclude failed pins rather than defaulting to pinned only. Include failed explicitly to list failures.

beforestring date-time

Only pins created strictly before this RFC 3339 timestamp. Use the last created timestamp from a page to request older records; equal timestamps are excluded.

afterstring date-time

Only pins created strictly after this RFC 3339 timestamp. Results remain ordered newest first.

limitinteger

Maximum records requested for this page. Defaults to 10. Use a positive integer and bounded page sizes. No upstream 1,000-record maximum is promised by this Filebase contract.

URL-encoded JSON object with one metadata key/value pair. Filebase only evaluates the first pair and looks up its S3-style x-amz-meta- key. Supply the key without that prefix; this is not an AND filter across multiple pairs.

Response

Matching pin requests, with a total count before pagination.

countinteger required

Total matching pins before applying limit.

Example response

{
  "results": [
    {
      "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.