Test and live mode

Every CastPDF request runs in one of two modes. Test mode makes real PDFs with a watermark, free and without limits on your plan's documents, so you can build and debug as much as you like. Live mode makes the clean PDFs you send to customers, and each one counts toward your plan. Both modes use the same endpoints, the same request bodies and the same renderer, so a request that works in test mode works the same way in live mode.

Test keys and live keys

The key decides the mode. Keys start with cpdf_test_ or cpdf_live_, followed by 32 letters and digits:

Authorization: Bearer cpdf_test_0123456789abcdefghijABCDEFGHIJ01

A test key always works in test mode. A live key works in live mode, unless the request asks for a test document (see the test flag). Create both kinds in the dashboard under API keys. A test key can be created at any time; a live key needs a verified email address. How keys are sent, stored and revoked is on the authentication page.

To check which mode a key is in, call GET /v1/me: key.mode is test or live, and plan.rate_limit_per_min is the limit that key gets.

What is different in test mode

Everything else is identical: the page count, the fonts, page breaks, warnings, errors and response shapes. The watermark is stamped onto every page after printing, so it never changes the layout.

The watermark

Test PDFs carry the words "CASTPDF TEST" in a large diagonal stamp on every page. API previews (POST /v1/templates/:id/preview) carry the same stamp, even when you call them with a live key: a preview is never a real document and is never counted.

The dashboard's editor preview is different. It shows a small grey "Preview" label in the bottom right corner of each page instead of the big stamp, so you can judge the design while you work. The dashboard's Generate PDF button makes a live document: no watermark, counted and stored like a live-key PDF (on the Free plan it carries the small footer). Neither mark is ever on a live PDF. If you see "CASTPDF TEST" on a PDF you meant to send to a customer, it was made in test mode: check the key, and check that the request does not set "test": true.

What is counted

Only successful live documents count toward your plan. Test documents and previews are never counted, on any plan, and a test key never gets plan_limit_reached or spending_cap_reached: it keeps working when your live documents for the month are used up. Failed requests are not counted in either mode. The details of periods, rollover and overage are in usage and billing.

The test flag on a live key

POST /v1/pdf and POST /v1/batches accept "test": true. With a live key, the request then runs in test mode: the PDF is watermarked, is not counted, is stored for 1 day and sends its events to test webhook endpoints. This lets a live system make a test PDF without a second key, for example in a staging environment that shares the live key.

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b", "data": {"number": "INV-042"}, "test": true}' \
  --output test.pdf

The flag only ever lowers a live key to test mode. "test": false with a test key changes nothing: a test key always makes test documents.

Storage and retention of test PDFs

A test PDF is stored for 1 day, and only when something needs the file later: the request asks for "response": "url", sends an Idempotency-Key, emails the PDF, or renders in the background ("async": true). A plain binary response from a test key is not stored, because nothing could fetch it again; the document still shows in the log, with url: null. A test batch's ZIP file is also kept for 1 day.

Stored test PDFs count toward your team's stored PDF space, with their own limit of 200 MB on every plan. Over it, requests that need a stored file get 429 storage_limit_reached with details.scope set to test. Old test files expire after a day and free the space by themselves.

What test keys can and cannot do

A test key can make PDFs (direct, in the background and in batches), read and preview templates, list its own documents and batches, read the account and usage, and manage test webhook endpoints. It cannot:

• Change templates. Creating, updating, pinning or deleting a template with a test key gets 403 forbidden. A leaked test key therefore cannot change the templates your live PDFs use. Use a live key or the dashboard.
• Read live documents or batches. A test key sees only test documents and test batches. Asking for a live one by id gets 404 document_not_found (or batch_not_found), exactly as if it did not exist.
• Manage live webhook endpoints. A test key lists and changes only test endpoints, and creating a live endpoint with it gets 400 invalid_request.
• Email anyone. Test-mode emails go only to verified email addresses of your own team; any other address gets invalid_request with details.reason set to members_only. The email footer says it is a test document.

A live key can read every document and batch of the team, test ones included.

Rate limits in test mode

All test keys of a team share one budget of 20 requests per minute, whatever the plan. The dashboard's previews and test renders draw from the same test budget. Live keys have their own, larger budget per plan, so heavy testing never slows down your live traffic. Previews have a separate limit of 30 per minute per team and mode, and background work in test mode is limited to Free 100, Starter 2,000, Growth 4,000, Pro 10,000 and Scale 20,000 PDFs in 24 hours. All limits are on the rate limits page.

Webhooks and documents per mode

Each webhook endpoint has a mode. A test endpoint receives the events of test PDFs (from a test key, a live key with "test": true, or a test batch); a live endpoint receives the events of live PDFs. Events carry "livemode": false or true, so a single receiver can tell them apart. Webhooks need the Starter, Growth, Pro and Scale plan in either mode. See webhooks.

Documents carry the mode too: GET /v1/pdf/:id and GET /v1/documents show "test": true for test documents.

Going live checklist

1. Verify your email address. Live keys, the dashboard's Generate PDF button and live batches from the dashboard need it.
2. Create a live key in the dashboard and store it as a secret on your server, next to (not instead of) your test key.
3. Swap the key in your production configuration. Nothing else in the request changes.
4. Remove "test": true from requests that should make real PDFs. Check one live PDF: it should have no watermark.
5. Add live webhook endpoints. Test endpoints never receive live events. Create the live endpoint with a live key or in the dashboard, and store its signing secret.
6. Check your plan's limits: documents per month, the live rate limit, PDFs rendering at once and file retention (usage and billing, rate limits).
7. Send an Idempotency-Key with every PDF request, so a retry after a network error never makes or counts a document twice (idempotency).
8. Read live documents with a live key. A test key that is still used for monitoring will not see live documents.

Next steps

• Authentication and keys: sending, storing and revoking keys.
• Idempotency: safe retries for live documents.
• Rate limits: every limit and how to back off.
• Usage and billing: what counts, rollover, overage and the spending cap.