The Filebase IPFS Pinning Service API implements the vendor-neutral IPFS Pinning Service specification. Per-bucket Bearer tokens authenticate requests to list, add, retrieve, replace, and delete pinned objects by CID. Supports metadata tagging and filtering by CID, name, status, and timestamps. Compatible with IPFS Desktop, the IPFS CLI, and any third-party tool supporting the pinning service standard. Rate limit is 100 requests per second.
openapi: 3.0.3
info:
title: Filebase IPFS Pinning Service API
description: >-
The Filebase IPFS Pinning Service API implements the vendor-neutral IPFS
Pinning Service specification. Per-bucket Bearer tokens authenticate requests
to list, add, retrieve, replace, and delete pinned objects by CID. Supports
metadata tagging and filtering by CID, name, status, and timestamps.
Compatible with IPFS Desktop, the IPFS CLI, and any third-party tool
supporting the pinning service standard. Rate limit is 100 requests per second.
version: "1.0"
contact:
name: Filebase Support
url: https://filebase.com/
email: [email protected]
termsOfService: https://filebase.com/terms/
license:
name: Proprietary
url: https://filebase.com/terms/
externalDocs:
description: Filebase IPFS Pinning Service API Documentation
url: https://filebase.com/docs/ipfs/pinning-service-api
servers:
- url: https://api.filebase.io/v1/ipfs
description: Filebase IPFS Pinning Service API
security:
- BearerAuth: []
paths:
/pins:
get:
operationId: listPins
summary: List pin objects
description: >-
Returns a list of pinned objects, with optional filtering by CID, name,
status, before/after timestamps, and limit.
tags:
- Pins
parameters:
- name: cid
in: query
description: Return pin objects for the specified CID(s)
schema:
type: array
items:
type: string
maxItems: 10
style: form
explode: false
- name: name
in: query
description: Return pin objects with names that contain the provided string (case-insensitive, partial matches)
schema:
type: string
maxLength: 255
- name: match
in: query
description: Customize the text matching strategy for the name filter
schema:
type: string
enum: [exact, iexact, partial, ipartial]
default: partial
- name: status
in: query
description: Return pin objects for pins with the specified statuses
schema:
type: array
items:
type: string
enum: [queued, pinning, pinned, failed]
style: form
explode: false
- name: before
in: query
description: Return results created before provided timestamp
schema:
type: string
format: date-time
- name: after
in: query
description: Return results created after provided timestamp
schema:
type: string
format: date-time
- name: limit
in: query
description: Max records to return
schema:
type: integer
minimum: 1
maximum: 1000
default: 10
- name: meta
in: query
description: Return pin objects that match specified metadata
schema:
type: object
additionalProperties:
type: string
maxProperties: 1000
style: deepObject
explode: true
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/PinResults"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
post:
operationId: addPin
summary: Add pin object
description: >-
Add a new pin object for the current access token.
tags:
- Pins
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Pin"
responses:
"202":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/PinStatus"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"409":
$ref: "#/components/responses/Conflict"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
/pins/{requestId}:
get:
operationId: getPin
summary: Get pin object
description: >-
Get a pin object and its status.
tags:
- Pins
parameters:
- $ref: "#/components/parameters/requestId"
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/PinStatus"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
post:
operationId: replacePin
summary: Replace pin object
description: >-
Replace an existing pin object (shortcut for remove + add).
tags:
- Pins
parameters:
- $ref: "#/components/parameters/requestId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Pin"
responses:
"202":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/PinStatus"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"409":
$ref: "#/components/responses/Conflict"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
delete:
operationId: deletePin
summary: Remove pin object
description: >-
Remove a pin object.
tags:
- Pins
parameters:
- $ref: "#/components/parameters/requestId"
responses:
"202":
description: Successful response (no body)
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Per-bucket Bearer token for authentication
parameters:
requestId:
name: requestId
in: path
required: true
description: Unique ID for a pin request
schema:
type: string
schemas:
PinResults:
type: object
required: [count, results]
properties:
count:
type: integer
description: Total number of pin objects that exist for passed query filters
minimum: 0
example: 1
results:
type: array
description: Paginated results
items:
$ref: "#/components/schemas/PinStatus"
uniqueItems: true
minItems: 0
maxItems: 1000
PinStatus:
type: object
required: [requestid, status, created, pin, delegates]
properties:
requestid:
type: string
description: Globally unique identifier of the pin request
example: "UniqueIdOfPinRequest"
status:
$ref: "#/components/schemas/Status"
created:
type: string
format: date-time
description: Immutable timestamp indicating when a pin request entered the pinning queue
example: "2020-07-27T17:32:28Z"
pin:
$ref: "#/components/schemas/Pin"
delegates:
type: array
description: List of multiaddrs designated by pinning service for p2p connection
items:
type: string
uniqueItems: true
minItems: 1
maxItems: 20
info:
type: object
description: Optional info for PinStatus response
additionalProperties:
type: string
minProperties: 0
maxProperties: 1000
Pin:
type: object
required: [cid]
properties:
cid:
type: string
description: CID to be pinned recursively
example: "QmCIDHash..."
name:
type: string
description: Optional name for pinned data
maxLength: 255
example: "my-file.jpg"
origins:
type: array
description: Optional list of multiaddrs known to provide the data
items:
type: string
uniqueItems: true
maxItems: 20
meta:
type: object
description: Optional metadata for pin object
additionalProperties:
type: string
minProperties: 0
maxProperties: 1000
Status:
type: string
enum: [queued, pinning, pinned, failed]
description: Status of a pin object
Failure:
type: object
required: [error]
properties:
error:
type: object
required: [reason]
properties:
reason:
type: string
description: Mandatory string identifying the type of error
example: "ERROR_CODE_FOR_MACHINES"
details:
type: string
description: Optional detailed error message
example: "Optional explanation for humans"
responses:
BadRequest:
description: Bad request (400)
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
Unauthorized:
description: Unauthorized (401); access token is missing or invalid
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
NotFound:
description: The specified resource was not found (404)
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
Conflict:
description: Conflict (409); requested ID already exists
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
TooManyRequests:
description: Rate limit exceeded (100 req/s)
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
InternalServerError:
description: Internal Server Error (500)
content:
application/json:
schema:
$ref: "#/components/schemas/Failure"
tags:
- name: Pins
description: IPFS pin management operations