IPFS endpoints

Upload meta-address

POST /api/v1/ipfs/upload validates meta-address hex and uploads bytes through Pinata v3.

Retrieve raw bytes

GET /api/v1/ipfs/:cid returns application/octet-stream from backend proxy.

Endpoints

• POST /api/v1/ipfs/upload
• GET /api/v1/ipfs/:cid

Upload request schema

meta_addressstringrequired

Hex-encoded SPECTER meta-address.

namestring

Optional display/pin name sent to Pinata upload API.

Upload response schema

cidstringrequired

Uploaded IPFS content identifier.

text_recordstringrequired

Formatted value for name service storage, e.g. ipfs://<cid>.

Retrieve request params

cidstringrequired

CID to retrieve through backend gateway client.

Typical flow

01

Upload meta-address bytes

Call POST /api/v1/ipfs/upload and capture the returned CID.

02

Set name-service record

Write text_record into ENS specter text record or SuiNS content hash.

03

Verify retrieval

Call GET /api/v1/ipfs/:cid and confirm raw bytes are returned.

Example calls

Upload (cURL)

curl -s -X POST https://backend.specterpq.com/api/v1/ipfs/upload \
  -H "Content-Type: application/json" \
  -d '{"meta_address":"<HEX_META_ADDRESS>","name":"alice.eth-specter"}' | jq .

Retrieve (cURL)

curl -s "https://backend.specterpq.com/api/v1/ipfs/<CID>" --output meta-address.bin

JavaScript

const up = await fetch("https://backend.specterpq.com/api/v1/ipfs/upload", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ meta_address, name: "alice.eth-specter" })
});

const uploaded = await up.json();
console.log(uploaded.cid, uploaded.text_record);

Required environment variables

Upload requires PINATA_JWT. Retrieval requires PINATA_GATEWAY_URL and PINATA_GATEWAY_TOKEN.

Gateway and caching behavior

Downloads use configured dedicated gateway and can be cached in-memory by CID when cache is enabled.

Response content type for GET

GET /api/v1/ipfs/:cid responds with raw bytes and Content-Type: application/octet-stream.