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.

The production endpoint is available only after the corresponding Flap Edge Functions release has been deployed. If the endpoint returns an HTML 404 page, contact Flap; that response is not a CID validation result.

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:

Status	Meaning
queued	Pinata is prechecking the CID.
retrieving	Pinata found the content and is retrieving it.
processing	Pinata is still processing the request.
pinned	The content is retained by the Flap Pinata account.
failed	Pinata could not complete the request. Check errorCode.
not_found	Flap has no active or completed Pinata record for the CID.

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

Result	Action
400 INVALID_REQUEST	Copy the complete raw CID again. Remove any gateway URL, ipfs:// prefix, or file path.
413 REQUEST_TOO_LARGE	Send only the small JSON body containing cid and optional name. Do not upload file bytes to this endpoint.
status: failed	Inspect errorCode and confirm the original provider still serves the content on Public IPFS.
502, 503, or 504	The upstream Pinata service rejected, rate-limited, or timed out. Retry later.
The endpoint itself returns an HTML 404 page	The deployed Flap Edge Functions release does not include this API yet. Contact Flap before retrying.
The Flap gateway still cannot load the content	Wait until the API reports pinned, then verify the exact CID and optional directory path again.