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>.

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 the Nirvana plan ($29/mo), which includes 50 GB/month of gateway bandwidth.

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 bandwidth fees on API requests for any plan. Dedicated gateway bandwidth (Nirvana plan) includes 50 GB/month. When the limit is reached, gateway requests are blocked until the next month.

Does storage reset?

Storage does not reset. Your plan includes a total storage allowance (1 GB / 10 GB / 100 GB). 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.