Skip to main content

API overview & authentication

Customer Champion
Updated

This article explains how to reach the Templified API, authenticate your requests with an API key, and understand the endpoints available under the /api/v1/ surface.

Base URL

All API requests go to the same host as the studio application — there is no separate API subdomain:

https://studio.templified.io

Every programmatic endpoint lives under the /api/v1/ prefix. For example, to create an image you post to:

https://studio.templified.io/api/v1/create

Creating an API key

API keys are managed per organization. Only org owners can create and revoke them.

  1. Open Settings in the top navigation.
  2. In the left sidebar, under Organization, click API Keys.
  3. Click Create API Key.
  4. Enter a descriptive Key Name — for example, Production CI or Staging Worker — then click Create Key.
  5. Copy the key from the card immediately. The full value is only shown once.
The API Keys settings page showing one active key with a Revoke button and a Create API Key button in the top right

Authenticating requests

Send your API key as a Bearer token in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

A minimal curl example:

curl -X POST https://studio.templified.io/api/v1/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "clx_...", "fields": {"Name": "Jordan Lee"}}'

API keys are scoped to your organization. Anyone who holds a key can create images and poll job status on behalf of your org. If a key is compromised, revoke it immediately from the API Keys settings page — revoked keys return 401 on every subsequent request.

The /api/v1/ surface

The /v1 routes are the stable, API-key-authenticated surface. They cover:

Group Representative endpoints
Render API POST /api/v1/create, GET /api/v1/create/:job_id
Photos POST /api/v1/photos/process, GET /api/v1/photos/process/:job_id
Design Groups GET /api/v1/design-groups, POST /api/v1/design-groups/create
Studio API POST /api/v1/studio/create, POST /api/v1/studio/create-and-render, POST /api/v1/studio/create/team
Webhooks Subscribe / unsubscribe to render events
Send To List available send-to targets and trigger sends

The full request/response reference — including all fields, async behavior, and webhook bodies — is in the API Documentation page inside the app (Settings → API Keys → API Documentation). You can also download it as a Markdown file to paste into an AI assistant.

Sync vs. async renders

By default, POST /api/v1/create queues the render and returns immediately with a job_id and a poll_url. Add ?sync=true to block for up to 25 seconds and receive the completed image inline — useful for one-off requests where polling is inconvenient. If the render takes longer than 25 seconds, sync mode falls back to a queued response with a poll_url.

Some endpoints that combine a render with an external send (to a destination like Dropbox or a webhook) return 202 Accepted with "async": true. In those cases, always check result.async before reading response fields such as outputUrl — those fields are only present on the synchronous 200 path.

Billing and render credits

Each successful render deducts from your organization's prepaid balance. Renders that include Background Removal carry an additional surcharge. If your balance is empty and auto-refill is off, the API returns 402 and the render is not queued.

Your balance, usage history, and auto-refill settings are all in Settings → Billing.

Common error responses

Status Meaning
401 Missing, invalid, or revoked API key.
402 Insufficient render credits or trial exhausted.
403 Feature not enabled for your organization, or resource belongs to a different org.
404 Template, job, folder, or preset not found.

All errors return a JSON envelope: {"error": {"code": "...", "message": "..."}}.

Related articles

Comments

0 comments

Article is closed for comments.