FAQ

Frequently asked questions about IPFS Ninja.

General

What is IPFS Ninja?

IPFS Ninja is a managed IPFS pinning service. You upload any file via a simple REST API, or pin existing CIDs from the IPFS network. Each file gets a permanent content identifier (CID) and is accessible through our gateway at ipfs.ninja/ipfs/<CID>.

Does ipfs.ninja/ipfs/<CID> serve any CID on the IPFS network?

No. The apex gateway only serves CIDs that have been uploaded or pinned by an IPFS Ninja user. Requests for unknown CIDs return HTTP 410 Gone with a pointer to public IPFS gateways (ipfs.io, dweb.link). To serve a third-party CID through our gateway, POST /pin it to your account first — once pinned, the CID becomes accessible at both the apex and your dedicated gateway URL.

What's the difference between the apex gateway and the dedicated gateway?

Aspect	Apex ipfs.ninja/ipfs/<CID>	Dedicated <slug>.gw.ipfs.ninja/ipfs/<CID>
Scope	Shared across all users	Your CIDs only
Auth	None	Optional token / IP allowlist / origin allowlist
SLA	Best-effort	Full SLA
Recommended for	Casual links	Production embedding (NFT, video, websites)
Rate limits	Shared per-IP + per-CID	Per-plan, configurable

Both serve identical content. For production traffic, use the dedicated gateway.

What file types are supported?

All file types are supported. JSON objects and arrays can be sent directly. All other files (images, PDFs, HTML, video, audio, binaries) are sent as base64-encoded content.

Is there a file size limit?

Individual uploads are limited by your plan's storage allowance. There is no per-file size limit beyond your available storage.

Can I pin content that already exists on IPFS?

Yes. Use POST /pin with any valid CID. Our cluster will fetch the content from the IPFS network and pin it to your account. See the Pinning API docs for details.

How long does pinning take?

It depends on file size and how many IPFS nodes have the content. Small, well-distributed files pin in seconds. Large or rarely-pinned content may take a few minutes. The pin endpoint returns immediately with status pinning — poll GET /pin/:cid to check progress.

What happens if a CID can't be found?

The status changes to failed. This means the CID is either invalid or the content is no longer available on any reachable IPFS node.

Is data uploaded to IPFS public?

Yes. All content pinned to IPFS is publicly accessible via its CID through any IPFS gateway. If you need private access, use a dedicated gateway with token-required mode — this restricts access through your gateway, though the content remains available on the broader IPFS network.

Will my files stay on IPFS if I cancel my account?

We unpin your files from our nodes when you cancel. If other IPFS nodes have cached your content, it may remain accessible. However, without active pinning, files will eventually be removed by garbage collection across the network.

Authentication & API

How do I authenticate API requests?

Pass your API key via the X-Api-Key header. Generate keys from the API Keys page in your dashboard.

Are there API rate limits?

No. IPFS Ninja does not impose rate limits on API requests. You can make as many requests as you need on any plan.

Do API keys expire?

No. API keys are valid until you delete them. You can create multiple keys and revoke them individually.

What's the difference between API keys and gateway tokens?

API keys (bws_) have full access — upload, delete, list files. Gateway tokens (gwt_) are read-only and can only access files through your dedicated gateway. Gateway tokens are safe to embed in frontend apps.

Dedicated Gateways

What is a dedicated gateway?

A private IPFS gateway at your own subdomain (e.g. abc123.gw.ipfs.ninja) that only serves files pinned to your account. Unlike the public gateway, it won't resolve CIDs from other users.

Which plans include a dedicated gateway?

Dedicated gateways are available on all paid plans (Bodhi $5/mo, Karma $19/mo, Nirvana $59/mo). Each plan's monthly bandwidth quota covers traffic from both the apex and dedicated gateways. See "Are there bandwidth fees?" below for per-plan quotas.

Can I restrict who accesses my gateway?

Yes. You can enable token-required mode (requires a gwt_ token on every request) and/or set an IP whitelist (up to 100 addresses).

Can I restrict my gateway by origin/domain?

Yes. Configure allowedOrigins in your gateway settings with a list of HTTPS origins. Only browser requests from those origins will be allowed. Non-browser requests (without an Origin header) pass through. An empty list allows all origins.

What are signed upload tokens?

Signed upload tokens are time-limited credentials for client-side uploads. You generate them on your server using POST /upload/signed-url and pass them to browsers or mobile apps. The client authenticates with Authorization: Signed <token> instead of exposing your API key. Each token tracks usage and expires automatically. See the Signed Tokens docs for details.

Can I optimize images served from IPFS?

Yes. Use GET /image/:cid with query parameters like w, h, format, and quality to resize, convert, and compress images on-the-fly. Responses are cached based on the content-addressed CID. This works on all plans. See Image Optimization.

Can I attach metadata to files?

Yes. Include a metadata object with up to 10 key-value pairs when uploading via POST /upload/new or pinning via POST /pin. Metadata is returned in file listings and the file detail endpoint. See the Files and Pinning docs.

Billing & Plans

Is there a free plan?

Yes. The Dharma plan is free forever — 1 GB of storage, unlimited API requests, no credit card required.

Are there bandwidth fees?

No metered bandwidth fees on any plan. Each plan includes a monthly gateway bandwidth quota that's a hard cap — your content stops serving on the apex and dedicated gateways once the quota is hit, and resumes on the 1st of the next month or after an upgrade:

Plan	Monthly bandwidth
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

You'll receive warning emails at 80% and 100% of your quota.

Does storage reset?

Storage does not reset. Your plan includes a total storage allowance (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). To free space, delete files you no longer need. Upgrading your plan increases your total allowance.

Can I cancel anytime?

Yes. Cancel your subscription through the billing portal — no lock-in. Your account reverts to the free tier, and existing pinned files remain accessible.

What happens to my files if I downgrade?

Your files stay pinned to IPFS, but you cannot upload more if your current usage exceeds the new plan's storage limit. Delete files to get back under the limit.

Security

Is my data encrypted?

All data is encrypted in transit via TLS/HTTPS. Authentication uses JWT tokens (Cognito) and API keys stored securely. File content on IPFS is not encrypted at rest — IPFS is a public network by design.

Is it safe to use API keys in my server-side code?

Yes. API keys are designed for server-side use. Never expose them in client-side code. For client-side file access, use gateway tokens (gwt_) which are read-only.

Support

How do I get help?

Email info@ipfs.ninja or check the API Reference documentation.

Is there an SLA?

We strive for high availability but do not offer a formal SLA at this time. The service is provided on an "as is" basis.