docs

IPFS Pinning Service API

Octopin implements the standard IPFS Pinning Service API. Any tool that speaks it, including Kubo (ipfs pin remote) and IPFS Desktop, can pin straight to Octopin with an API key.

Endpoint: https://api.octopin.app/psa
Auth: Authorization: Bearer <your API key>
Plans: API keys work on every plan. Pinning existing CIDs needs a paid plan (from $5/mo).

1. Create an API key

Sign in, open Settings, and create a key under api keys. Copy it right away: it is shown only once. Keys start with opk_.

2a. Kubo (command line)

ipfs pin remote service add octopin https://api.octopin.app/psa <your-api-key>

Pin a CID. Kubo waits until it is pinned; add --background to return immediately:

ipfs pin remote add --service=octopin --name=my-collection bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

List, check and remove pins:

ipfs pin remote ls --service=octopin
ipfs pin remote ls --service=octopin --status=queued,pinning,failed
ipfs pin remote service ls --stat
ipfs pin remote rm --service=octopin --cid=<CID>

Optional: let Kubo automatically pin your MFS (the Files tab) to Octopin whenever it changes:

ipfs config --json Pinning.RemoteServices.octopin.Policies.MFS.Enable true

2b. IPFS Desktop

Open Settings and find Pinning services.
Click Add service and choose Custom.
Nickname: octopin. API endpoint: https://api.octopin.app/psa. Secret access token: your API key.
In the Files tab, open the menu on any file or folder, choose Set pinning and tick octopin.

3. Plain HTTP (curl, scripts, CI)

Pin an existing CID:

curl -X POST https://api.octopin.app/psa/pins \
  -H "Authorization: Bearer $OCTOPIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cid":"<CID>","name":"metadata","meta":{"collection":"octo"}}'

Check its status with the returned requestid:

curl -H "Authorization: Bearer $OCTOPIN_KEY" https://api.octopin.app/psa/pins/<requestid>

Upload a new file (works on every plan). Use the upload host so large files aren't cut off by proxy timeouts:

curl -X POST https://upload.octopin.app/api/upload \
  -H "Authorization: Bearer $OCTOPIN_KEY" \
  -F "file=@./image.png"

Endpoints

Method	Path	What it does
GET	`/pins`	List pins. Filters: cid, name, match, status, before, after, limit, meta.
POST	`/pins`	Pin a CID. Returns 202 with a requestid.
GET	`/pins/{requestid}`	Status of one pin: queued, pinning, pinned or failed.
POST	`/pins/{requestid}`	Replace a pin (new CID) or rename it (same CID).
DELETE	`/pins/{requestid}`	Remove a pin or cancel a queued one.

Limits

Up to 10 active API keys per account.
Up to 100 pins queued or pinning at once per account.
Pins count toward your plan's storage and file limits, same as dashboard uploads.
Errors follow the spec: {"error":{"reason":"...","details":"..."}}.

FAQ

Which plans can use the Pinning Service API?

Every plan can create API keys and upload files with them. Adding existing CIDs through the Pinning Service API (ipfs pin remote add) needs a paid plan, from $5/mo, the same as importing by CID in the dashboard.

Why does my pin stay in 'queued' or 'pinning'?

Octopin fetches the content from the public IPFS network. Large folders take a while, and content that only exists on your own node needs that node to be online and reachable. If no provider is found within about 10 minutes the pin moves to 'failed' and you can retry.

Do pins added through the API show up in the dashboard?

Yes. API pins and dashboard uploads are the same pins, count toward the same quota and are served from the same gateway. Anything you upload in the dashboard is also listed by ipfs pin remote ls.

What happens if an API key leaks?

Revoke it in Settings and it stops working immediately. API keys can't manage other API keys or reach admin features, so a leaked key can't mint new ones.

New to remote pinning? Read how to use Octopin with IPFS Desktop and Kubo for a walkthrough.