API keys and requests

Connect your server to thirds.ai with an API key. This page covers how to create the key, send it with a request, and check the result. For a complete working example, create your first PDF.

Authentication

Sign in with an email link, GitHub, or Google. If your account has no verified email address, verify one on the account page to receive free credits.

Open API keys and create a named key. Copy it before you leave the page and put it in your server's secret store. You can only see the full key once. Later reads show only its prefix.

Send Authorization: Bearer YOUR_API_KEY with API requests. The key gives access to its account, so keep it out of browser code, prompts, URLs, logs, and source control. Use a separate key for each integration. If you lose a key, revoke it and update each client that uses it. An account can hold ten active API keys.

Use the studio to manage your account, sign in, buy credits, and edit designs. It uses a secure session cookie, and browser writes also need the session's x-csrf-token. Your app uses the API endpoints that accept bearer keys. Do not use browser session or checkout routes to authenticate an integration.

Send a request

The base URL is https://thirds.ai. Send JSON with Content-Type: application/json. For an asset upload, use the media type listed for that endpoint. The API rejects JSON fields it does not know.

To create a PDF or image, send HTML or a saved template with its data. The API does not render a page URL. The API reference lists each endpoint's fields, headers, and response types. You can also download the OpenAPI file.

Responses and errors

When you create a render, the response is a JSON object with its job ID and status. Download the output file in a separate request after the render succeeds.

• 200 from a create request means the render finished, failed, or was cancelled during the request's wait period.
• 202 means thirds.ai accepted and saved the job. Keep its ID and poll for the result.
• 200 from a status read means the read worked. It does not mean the render succeeded.

Check status before you use download.url.

Keep the x-request-id from each response if you need help from support. This ID is safe to share. HTTP errors contain an error object with a fixed code, a message, field details, and retry guidance when it applies. A failed render has its own error.category and error.code. Follow retries, downloads, and limits before you repeat a write request.

We check the request examples against the OpenAPI schemas. Use the API reference for exact header rules and shared error responses.