Getting Started with the Public API

The Toksta Public API lets you search creators, run enrichment and analysis jobs, and (with SaaS entitlements) manage campaigns and creator lists from your own backend.

Base URL

All v1 routes use:

https://api.toksta.com/v1/...

System probes (/health, /ready, /version) sit at the root without the /v1 prefix (for example, https://api.toksta.com/health).

Before you start

1. Sign in at Toksta and open Account → API keys (or go to /account#api-keys).
2. You need an active dedicated API plan (Build, Scale, Enterprise, or PAYG) or a SaaS plan with API access enabled. Free plans cannot create API keys.
3. Subscribe or top up at API pricing when available on your account, or upgrade your SaaS plan from Pricing.

See Authentication for key creation and Pricing and Plans for plan economics.

Authentication

Every v1 request requires a bearer token:

Authorization: Bearer tk_live_<your-secret>
Content-Type: application/json

Use server-to-server calls from your backend. Do not embed API keys in browser or mobile client code.

First call — verify connectivity

GET /v1/account/usage
Authorization: Bearer tk_live_<your-secret>

A 200 response confirms your key, plan entitlements, and current credit balance. Common early failures:

Status	Code	Meaning
401	UNAUTHORIZED	Missing header, invalid key, or revoked key
403	FORBIDDEN	API access disabled (Free plan, blocked billing, or entitlement off)
429	RATE_LIMITED	Per-minute limit exceeded — wait for Retry-After

Async jobs — polling only

Webhooks are not available in v1. Long-running work returns job identifiers; poll the matching results endpoint until jobs reach a terminal state.

Each analysis family has its own start and results endpoints — you do not poll a single generic endpoint for everything (see Job ID formats below).

Typical enrichment flow — note that enrichment is selected by creator_ids, not by profile_url:

# 1) Start enrichment for one or more creators (UUIDs from search/discovery)
curl -X POST https://api.toksta.com/v1/creators/enrich \
  -H "Authorization: Bearer tk_live_<your-secret>" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["f0e1d2c3-b4a5-4678-9abc-def012345678"]}'

# 2) Fetch results by the SAME creator_ids (enrichment has no per-job poll endpoint)
curl -X POST https://api.toksta.com/v1/enrichments/results \
  -H "Authorization: Bearer tk_live_<your-secret>" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["f0e1d2c3-b4a5-4678-9abc-def012345678"], "wait_seconds": 20}'

If every requested creator is already enriched, POST /v1/creators/enrich returns 200 with jobs_created: 0 and all_complete: true (no job IDs) — go straight to POST /v1/enrichments/results. Otherwise it returns 202.

Thought leaders runs as an async discovery job (requires at least 5 keywords). Start the job, then poll with the plain UUID job ID:

# 1) Start thought leaders search (returns 202 with job_id)
curl -X POST https://api.toksta.com/v1/creators/thought-leaders \
  -H "Authorization: Bearer tk_live_<your-secret>" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["B2B SaaS", "demand generation", "marketing analytics", "growth", "ABM"], "count": 10, "mode": "balanced"}'

# 2) Poll job status
curl https://api.toksta.com/v1/jobs/<job_id> \
  -H "Authorization: Bearer tk_live_<your-secret>"

# 3) Fetch results when status is terminal
curl -X POST https://api.toksta.com/v1/jobs/results \
  -H "Authorization: Bearer tk_live_<your-secret>" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<job_id>", "wait_seconds": 20}'

Credits are reserved up front from max_candidates_to_analyze and mode (broad: 1, balanced: 2, strict: 3 credits per creator analyzed); unused credits are refunded after completion.

Poll while results report pending/status of queued or running. Terminal states: succeeded, failed, canceled, expired. You can also pass wait_seconds (max 30) on results endpoints to poll inline server-side.

Polling tips:

• Use exponential backoff (start ~2 s, cap ~30 s), or use wait_seconds for short inline waits.
• Retry results calls on 5xx and 429.
• Do not resubmit the same start POST unless the job failed or you intentionally want a new run.

Job ID formats

Job identifiers are not uniform across endpoint families. Use the right format with the right endpoint:

Endpoint family	Start endpoint	ID format	Example	Retrieve results with
Creator discovery / thought leaders	POST /v1/creators/thought-leaders, campaign discovery	Plain UUID	56232ac2-8068-4dcb-9d1a-1f2e3a4b5c6d	GET /v1/jobs/{id}, POST /v1/jobs/results, POST /v1/jobs/results:bulk
Enrichment	POST /v1/creators/enrich	enrichment:<uuid> (informational)	enrichment:f0e1d2c3-...	POST /v1/enrichments/results with creator_ids
Content match	POST /v1/creators/content-match	Prefixed content-fit:<uuid>	content-fit:56232ac2-...	POST /v1/content-match/results, /posts
Audience match	POST /v1/creators/audience-match	Prefixed audience-fit:<uuid>	audience-fit:a5f1eeb5-...	POST /v1/audience-match/results, /details

Key rules:

• GET /v1/jobs/{id}, POST /v1/jobs/results, POST /v1/jobs/results:bulk, and POST /v1/jobs/{id}/cancel accept plain UUIDs only. They serve creator-discovery jobs. Content-fit / audience-fit / enrichment IDs are not findable there (they return 404).
• The content-match and audience-match results endpoints accept either the full prefixed ID (content-fit:<uuid> / audience-fit:<uuid>) or the bare analysis UUID. You do not need to strip the prefix yourself — both are accepted.
• Enrichment has no standalone job-status endpoint. Track it by re-querying POST /v1/enrichments/results with the original creator_ids.
• POST /v1/jobs/{id}/cancel requires a JSON body even if empty — send {}.

Rate limits

Authenticated responses include rate-limit headers:

Header	Description
X-RateLimit-Limit	Max requests in the current 60-second window
X-RateLimit-Remaining	Requests left in the window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Present on 429 — seconds until retry is safe

Dedicated API plan limits:

Plan	Requests / minute
API PAYG	20
API Build	30
API Scale	60
API Enterprise	150

Dedicated API vs SaaS workspace

	Dedicated API (Build / Scale / Enterprise / PAYG)	SaaS (Starter / Pro / Agency / PAYG)
Data endpoints (/v1/creators/*, analysis, evidence)	Yes	Yes, when api_access_enabled
Workspace endpoints (/v1/campaigns, /v1/creator-lists)	No — returns 403	Yes, when workspace_endpoints_enabled
Credit economics	Dedicated overage rates	SaaS monthly allocation + SaaS PAYG

Dedicated API plans are for data-only integrations. Campaign and creator-list management requires a SaaS workspace entitlement.

Error handling

All errors use a normalized envelope with error.code, error.message, and meta.request_id. Log request_id when contacting support.

HTTP	Code	Retry?
400	BAD_REQUEST, VALIDATION_ERROR	Fix the request
401	UNAUTHORIZED	Fix auth
402	INSUFFICIENT_CREDITS	Top up or upgrade
403	FORBIDDEN	Fix plan or entitlement
404	NOT_FOUND	Do not retry same ID
429	RATE_LIMITED	Back off per Retry-After
500	INTERNAL_ERROR	Retry with backoff; include request_id

Next steps

• Authentication — create, rotate, and revoke keys
• Pricing and Plans — credits, overage, and checkout
• Managing API Keys — self-serve key management in the app
• API Reference — full endpoint list (auto-generated from OpenAPI)

Legacy Partner API

The private beta Partner API has been replaced by Public API v1. If you still have beta access questions, contact support. See Legacy Partner API (beta).