> For the complete documentation index, see [llms.txt](https://docs.flap.sh/flap/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flap.sh/flap/developers/pin-existing-ipfs-content.md). # 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. {% hint style="warning" %} 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. {% endhint %} ## 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](/flap/developers/token-launcher-developers/launch-token-through-portal.md#id-1-prepare-token-metadata) 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 ```http 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: ```json { "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: ```bash 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: ```json { "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 ```http GET https://funcs.flap.sh/api/v1/ipfs/pins?cid= ``` Example: ```bash 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/ # File inside a pinned directory https://flap.mypinata.cloud/ipfs// ``` 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. |