API Reference

The Effect AI Provider API lets you post microtask jobs to the Effect AI network and retrieve completed results, without needing the Effect team involved after initial setup.

Bring a CSV of inputs and an HTML template. Workers on the network complete one task per row. You poll for results.

Important: The Effect AI Provider API is curently in alpha and will undergo many changes

Base URL

https://api.effect.ai/v1

All endpoints are prefixed with /v1.

Try it in the browser

Prefer not to use curl? The API console is an interactive browser client for the full API: sign up, manage keys, submit templates, post jobs, and download results. Your API key is kept in memory only and never stored.

Authentication

All endpoints except POST /signup require an API key passed as a Bearer token:

-H "Authorization: Bearer eff_live_YOUR_KEY"

Alternatively, use the X-API-Key header:

-H "X-API-Key: eff_live_YOUR_KEY"

API keys are prefixed eff_live_ and are shown exactly once at issuance. Store yours securely, because it cannot be recovered if lost. You can revoke and issue a new one via API Keys.

Requests with a missing, invalid, or revoked key return 401 unauthorized. Keys belonging to a suspended account also return 401.

Credits

All jobs are paid for with EFFECT credits, debited upfront when a job is created. New accounts start with a zero balance. Contact the Effect team to top up your account. Every balance change is recorded in the credit ledger.

Unit	Value
1 EFFECT	1,000,000 lamports
Min reward	0.001 EFFECT per task
Max reward	100 EFFECT per task
Max tasks per job	10,000 (CSV rows or `maxTasks`)
Max job cost	1,000,000 EFFECT
Max request body	20 MB

Pagination

Every list endpoint (/jobs, /jobs/:id/results, /templates, /credits/transactions) accepts the same query parameters and echoes them back in the response alongside a total count:

Parameter	Default	Max	Description
`limit`	100	1000	Number of items to return
`offset`	0	None	Number of items to skip

Rate limits

Scope	Limit
API requests	120 per minute per key
Signups	3 per IP per day

Rate limit headers are returned on every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119

Error responses

All errors return a consistent JSON envelope:

{
  "error": {
    "code": "insufficient_credits",
    "message": "account balance too low to cover job cost"
  }
}

Code	HTTP	Meaning
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	Key is valid but you don't own this resource
`not_found`	404	Resource does not exist
`invalid_request`	400	Bad input such as a missing field, bad CSV, or validation failure
`insufficient_credits`	402	Not enough credit balance
`rate_limited`	429	Over the rate limit
`internal`	500	Server error (credits auto-refunded if job creation fails mid-way)

Quick start

1. Sign up

curl

curl -s -X POST "https://api.effect.ai/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "you@acme.com"}'

2. Check your balance

curl

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

3. Browse templates

curl

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

4. Post a job

curl

curl -s -X POST "https://api.effect.ai/v1/jobs" \
  -H "Authorization: Bearer eff_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "csv",
    "name": "My first job",
    "templateId": "TEMPLATE_ID",
    "reward": "0.5",
    "csv": "product,question\nWidget,Is this good?"
  }'

5. Poll for results

curl

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