The IPFS » Pins API from Cardano — 4 operation(s) for ipfs » pins.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/cardano:cardano-ipfs-pins-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 0.1.89
title: Blockfrost.io ~ API Documentation IPFS » Pins API
x-logo:
url: https://staging.blockfrost.io/images/logo.svg
altText: Blockfrost
contact:
name: Blockfrost Team
url: https://blockfrost.io
email: contact@blockfrost.io
license:
name: MIT
url: https://opensource.org/licenses/MIT
termsOfService: https://blockfrost.io/terms
description: Blockfrost is an API as a service that allows users to interact with the Cardano blockchain, Midnight blockchain, and parts of their ecosystems.
servers:
- url: https://cardano-mainnet.blockfrost.io/api/v0
description: Cardano Mainnet network
- url: https://cardano-preprod.blockfrost.io/api/v0
description: Cardano Preprod network
- url: https://cardano-preview.blockfrost.io/api/v0
description: Cardano Preview network
- url: https://localhost:3000
description: local
security:
- project_id: []
tags:
- name: IPFS » Pins
paths:
/ipfs/pin/add/{IPFS_path}:
servers:
- url: https://ipfs.blockfrost.io/api/v0
post:
tags:
- IPFS » Pins
summary: Pin an object
description: 'Pinning is necessary to avoid regular garbage collection (deletion) of IPFS objects. Non-pinned objects are regularly being removed without prior notice. Pinned objects are counted in your user storage quota.
**Note:** If the object was pinned to Filecoin (using `filecoin=true`), it cannot be removed or unpinned due to Filecoin''s immutable and persistent storage guarantees. Please ensure careful consideration when pinning objects to Filecoin, as the action is irreversible.'
parameters:
- in: path
required: true
name: IPFS_path
schema:
type: string
description: Path to the IPFS object
- in: query
name: filecoin
schema:
type: boolean
required: false
description: 'If set to true, the object will be pinned to Filecoin as well. If not specified, the object will only be pinned to IPFS. Objects pinned to Filecoin cannot be unpinned due to its long-term storage guarantees.
'
x-codeSamples:
- lang: Shell
label: cURL
source: "curl \"https://ipfs.blockfrost.io/api/v0/ipfs/pin/add/{IPFS_path}\" \\\n -H \"project_id: $PROJECT_ID\" \\\n"
responses:
'200':
description: Returns pinned object
content:
application/json:
schema:
type: object
properties:
ipfs_hash:
type: string
example: QmPojRfAXYAXV92Dof7gtSgaVuxEk64xx9CKvprqu9VwA8
description: IPFS hash of the pinned object
state:
type: string
enum:
- queued
- pinned
- unpinned
- failed
- gc
example: queued
description: State of the pin action
filecoin:
type: boolean
description: Whether filecoin was used to pin the resource.
required:
- ipfs_hash
- state
- filecoin
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'425':
$ref: '#/components/responses/425-2'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
operationId: postIpfsPinAddByIPFSPath
x-operation-id-source: derived
/ipfs/pin/list:
servers:
- url: https://ipfs.blockfrost.io/api/v0
get:
tags:
- IPFS » Pins
summary: List pinned objects
description: 'List objects pinned to local storage
Hosted Endpoint only available for hosted variant.'
parameters:
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: 'The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first, newest last.
'
x-codeSamples:
- lang: Shell
label: cURL
source: "curl \"https://ipfs.blockfrost.io/api/v0/ipfs/pin/list/\" \\\n -H \"project_id: $PROJECT_ID\" \\\n"
responses:
'200':
description: Returns pinned objects
content:
application/json:
schema:
type: array
items:
type: object
properties:
time_created:
type: integer
description: Creation time of the IPFS object on our backends
example: 1615551024
time_pinned:
type: integer
description: Pin time of the IPFS object on our backends
example: 1615551024
ipfs_hash:
type: string
description: IPFS hash of the pinned object
example: QmdVMnULrY95mth2XkwjxDtMHvzuzmvUPTotKE1tgqKbCx
size:
type: string
description: Size of the object in Bytes
example: '1615551024'
state:
type: string
enum:
- queued
- pinned
- unpinned
- failed
- gc
description: 'State of the pinned object, which is `queued` when we are retriving object. If this
is successful the state is changed to `pinned` or `failed` if not. The state `gc` means the
pinned item has been garbage collected due to account being over storage quota or after it has
been moved to `unpinned` state by removing the object pin.
'
example: pinned
filecoin:
type: boolean
description: Whether filecoin was used to pin the resource.
required:
- time_created
- time_pinned
- ipfs_hash
- size
- state
- filecoin
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
operationId: getIpfsPinList
x-operation-id-source: derived
/ipfs/pin/list/{IPFS_path}:
servers:
- url: https://ipfs.blockfrost.io/api/v0
get:
tags:
- IPFS » Pins
summary: Get details about pinned object
description: 'Get information about locally pinned IPFS object
Hosted Endpoint only available for hosted variant.'
parameters:
- in: path
required: true
name: IPFS_path
schema:
type: string
description: The path to the IPFS object
x-codeSamples:
- lang: Shell
label: cURL
source: "curl \"https://ipfs.blockfrost.io/api/v0/ipfs/pin/list/{IPFS_PATH}\" \\\n -H \"project_id: $PROJECT_ID\" \\\n"
responses:
'200':
description: Returns the pins pinned
content:
application/json:
schema:
type: object
properties:
time_created:
type: integer
description: Time of the creation of the IPFS object on our backends
example: 1615551024
time_pinned:
type: integer
description: Time of the pin of the IPFS object on our backends
example: 1615551024
ipfs_hash:
type: string
description: IPFS hash of the pinned object
example: QmdVMnULrY95mth2XkwjxDtMHvzuzmvUPTotKE1tgqKbCx
size:
type: string
description: Size of the object in Bytes
example: '1615551024'
state:
type: string
enum:
- queued
- pinned
- unpinned
- failed
- gc
description: 'State of the pinned object. We define 5 states: `queued`, `pinned`, `unpinned`, `failed`, `gc`.
When the object is pending retrieval (i.e. after `/ipfs/pin/add/{IPFS_path}`), the state is `queued`.
If the object is already successfully retrieved, state is changed to `pinned` or `failed` otherwise.
When object is unpinned (i.e. after `/ipfs/pin/remove/{IPFS_path}`) it is marked for garbage collection.
State `gc` means that a previously `unpinned` item has been garbage collected due to account being over storage quota.
'
example: pinned
filecoin:
type: boolean
description: Whether filecoin was used to pin the resource.
required:
- time_created
- time_pinned
- ipfs_hash
- size
- state
- filecoin
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
operationId: getIpfsPinListByIPFSPath
x-operation-id-source: derived
/ipfs/pin/remove/{IPFS_path}:
servers:
- url: https://ipfs.blockfrost.io/api/v0
post:
tags:
- IPFS » Pins
summary: Remove a IPFS pin
description: 'Remove pinned objects from local storage
Hosted Endpoint only available for hosted variant.
**Note:** If the object was pinned to Filecoin (using `filecoin=true`), it cannot be removed or unpinned due to Filecoin''s immutable and persistent storage guarantees. Please ensure careful consideration when pinning objects to Filecoin, as the action is irreversible.'
parameters:
- in: path
required: true
name: IPFS_path
schema:
type: string
description: The path to the IPFS object
x-codeSamples:
- lang: Shell
label: cURL
source: "curl \"https://ipfs.blockfrost.io/api/v0/ipfs/pin/remove/{IPFS_PATH}\" \\\n -X POST \\\n -H \"project_id: $PROJECT_ID\" \\\n"
responses:
'200':
description: Returns the pins removed
content:
application/json:
schema:
type: object
properties:
ipfs_hash:
type: string
example: QmPojRfAXYAXV92Dof7gtSgaVuxEk64xx9CKvprqu9VwA8
description: IPFS hash of the pinned object
state:
type: string
enum:
- queued
- pinned
- unpinned
- failed
- gc
example: unpinned
description: State of the pin action
required:
- ipfs_hash
- state
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
operationId: postIpfsPinRemoveByIPFSPath
x-operation-id-source: derived
components:
responses:
'403':
description: Authentication secret is missing or invalid
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 403
error:
type: string
example: Forbidden
message:
type: string
example: Invalid project token.
required:
- error
- message
- status_code
'429':
description: Usage limit reached
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 429
error:
type: string
example: Project Over Limit
message:
type: string
example: Usage is over limit.
required:
- error
- message
- status_code
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 400
error:
type: string
example: Bad Request
message:
type: string
example: Backend did not understand your request.
required:
- error
- message
- status_code
'404':
description: Component not found
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 404
error:
type: string
example: Not Found
message:
type: string
example: The requested component has not been found.
required:
- error
- message
- status_code
425-2:
description: Pin queue is currently full, not accepting new txs straight away
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 425
error:
type: string
example: Pin Queue Full
message:
type: string
example: Your pin queue is currently full, please try pinning again later.
required:
- error
- message
- status_code
'418':
description: IP has been auto-banned for extensive sending of requests after usage limit has been reached
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 418
error:
type: string
example: Requested Banned
message:
type: string
example: IP has been auto-banned for flooding.
required:
- error
- message
- status_code
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 500
error:
type: string
example: Internal Server Error
message:
type: string
example: An unexpected response was received from the backend.
required:
- error
- message
- status_code
securitySchemes:
project_id:
type: apiKey
in: header
name: project_id
description: 'There are multiple token types available based on network you choose
when creating a Blockfrost a project, for a list of token types
see available networks.
'
x-provenance:
method: harvested
publisher: Cardano
source: https://docs.blockfrost.io/blockfrost-openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)