Pinion Documentation

Pinning Service

Overview

The Pinning Service API allows you to manage and persist content on IPFS by "pinning" CID objects. Pinning ensures that specific data remains available and is not garbage-collected by IPFS nodes.

This API is compatible with the IPFS Pinning Service API specification v1.0.0.

Base URL

Shown here using PAT authentication (see Authentication for the /web/ and /api/v1/ alternatives).

Pin Lifecycle

Every pin moves through a sequence of states. The happy path is queued → pinning → pinned. A failure during ingestion moves the pin to failed, which is terminal.

Endpoints

List Pins

Retrieve a list of pinned or pinning requests.

Query Parameters

Results are always returned in ascending order by created (oldest first), regardless of how many pins match. This holds even when there are more matches than limit: the response is always the oldest matching page, never an arbitrary subset. That makes GET /pins?name=X a reliable way to read back a revision history for anything you upload repeatedly under the same name: reuse the name on every upload, then list by that name to get every CID back in the order it was created.

countis the total number of pins matching this request's filters, independent of limitspecifically, so it's not capped at the page size. It is still scoped to this request, though: once you page forward by advancing after, after itself is one of the filters, so countcorrectly shrinks on each subsequent page (it is “how many match from here on,” not a fixed grand total for the name). If count is larger than the length of results, there are more matches to read; pass after with the created timestamp of the last item in the current page to fetch the next one. An empty results array (count: 0) means you've read everything.

Examples

Pin a CID by name:

curl -X POST https://helium.pinion.build/pinning/pat/v1/pins \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi", "name": "my-file"}'

List all pinned items:

curl https://helium.pinion.build/pinning/pat/v1/pins?status=pinned \
  -H "Authorization: Bearer YOUR_TOKEN"

Check the status of a specific pin:

curl https://helium.pinion.build/pinning/pat/v1/pins/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete a pin:

curl -X DELETE https://helium.pinion.build/pinning/pat/v1/pins/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Gateway API

Overview

The Pinion Gateway provides HTTP access to IPFS content by CID. It implements the IPFS HTTP Gateway specification, including full content-type negotiation via the Accept header.

Content uploaded through the Upload Service is immediately retrievable through the Gateway, even before the worker has finished processing the pin request.

Base URL

Shown here using PAT authentication (see Authentication for the /web/ and /api/v1/ alternatives).

Endpoint

Retrieve content by CID. Optionally traverse into a UnixFS directory using a path suffix.

Content-Type Negotiation

Use the Accept header to request a specific response format:

Caching

Responses include standard HTTP caching headers. Because IPFS content is content-addressed and immutable, responses for a given CID are safe to cache indefinitely. Cache-Control: public, max-age=29030400, immutable is set by the gateway for resolved content.

Examples

Download a file by CID:

curl https://helium.pinion.build/gateway/pat/v1/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o myfile.jpg

Download a CAR archive of a DAG:

curl https://helium.pinion.build/gateway/pat/v1/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/vnd.ipld.car" \
  -o content.car

Fetch a file within a directory CID:

curl https://helium.pinion.build/gateway/pat/v1/ipfs/bafybeid.../index.html \
  -H "Authorization: Bearer YOUR_TOKEN"

Public Paths

Every endpoint above requires authentication, because retrieving content costs us egress bandwidth that has to be billed to someone. That's a problem for a perfectly normal use case: you want to hand someone a link and have it just work, no Pinion account required. Self-hosting a website, sharing a dataset with a collaborator, linking to a file from a README, publishing something via DNSLink.

A naive "make this pin public" toggle breaks down the moment two accounts pin the same content, which happens constantly since IPFS is content-addressed: whoever flipped the toggle first would end up billed for everyone's traffic. A Public Pathfixes this by making the exposure explicit and account-scoped instead of a property of the CID itself: it's a named, globally-unique allowlist of your own pins. Content attached to it is served with no authentication at all, billed to your account specifically, regardless of who else happens to have pinned the same CID. You can create as many paths as you like and attach the same pin to more than one.

Creating a path and attaching pins to it uses the same authenticated endpoints as everything else on this page (shown here under /pat/v1/). Fetching content through a path is the one exception in this entire document: it lives directly under /gateway/, with no /pat/v1/, /web/, or /api/v1/ prefix, and no Authorization header.

Managing paths

Fetching through a path — no account needed

The DNSLink form resolves domain's _dnslinkTXT record (a record you control, we don't manage DNS on your behalf) and serves the resolved CID the same way, as long as it's attached to that path. Either form 404s if the path doesn't exist, or if the resolved CID isn't attached to it.

Create a path:

curl -X POST https://helium.pinion.build/gateway/pat/v1/paths \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "<YourPathName>"}'

Attach one of your pins to it:

curl -X POST https://helium.pinion.build/gateway/pat/v1/paths/<YourPathName>/pins \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"requestid": "550e8400-e29b-41d4-a716-446655440000"}'

Fetch it — no account needed:

# No Authorization header -- this is the whole point.
curl https://helium.pinion.build/gateway/<YourPathName>/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -o myfile.jpg

Upload Service

Overview

The Upload Service accepts files and CAR archives, writes them directly into the shared IPFS blockstore, and creates a pin request for asynchronous processing by the worker cluster. Content is immediately available via the Gateway upon upload, even before the pin is confirmed.

This is the writable side of the Gateway, a plain HTTP endpoint for handing us bytes directly without running an IPFS node. If you already run a kubo node or another IPFS-native client, you likely want the Pinning Service instead. It tells us which CID to keep, and we fetch it from the network ourselves.

Two upload formats are supported:

• Regular file: any file, chunked and organized into a UnixFS DAG automatically. A multipart request can include more than one file field (e.g. a train/test split); when it does, all of them are wrapped into a single directory pin.
• CAR archive: a pre-built IPFS DAG in Content Addressable aRchive format. Supports multiple roots; when there is more than one, they are wrapped into a single directory pin the same way multiple files are.

Whenever an upload produces more than one root, the response is always a single directory pin rather than one pin per file, see Response below for the exact shape.

Base URL

Shown here using PAT authentication (see Authentication for the /web/ and /api/v1/ alternatives).

(psst… there's also an interactive Swagger UI for this one, if you'd rather click around than read.)

Endpoint

Upload a file or CAR archive to IPFS.

Query Parameters

Request Body

Response

Always returns a single PinStatus object, never an array. For a single file or single-root upload, pin.cidis that file's own CID:

// Single file / single root
{
  "requestid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pinning",
  "created": "2025-01-15T12:00:00Z",
  "pin": {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "name": "my-file"
  }
}

When an upload produces more than one root (multiple file fields, or a multi-root CAR), or when wrap=true was set, pin.cid is instead the CID of a UnixFS directory wrapping every file, and pin.info carries a file:<name> manifest entry per file, so you never have to fetch a directory listing just to find where a file landed:

// Multiple files/roots, or wrap=true
{
  "requestid": "6f9619ff-8b86-d011-b42d-00cf4fc964ff",
  "status": "pinning",
  "created": "2025-01-15T12:00:00Z",
  "pin": {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdd",
    "name": "dataset"
  },
  "info": {
    "file:train.csv": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "file:test.csv":  "bafybeih6cq4nsdlz6hshoyv2ymhr5vhwjq7ke5m5rmglmvv2s3iuxqtxbi"
  }
}

File names inside the directory (and in the manifest) come from each part's own filename for multipart uploads, or root-0, root-1, … for CAR files, which don't carry filenames of their own.

Behavior

After upload, the pin enters pinning status. A worker node picks up the request from the pubsub queue, verifies the content is present in the blockstore, and transitions the pin to pinned. Because content is written directly to the shared blockstore on upload, it is retrievable via the Gateway immediately, not only after pinning completes.

Examples

Upload a regular file (multipart):

curl -X POST "https://helium.pinion.build/upload/pat/v1/?name=myfile" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@./myfile.txt"

Upload several files in one request (multipart, e.g. a dataset split into parts):

curl -X POST "https://helium.pinion.build/upload/pat/v1/?name=dataset" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@./train.csv" \
  -F "file=@./test.csv"

Upload raw bytes (octet-stream):

curl -X POST https://helium.pinion.build/upload/pat/v1/?name=myfile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./myfile.txt

Upload a CAR archive (via Content-Type):

curl -X POST https://helium.pinion.build/upload/pat/v1/?name=my-dag \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/vnd.ipld.car" \
  --data-binary @./content.car

Upload a CAR archive (via query param, useful when Content-Type cannot be set). No pinion-clitab here since it's the same pinion upload --car command shown above either way:

curl -X POST "https://helium.pinion.build/upload/pat/v1/?format=car&name=my-dag" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-binary @./content.car

GitHub Integration

Overview

Pinion integrates with GitHub as a GitHub App. Once installed on your account or organization, Pinion monitors your repositories and automatically pins content to IPFS based on a configuration file you commit to each repository.

No CI pipeline changes are needed. Pinion responds directly to GitHub webhook events.

What Gets Pinned

• Repository content: pin the full repository or specific subdirectories on every push to your configured branch.
• Subdirectories: pin one or more paths within your repository (e.g. docs/, dist/) independently.
• Release assets: pin the files attached to a GitHub release when it is published.
• Filtered release assets: use glob patterns to pin only specific assets (e.g. *.tar.gz), and control whether auto-generated source code archives are included.

Installation

1. Sign in to Pinion and go to your Profile page.
2. Click Connect GitHub and install the Pinion GitHub App on your account or organization.
3. Add a pinion.build.yaml file to the root of any repository you want Pinion to monitor.

Configuration: pinion.build.yaml

Place this file at the root of your repository. Sections you omit are ignored.

version: 1

# Release asset pinning - supports pattern matching
release_assets:
  enabled: true
  include_source_code: true
  patterns:
    - "*.txt"
    - "*.tar.gz"


# Directory monitoring - supports multiple paths and branch selection
subdirectories:
  enabled: true
  branch: "main"        # Git branch to monitor (default: "main")
  paths:
    - "docs/"           # Pin documentation directory
    - "static/"         # Pin static assets
    - "dist/"           # Pin build output
    - "data/"           # Pin data files

release_assets

subdirectories

Monitoring

Each webhook event Pinion receives is recorded with a status and any processing messages. You can review these events from your GitHub Events page to diagnose configuration issues or confirm that pins were created successfully.

Prover API

The Prover API adds cryptographic proofs of storage to your pinned content. Rather than trusting that your data is safe, you can issue mathematical challenges to Pinion servers and verify the responses yourself, with no Pinion involvement in the verification step. See the Storage Proofs page for a full explanation of the protocols.

Prover Keys

A prover key is a server-held cryptographic keypair generated for a specific proof protocol. Creating a key returns a client_setup blob containing the public material you need to generate challenges and verify proofs. The signing secret stays on the server. One key can cover many pinned CIDs simultaneously.

Supported protocols:

Unsupported protocols:

The underlying storage-proofs library implements additional protocols that Pinion does not support for IPFS content:

Tags & Data

A tagis a small cryptographic authentication value computed from a block’s content and identity. When you call POST /tag, Pinion queues the work and returns a job_id immediately: it walks the full IPFS DAG of the given root CID in the background, virtualizes it into uniform fixed-size super-blocks, computes one tag per super-block, and stores the tags. Once the job is done, polling it returns a block_count, the number of super-blocks, which is all you need to construct challenges client-side: ids are rootCID || localIndex for localIndex in [0, block_count), so no per-block manifest is ever sent. This is the expected flow for most users.

The root must already be in the pinned lifecycle state for your account before you can tag it. Calling POST /tag for a CID that’s still queued or pinning returns 409 {"error": "pin_not_active", "cid": "..."}: wait for the pin to finish (or poll GET /pinning/pat/v1/pins/<requestid> until status is pinned) and retry.

Multiple roots can be tagged under one key. The prover merges all tagged roots into a single proof when challenged with an empty roots array. In the unusual case that you need to hold your own private key, you can generate tags client-side using the storage-proofs library and register them via POST /register. The challenge and verification flow is identical; only key custody changes.

Setup

Setup is done once per key. It creates the cryptographic material the server needs to answer challenges and the material you need to issue them. There are three steps.

curl -X POST https://helium.pinion.build/prover/pat/v1/challenge-key \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"protocol": "sw-pub"}'

{ "key_id": "550e8400-...", "client_setup": "<base64>" }

# Tagging is asynchronous, so this queues the job and returns immediately:
curl -X POST https://helium.pinion.build/prover/pat/v1/tag \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"root": "bafybeigdyrzt...", "key_id": "550e8400-..."}'
# Returns JSON: {"job_id":"<id>"}. Poll GET /tag/<job_id> (same auth) until
# status is "tag-done" (then block_count is populated; see "Tags & Data"
# for why no per-block manifest is ever sent) or "tag-failed" (then error
# is). A large DAG can take minutes to walk.
curl https://helium.pinion.build/prover/pat/v1/tag/<job_id> -H "Authorization: Bearer YOUR_TOKEN"

{ "block_count": 42 }

curl "https://helium.pinion.build/prover/pat/v1/setup?key_id=550e8400-..." \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "client_setup": "<base64>",
  "roots": [
    { "root": "bafybeigdyrzt...", "block_count": 42 }
  ]
}

Tag Signing

client_setup (from CreateKey) and block_count (from tagging) are both looked up fresh from Firestore on every GET /setupand every share-link resolve. Pinion signs both with an Ed25519 key the moment they’re created — client_setup at CreateKey time, block_countat tag-completion time — so a client can confirm this data really came from Pinion’s own prover, unmodified, before trusting it. Without that check, a compromise below the application layer (a Firestore injection bug, a bad migration, compromised database credentials, not necessarily a compromise of pinion-prover itself) could substitute fabricated key material, or shrink a block_countto make an unsatisfiable challenge trivially satisfiable, and a naive client would never notice: the pairing math would still “pass” against the tampered inputs. Verifying the signature protects the inputs to that math, which matters as much as the math itself.

Configure the trusted key once, per client:

import proverclient "github.com/pinionengineering/pinion-prover-client/go"

pubKeyHex := "e2ca7910acbe769ad9da4078e2999e13d0aaa5db08cf720f9e21f2e3c86dc17a"
pubKey, _ := hex.DecodeString(pubKeyHex)

client := proverclient.NewClient("https://helium.pinion.build/prover",
	proverclient.WithAuthURL("https://helium.pinion.build/prover/pat/v1"),
	proverclient.WithToken(tokenFunc),
	proverclient.WithTrustedKey(ed25519.PublicKey(pubKey)),
)
// client.Audit(...) now verifies ClientSetup/BlockCount signatures before
// trusting anything in them; see the Go client's trustkey.go doc comments.

Both client libraries and pinion-cli refuse to run an audit without a configured trusted key — a clear error instead of silently skipping the check, which would defeat its purpose. This only gates audit/Audit(): the lower-level challenge/verify flow (see Audit Cycle below) doesn’t currently perform this check, so prefer audit when you want the authenticity guarantee.

Requires @pinionengineering/prover-client v0.12.0+ and pinion-prover-client/go with WithTrustedKey (both current as of this page). Earlier versions checked against a fixed placeholder key baked into the JS package and had no trust-key concept in the Go package at all; upgrade if audit/Audit()reports an untrusted-setup failure you can’t otherwise explain.

Audit Cycle

Once setup is complete, you can audit at any time from any machine using only your saved state file. No authenticated requests are needed. Two roles are involved:

The cycle per round: generate challenge locally, POST to /prover/prove (queues a job and returns a job_id immediately), poll GET /prover/prove/<job_id> until it reaches a terminal state, verify locally. If verification fails, the data has been tampered with or lost.

Load state file and run the audit loop:

# curl cannot generate a valid challenge or verify the proof; those steps
# require client-side cryptography. Use the Go or JavaScript library instead.
#
# The /prove endpoint itself accepts a raw POST (no authentication required).
# Proving is asynchronous, so this queues the job and returns immediately:
curl -X POST https://helium.pinion.build/prover/prove \
  -H "Content-Type: application/json" \
  -d '{"key_id":"<uuid>","roots":[],"challenge":"<base64>","challenge_id":"<optional-id>"}'
# Returns JSON: {"job_id":"<id>"}. Poll GET /prove/<job_id> until status is
# "prove-done" (then proof is populated) or "prove-failed" (then error is).
# The challenge must be generated by the Go/JS client and the proof
# verified by the same client. See the Go and JavaScript tabs above.

The sw-pub protocol is recommended for IPFS workloads: it is publicly verifiable and supports cross-CID challenges. Both tabs above use pinion-prover-client, which ships a client for each language: the JavaScript tab uses @pinionengineering/prover-client, which implements the BN254 pairing math itself; the Go tab uses pinion-prover-client/go, a thin wrapper around storage-proofs/line/swpub and ipfs-storage-proofs, the same libraries pinion-prover itself runs on. Both clients speak the same wire protocol, so you can mix them, tag from one, audit from the other.

Endpoints

Key Management (requires Bearer JWT or OAuth session)

Each entry in the GET /challenge-keys response includes:

Tagging (requires Bearer JWT or OAuth session)

Tagging is asynchronous, same as proving: POST /tag queues the walk and returns immediately; poll GET /tag/:job_id until status is "tag-done" (then block_countis populated; see “Tags & Data” above for why no per-block manifest is ever sent) or "tag-failed" (then erroris). A large DAG can take minutes to walk. The JS client's tag() only submits the job and returns immediately with a job handle; call waitForTag()to actually wait for a terminal state — there's no default deadline, since a large DAG can legitimately take longer than any fixed ceiling.

Proving (no authentication required)

Proving is asynchronous: POST /prove queues the challenge and returns immediately; poll GET /prove/:job_id until status is "prove-done" (then proof is populated) or "prove-failed" (then error is). In the JS client, prove()itself only submits and returns a job handle immediately — call waitForProve() to wait for a terminal state, with no default deadline. audit() is the one call that still does both for you (submit, wait, and cryptographically verify), and its wait phase also has no fixed ceiling unless you pass your own signal.

curl -X POST https://helium.pinion.build/prover/prove \
  -H "Content-Type: application/json" \
  -d '{"key_id":"<uuid>","roots":[],"challenge":"<base64>","challenge_id":"<optional-id>"}'
# Response: {"job_id":"<id>"}. Proving is asynchronous.
curl https://helium.pinion.build/prover/prove/<job_id>
# Response once done: {"status":"prove-done","challenge_id":"<echoed>","proof":"<base64>"}
# proof is base64-encoded raw bytes; pass to validator.Verify() after decoding