Templates

Templates are the HTML pages workers see when completing tasks. Fields like ${product} are filled from your CSV columns at task-serve time.

Templates are content-addressed, meaning the template ID is a hash of the HTML, so submitting the same HTML always produces the same ID regardless of submission order.

Trust levels

You can request team approval when creating a template. Unapproved templates are usable immediately.

List templates

GET /v1/templates

Returns the public approved catalog plus your own templates. Archived templates are excluded.

curl -s "https://api.effect.ai/v1/templates" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

With pagination

curl -s "https://api.effect.ai/v1/templates?limit=20&offset=0" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

{
  "templates": [
    {
      "templateId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "name": "Sentiment Analysis",
      "fields": ["product", "question"],
      "approved": true,
      "owned": false
    },
    {
      "templateId": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
      "name": "My Custom Labeller",
      "fields": ["image_url", "label_options"],
      "approved": false,
      "owned": true
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}

Get a template

GET /v1/templates/:id

Returns metadata for a single template. You can only access templates that are approved or owned by your account.

curl -s "https://api.effect.ai/v1/templates/TEMPLATE_ID" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

{
  "templateId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "name": "Sentiment Analysis",
  "fields": ["product", "question"],
  "approved": true,
  "owned": false,
  "status": "active",
  "approvalRequested": false,
  "createdAt": 1750000000000
}

Preview a template

GET /v1/templates/:id/preview

Returns the template's rendered HTML with each field filled in using its own name as a sample value (e.g. ${product} becomes product). Useful for inspecting layout before using it in a job.

To preview with realistic values instead of field names, use the POST variant below.

curl -s "https://api.effect.ai/v1/templates/TEMPLATE_ID/preview" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

{
  "templateId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "name": "Sentiment Analysis",
  "fields": ["product", "question"],
  "approved": true,
  "sampleData": { "product": "product", "question": "question" },
  "html": "<h1>product</h1><p>question</p><button>Yes</button><button>No</button>"
}

sampleData echoes the values that were actually rendered into html.

Preview with sample data

POST /v1/templates/:id/preview

Same as the GET variant, but accepts a data object with your own sample values, so templates that expect real shapes (image URLs, JSON strings) can be previewed working. Provided values merge over the field-name defaults; unknown fields are ignored. Values must be strings, numbers, or booleans.

curl -s -X POST "https://api.effect.ai/v1/templates/TEMPLATE_ID/preview" \
  -H "Authorization: Bearer eff_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"product": "Solar-powered lamp", "question": "Would you buy this?"}}'

{
  "templateId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "name": "Sentiment Analysis",
  "fields": ["product", "question"],
  "approved": true,
  "sampleData": {
    "product": "Solar-powered lamp",
    "question": "Would you buy this?"
  },
  "html": "<h1>Solar-powered lamp</h1><p>Would you buy this?</p><button>Yes</button><button>No</button>"
}

Create a template

POST /v1/templates

Registers a new HTML template. Templates are usable immediately (with an unverified badge shown to workers). Optionally request team approval to get a verified badge.

Workers submit answers by posting a message to the parent window:

window.parent.postMessage({ task: 'submit', values: { label: 'yes' } }, '*')

Without approval request

curl -s -X POST "https://api.effect.ai/v1/templates" \
  -H "Authorization: Bearer eff_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment Analysis",
    "html": "<h1>${product}</h1><p>${question}</p><button onclick=\"window.parent.postMessage({task:'\''submit'\'',values:{answer:'\''yes'\''}},'\''*'\'')\">Yes</button>"
  }'

With approval request

curl -s -X POST "https://api.effect.ai/v1/templates" \
  -H "Authorization: Bearer eff_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment Analysis",
    "html": "<h1>${product}</h1>...",
    "requestApproval": true
  }'

{
  "templateId": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
  "name": "Sentiment Analysis",
  "fields": ["product", "question"],
  "approved": false,
  "owned": true,
  "approvalRequested": true
}

Delete a template

DELETE /v1/templates/:id

Soft-archives your template. It disappears from listings and cannot be used in new jobs. Existing running jobs are not affected.

The archive is reversible. Resubmitting the same HTML via POST /templates revives the template with its previous approval status intact.

curl -s -X DELETE "https://api.effect.ai/v1/templates/TEMPLATE_ID" \
  -H "Authorization: Bearer eff_live_YOUR_KEY"

{
  "templateId": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
  "name": "Sentiment Analysis",
  "fields": ["product", "question"],
  "approved": false,
  "owned": true,
  "status": "archived",
  "approvalRequested": false,
  "createdAt": 1750000000000
}

Returns 403 forbidden if you attempt to delete a template you don't own.