Pin Existing IPFS Content

Use the Flap Pin By CID API when a file or directory is already available on Public IPFS but is not yet retained by the Flap Pinata account. After the pin finishes, Flap applications and approved Vault UIs can load the content through the Flap IPFS gateway.

This API imports an existing CID. It does not upload local files or create a CID for you.

When to use this API

Use it when:

• You already have a public IPFS CID.
• The content works through its original IPFS provider but the Flap gateway reports that it is not pinned by the gateway owner.
• A custom Vault UI needs an immutable image that must be available through the Flap gateway.

For a new token image and metadata JSON that have not been uploaded yet, use the token metadata upload flow instead.

Requirements

Before submitting a request:

• Confirm that the content is available on Public IPFS.
• Copy the complete raw CID exactly as returned by the original provider.
• Keep the original provider pin active until Flap reports pinned and the content works through the Flap gateway.
• Submit only a raw CIDv0 or base32 CIDv1 value.

Do not submit an ipfs:// URI, a gateway URL, or a path below the CID.

# Valid
bafy...
Qm...

# Invalid
ipfs://bafy...
https://example-gateway.com/ipfs/bafy...
bafy.../image.webp

Submit a CID

POST https://funcs.flap.sh/api/v1/ipfs/pins
Content-Type: application/json

The public endpoint does not require a caller API key. Flap's Pinata credential remains on the server and must never be included in a request.

Request body:

{
  "cid": "bafy...wejvfy",
  "name": "vault-ui-hero-image"
}

The CID above is intentionally shortened for documentation. Replace it with the complete raw CID returned by your IPFS provider when making a request.

• cid is required.
• name is optional and is used only as an operator-friendly Pinata label.

Example with cURL:

curl --request POST \
  --url "https://funcs.flap.sh/api/v1/ipfs/pins" \
  --header "Content-Type: application/json" \
  --data '{
    "cid": "YOUR_CID_HERE",
    "name": "vault-ui-hero-image"
  }'

The API returns 202 Accepted while Pinata is processing a new request. If the CID is already pinned or already being processed, the API returns the existing result instead of creating a duplicate job. A CID that is already pinned returns 200 OK.

Example response:

{
  "data": {
    "cid": "bafy...wejvfy",
    "status": "queued",
    "providerStatus": "prechecking",
    "jobId": "00000000-0000-0000-0000-000000000000",
    "name": "vault-ui-hero-image"
  },
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Check the pin status

GET https://funcs.flap.sh/api/v1/ipfs/pins?cid=<CID>

Example:

curl --get \
  --url "https://funcs.flap.sh/api/v1/ipfs/pins" \
  --data-urlencode "cid=YOUR_CID_HERE"

The stable Flap statuses are:

Pinning is asynchronous. Poll at a reasonable interval and do not treat the initial 202 response as completion.

Verify through the Flap gateway

After the status becomes pinned, verify the content through the Flap gateway:

# Single file
https://flap.mypinata.cloud/ipfs/<CID>

# File inside a pinned directory
https://flap.mypinata.cloud/ipfs/<DIRECTORY_CID>/<FILE_PATH>

Only remove the original provider pin after at least one real file has loaded successfully through the Flap gateway.

Files and directories

• For one existing image, submit its image CID once.
• For an existing IPFS directory, submit the directory CID once. Do not submit every file path below it.
• If every image has a separate CID, each CID is a separate Pin request; this API does not combine them into a directory.

Browser and server usage

The endpoint is public but does not enable wildcard browser CORS. Call it from a command-line client or your server, not directly from arbitrary browser JavaScript.

Troubleshooting