API Reference

All endpoints, parameters, request/response formats, and error codes.

For press and integration use, see Brand Assets.

Base URL

https://api.ipfs.ninja

All requests require an API key via the X-Api-Key header. See Authentication for details.

Endpoints

Method	Path	Description	Page
POST	/upload/new	Upload a file to IPFS	Files
GET	/upload/list	List uploaded files	Files
GET	/file/:cid	Get file metadata by CID	Files
PUT	/files/:cid/name	Rename a file	Files
PUT	/files/:cid/move	Move a file into a folder	Folders
POST	/pin	Pin existing CID from IPFS network (supports swarm-connect hints)	Pinning
POST	/pins	Alias of POST /pin (IPFS Pinning Services API spec path)	Pinning
GET	/pin/:cid	Check pin status	Pinning
GET	/pins/:cid	Alias of GET /pin/:cid	Pinning
DELETE	/pin/:cid	Delete a pin (unpin from cluster if no other user holds the CID)	Pinning
DELETE	/pins/:cid	Alias of DELETE /pin/:cid	Pinning
POST	/folders	Create folder	Folders
GET	/folders	List folders	Folders
PUT	/folders/:folderId	Update folder	Folders
DELETE	/folders/:folderId	Delete folder	Folders
POST	/folders/:folderId/snapshot	Snapshot a folder into a directory CID	Folders
PUT	/folders/:folderId/cors	Set per-bucket CORS config	Folders
GET	/folders/:folderId/cors	Get per-bucket CORS config	Folders
DELETE	/folders/:folderId/cors	Remove per-bucket CORS config	Folders
GET	/user/profile	Get user profile	Profile
POST	/apikeys	Create API key	API Keys
GET	/apikeys	List API keys	API Keys
DELETE	/apikeys/:key	Delete API key	API Keys
GET	/analytics	Usage analytics	Analytics
PUT	/gateway-settings	Update gateway settings	Gateways
POST	/gateway-tokens	Create gateway token	Gateways
GET	/gateway-tokens	List gateway tokens	Gateways
DELETE	/gateway-tokens/:prefix	Delete gateway token	Gateways
POST	/upload/signed-url	Generate signed upload token	Signed Tokens
GET	/signed-tokens	List signed tokens	Signed Tokens
DELETE	/signed-tokens/:tokenId	Revoke signed token	Signed Tokens
GET	/image/:cid	Optimize image on-the-fly	Image Optimization

CIDv1 by default

Uploads and pins return modern CIDv1 (bafk… for small single-block content, bafy… for larger files and directories) following the IPIP-0499 unixfs-v1-2025 profile. Legacy Qm… CIDs from earlier uploads remain fully resolvable everywhere — Qm… is a valid input to any endpoint that accepts a CID.

S3-Compatible API

Use any AWS SDK to upload and manage files on IPFS Ninja. Point your S3 client at https://s3.ipfs.ninja with your API key as credentials.

https://s3.ipfs.ninja

S3 Operation	Description
PutObject	Upload a file to IPFS
GetObject	Download a file
HeadObject	Get file metadata
DeleteObject	Unpin and delete a file
ListObjectsV2	List files with prefix filtering
CreateMultipartUpload	Start a multipart upload (up to 5 GB)
UploadPart	Upload a part
CompleteMultipartUpload	Finish multipart upload
ListBuckets	List your gateways
CreateBucket	Create a gateway (bucket names are globally unique — returns BucketAlreadyExists if taken)
DeleteBucket	Delete a gateway
PutBucketCors	Configure per-bucket CORS rules (required for browser SDK usage)
GetBucketCors	Read the current CORS config for a bucket
DeleteBucketCors	Remove all CORS rules from a bucket

See S3 Compatibility for full documentation, code examples, and migration guides.