Die Entwicklerdokumentation gibt es vorerst nur auf Englisch. Der Rest der Website ist auf Deutsch.

API reference

Generated from the schemas the API validates against, so a field listed here is a field the API accepts.

OpenAPI 3.1: https://api.50heads.com/openapi.json. Generated from the same schemas, so it never drifts from this page. Load it into Postman, Insomnia or a client generator.

Pricing and config

Unauthenticated and rate limited. Estimate as often as you like; it never spends.

POST`/v1/billing/estimate`

Price, time and validation for a question draft.

No authentication.

Counts as half a request against the rate limit. validation lists anything that would stop the ask, one issue per field.

Request body (JSON)
Field	Type	Notes
`draft`	`object`	required
`draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`draft.text`	`string`	required up to 600 characters
`draft.context`	`string`	up to 120 characters
`draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`draft.options`	`object[]`	up to 8 items, default []
`draft.options[].label`	`string`	required up to 40 characters
`draft.options[].imageUrl`	`string (URL)`
`draft.options[].imageUrls`	`string (URL)[]`	up to 4 items
`draft.scaleLabels`	`object`
`draft.scaleLabels.low`	`string`	required up to 24 characters
`draft.scaleLabels.high`	`string`	required up to 24 characters
`draft.neither`	`boolean`	default false
`draft.stimulus`	`object`
`draft.stimulus.imageUrl`	`string (URL)`
`draft.stimulus.audioUrl`	`string (URL)`
`draft.stimulus.text`	`string`	up to 120 characters
`draft.stimulus.exposureMs`	`integer`	2000–10000
`draft.n`	`integer`	10–5000, default 50
`draft.tier`	`1 \| 2 \| 3`	default 1
`draft.rush`	`boolean`	default false
`draft.targeting`	`object`
`draft.targeting.countries`	`string[]`	up to 50 items, default []
`draft.targeting.tags`	`string[]`	up to 20 items, default []
`draft.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`draft.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`draft.targeting.verifiedAge`	`boolean`
`draft.clickTest`	`object`
`draft.clickTest.maxTaps`	`integer`	1–5, default 1
`draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`draft.publicResults`	`boolean`	default false
`draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`draft.goRule`	`object`
`draft.goRule.goAbove`	`number`	required 0.5–0.95
`draft.goRule.minAnswers`	`integer`	required 5–5000
`draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`draft.interestAudienceId`	`string`	up to 40 characters
`draft.minGrade`	`1 \| 2 \| 3`
`draft.interestPrice`	`object`
`draft.interestPrice.perAnswerPence`	`integer`	required 1–10000
`draft.interestPrice.headShareBps`	`integer`	required 0–10000
`draft.answeredBy`	`"heads" \| "private"`	default "heads"
`draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`draft.shownAs`	`string`	up to 40 characters
`surface`	`"app" \| "web"`

Response (JSON)
Field	Type	Notes
`creditsPerAnswer`	`integer`	required
`creditsTotal`	`integer`	required
`payPerAnswer`	`integer`	required
`etaMinutes`	`integer`	required
`traits`	`integer`	required
`breakdown`	`object[]`	required
`breakdown[].label`	`string`	required
`breakdown[].value`	`string`	required
`breakdownLine`	`string`	required
`validation`	`object[]`	required
`validation[].field`	`string`	required
`validation[].code`	`string`	required
`validation[].message`	`string`	required
`poolSize`	`integer \| null`	required

GET`/v1/config`

Credit exchange rates, the country table and question languages.

No authentication.

Response (JSON)
Field	Type	Notes
`rates`	`map of number`	required
`ratesDate`	`string`	required
`countries`	`map of object`	required
`defaultCountry`	`object`	required
`defaultCountry.minWithdrawalPence`	`integer`	required
`defaultCountry.payoutRails`	`string[]`	required
`defaultCountry.otpChannel`	`"sms" \| "whatsapp"`	required
`defaultCountry.taxFields`	`string[]`	required
`defaultCountry.tier2Available`	`boolean`	required
`defaultCountry.currency`	`"GBP" \| "USD" \| "EUR" \| "CAD"`	required
`defaultCountry.displayCurrency`	`"GBP" \| "USD" \| "EUR" \| "CAD" \| "JPY" \| "KRW" \| "BRL" \| "TRY" \| "SEK" \| "DKK" \| "NOK" \| "PLN" \| "CZK" \| "RON"`
`defaultCountry.wiseFields`	`object[]`
`defaultCountry.wiseFields[].key`	`string`	required
`defaultCountry.wiseFields[].label`	`string`	required
`defaultCountry.wiseFields[].example`	`string`
`defaultCountry.wiseFields[].pattern`	`string`
`defaultCountry.requesterRails`	`"card" \| "bank_transfer" \| "pix" \| "swish" \| "vipps" \| "mobilepay" \| "pse"[]`
`defaultCountry.locale`	`string`
`defaultCountry.questionLanguages`	`string[]`
`defaultCountry.legalPack`	`"uk" \| "gdpr-eu" \| "gdpr-eea" \| "us" \| "ca" \| "lgpd" \| "appi" \| "pipa" \| "kvkk" \| "cl" \| "co" \| "ar" \| "pe" \| "uy" \| "other"`
`defaultCountry.legalPackVersion`	`string`	up to 40 characters
`defaultCountry.payoutProvenAt`	`string`	up to 40 characters
`defaultCountry.minAge`	`integer`	13–21
`defaultCountry.state`	`"known" \| "answering" \| "launched"`
`questionLanguages`	`"en" \| "fr" \| "es" \| "pt" \| "it" \| "de" \| "nl" \| "pl" \| "ja" \| "ko" \| "sv" \| "da" \| "nb" \| "cs" \| "ro" \| "fi" \| "tr"[]`	required
`reverifyDays`	`integer`	required
`tier1PayPence`	`integer`	required
`tier2PayMultiplier`	`number`	required
`answeringCountries`	`string[]`
`tremendous`	`"off" \| "on" \| "default"`
`webTopUpStorefronts`	`string[]`
`storeCreditPacks`	`object[]`
`storeCreditPacks[].productId`	`string`	required
`storeCreditPacks[].credits`	`integer`	required

POST`/v1/estimate`

A quick price and time from a tier, a number of heads and images.

No authentication.

Never spends. Defaults: tier1, 50 heads, no images. For a real question (targeting, question type, validation) send a draft to POST /v1/billing/estimate; this route also accepts that body when it has a draft. Counts against the same rate limit.

Request body (JSON)
Field	Type	Notes
`tier`	`"tier1" \| "tier2" \| "tier3"`	default "tier1"
`n`	`integer`	10–5000, default 50
`images`	`integer`	0–4, default 0

Response (JSON)
Field	Type	Notes
`estimate`	`object`	required
`estimate.tier`	`"tier1" \| "tier2" \| "tier3"`	required
`estimate.n`	`integer`	required
`estimate.images`	`integer`	required
`estimate.perAnswerPence`	`integer`	required
`estimate.totalPence`	`integer`	required
`estimate.payPerSayPence`	`integer`	required
`estimate.etaMinutes`	`integer`	required
`line`	`string`	required
`creditsPerAnswer`	`integer`	required
`creditsTotal`	`integer`	required
`payPerAnswer`	`integer`	required
`etaMinutes`	`integer`	required
`price`	`object`	required
`poolSize`	`integer \| null`	required
`validation`	`object[]`	required
`validation[].field`	`string`	required
`validation[].code`	`string`	required
`validation[].message`	`string`	required

GET`/v1/config/platform`

Whether asking through MCP is paused, the minimum app versions and the feature flags.

No authentication.

Read by the MCP server before it asks. Safe to cache for a minute.

Response (JSON)
Field	Type	Notes
`killSwitch`	`object`	required
`killSwitch.pauseAsking`	`boolean`	required
`killSwitch.pauseAnswering`	`boolean`	required
`killSwitch.message`	`string \| null`	required
`killSwitch.until`	`string \| null`	required
`appVersions`	`object`	required
`appVersions.minimumIos`	`string`	required
`appVersions.minimumAndroid`	`string`	required
`mcp`	`object`	required
`mcp.pauseAsk`	`boolean`	required
`mcp.pausedClients`	`string[]`	required
`mcp.minProtocolVersion`	`string \| null`	required
`mcp.message`	`string \| null`	required
`flags`	`map of object`	required

GET`/v1/templates`

Fixed-price question templates.

No authentication.

Response (JSON)
Field	Type	Notes
`templates`	`object[]`	required
`templates[].id`	`string`	required
`templates[].name`	`string`	required
`templates[].description`	`string`	required
`templates[].draft`	`object`	required
`templates[].draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`templates[].draft.text`	`string`	required up to 600 characters
`templates[].draft.context`	`string`	up to 120 characters
`templates[].draft.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`templates[].draft.options`	`object[]`	required up to 8 items, default []
`templates[].draft.scaleLabels`	`object`
`templates[].draft.neither`	`boolean`	required default false
`templates[].draft.stimulus`	`object`
`templates[].draft.n`	`integer`	required 10–5000, default 50
`templates[].draft.tier`	`1 \| 2 \| 3`	required default 1
`templates[].draft.rush`	`boolean`	required default false
`templates[].draft.targeting`	`object`
`templates[].draft.clickTest`	`object`
`templates[].draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`templates[].draft.publicResults`	`boolean`	required default false
`templates[].draft.reason`	`"off" \| "optional" \| "required"`	required default "off"
`templates[].draft.goRule`	`object`
`templates[].draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`templates[].draft.interestAudienceId`	`string`	up to 40 characters
`templates[].draft.minGrade`	`1 \| 2 \| 3`
`templates[].draft.interestPrice`	`object`
`templates[].draft.answeredBy`	`"heads" \| "private"`	required default "heads"
`templates[].draft.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`templates[].draft.shownAs`	`string`	up to 40 characters
`templates[].priceCredits`	`integer`	required

GET`/v1/public/countries`

Where heads answer from, the languages they read and pool size bands by tier.

No authentication.

Response (JSON)
Field	Type	Notes
`countries`	`object[]`	required
`countries[].code`	`string`	required up to 2 characters, at least 2 characters
`countries[].name`	`string`	required
`countries[].languages`	`string[]`	required
`countries[].tier2Available`	`boolean`	required
`countries[].poolBands`	`object`	required
`countries[].poolBands.tier1`	`string \| null`	required
`countries[].poolBands.tier2`	`string \| null`	required
`countries[].poolBands.tier3`	`string \| null`	required
`updatedAt`	`string`	required

GET`/v1/tags`

The self-declared tags you can target at any tier, by group (one trait per group).

No authentication.

Response (JSON)
Field	Type	Notes
`groups`	`object[]`	required
`groups[].id`	`"life_stage" \| "household" \| "income" \| "education" \| "occupation" \| "interests" \| "habits" \| "shopping" \| "health" \| "media" \| "pets" \| "tech"`	required
`groups[].label`	`string`	required
`groups[].why`	`string`	required
`groups[].max`	`integer`	required
`tags`	`object[]`	required
`tags[].id`	`string`	required
`tags[].group`	`"life_stage" \| "household" \| "income" \| "education" \| "occupation" \| "interests" \| "habits" \| "shopping" \| "health" \| "media" \| "pets" \| "tech"`	required
`tags[].label`	`string`	required

GET`/v1/public/stats`

Heads online now, answers this week and the median time to fifty answers.

No authentication.

Response (JSON)
Field	Type	Notes
`headsOnlineNow`	`integer`	required
`answersThisWeek`	`integer`	required
`medianMinutesTo50`	`number`	required
`headEarningsPerHour`	`object`	required
`headEarningsPerHour.low`	`integer`	required
`headEarningsPerHour.high`	`integer`	required
`updatedAt`	`string`	required

GET`/v1/public/subprocessors`

Upcoming and past changes to our subprocessors, with their effective dates.

No authentication.

Cacheable for an hour. We email every account holder before adding or changing a subprocessor, and give at least 30 days' notice (noticeDays). upcoming holds announced changes that have not taken effect, soonest first; history holds the rest, newest first. Drafts are never listed. The current list itself is on the subprocessors page.

Response (JSON)
Field	Type	Notes
`upcoming`	`object[]`	required
`upcoming[].id`	`string`	required
`upcoming[].kind`	`"add" \| "remove" \| "change"`	required
`upcoming[].name`	`string`	required
`upcoming[].purpose`	`string`	required
`upcoming[].dataCategories`	`string`	required
`upcoming[].location`	`string`	required
`upcoming[].transferMechanism`	`string`	required
`upcoming[].link`	`string \| null`	required
`upcoming[].status`	`"announced" \| "effective" \| "withdrawn"`	required
`upcoming[].announcedAt`	`string`	required
`upcoming[].effectiveAt`	`string`	required
`upcoming[].withdrawnAt`	`string \| null`	required
`history`	`object[]`	required
`history[].id`	`string`	required
`history[].kind`	`"add" \| "remove" \| "change"`	required
`history[].name`	`string`	required
`history[].purpose`	`string`	required
`history[].dataCategories`	`string`	required
`history[].location`	`string`	required
`history[].transferMechanism`	`string`	required
`history[].link`	`string \| null`	required
`history[].status`	`"announced" \| "effective" \| "withdrawn"`	required
`history[].announcedAt`	`string`	required
`history[].effectiveAt`	`string`	required
`history[].withdrawnAt`	`string \| null`	required
`noticeDays`	`integer`	required
`updatedAt`	`string`	required

Status, identity and limits

Read these before you spend: whether 50heads is working and asking is open, who your key or grant acts as, and the rate limits on it. Every response that counts against a limit carries RateLimit-Policy, RateLimit, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers; a 429 also carries Retry-After.

GET`/v1/status`

Whether 50heads is working, and whether asking, answering, MCP asking or top-ups are paused.

No authentication.

Cached for 15 seconds. 503 with the same body when the database is not answering. An agent should not ask while asking or mcp_asking is paused; nothing is charged while paused.

Response (JSON)
Field	Type	Notes
`status`	`"operational" \| "degraded" \| "paused" \| "outage"`	required
`components`	`object[]`	required
`components[].id`	`"api" \| "database" \| "asking" \| "answering" \| "mcp_asking" \| "top_ups"`	required
`components[].status`	`"operational" \| "degraded" \| "paused" \| "outage"`	required
`components[].note`	`string \| null`	required
`message`	`string \| null`	required
`until`	`string \| null`	required
`checkedAt`	`string`	required
`page`	`string`	required

GET`/v1/whoami`

Who this credential is, its scopes, its connection's caps and spend, and the account and organization it acts in.

API key or OAuth token.

Any key, connected app, service account or signed-in person; no scope needed. organization is null unless organizations are switched on for the team (and, for keys and apps, machine identities too).

Response (JSON)
Field	Type	Notes
`principal`	`object`	required
`principal.type`	`"person" \| "service_account"`	required
`principal.id`	`string`	required
`principal.email`	`string \| null`	required
`auth`	`"session" \| "api_key" \| "oauth" \| "device"`	required
`scopes`	`string[] \| null`	required
`connection`	`object \| null`	required
`connection.id`	`string`	required
`connection.kind`	`"oauth" \| "key" \| "app"`	required
`connection.clientId`	`string \| null`	required
`connection.clientName`	`string`	required
`connection.host`	`string \| null`	required
`connection.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`connection.capDailyPence`	`integer`	required
`connection.spentTodayPence`	`integer`	required
`connection.spentMonthPence`	`integer`	required
`connection.protocolVersion`	`string \| null`	required
`connection.validatesIss`	`boolean \| null`	required
`connection.createdAt`	`string`	required
`connection.lastUsedAt`	`string \| null`	required
`connection.capMonthlyPence`	`integer \| null`
`connection.capQuestionPence`	`integer \| null`
`connection.teamId`	`string \| null`
`account`	`object`	required
`account.kind`	`"personal" \| "team"`	required
`account.teamId`	`string \| null`	required
`account.teamName`	`string \| null`	required
`account.role`	`"owner" \| "admin" \| "member" \| "viewer" \| "billing" \| null`	required
`organization`	`object \| null`	required
`organization.id`	`string`	required
`organization.name`	`string`	required
`organization.admin`	`boolean`	required

GET`/v1/limits`

The rate limits on this account and connection, with what is used in the current window.

API key or OAuth token.

Any credential; no scope needed. Counts are approximate (a brake on runaway loops, not a quota). The MCP server's own limits are listed with used: null.

Response (JSON)
Field	Type	Notes
`policies`	`object[]`	required
`policies[].id`	`string`	required
`policies[].appliesTo`	`string`	required
`policies[].per`	`"account" \| "connection"`	required
`policies[].limit`	`integer`	required
`policies[].windowSeconds`	`integer`	required
`policies[].used`	`integer \| null`	required
`policies[].remaining`	`integer \| null`	required
`policies[].resetSeconds`	`integer`	required
`note`	`string`	required

Questions

Ask, wait and read results. Asking reserves the full price from your credits; answers not given are refunded when the question closes.

POST`/v2/questions`

Ask a question.

API key or OAuth token with questions:write. Idempotency-Key header required.

Requires an Idempotency-Key header (a UUID). The same key returns the same question for 24 hours; a different body with the same key is idempotency_conflict. Fails with insufficient_credits, spend_cap_reached or content_refused without spending anything. The portal and app are reminded once with 422 quality_reminder (nothing stored or charged) when the wording review has a strong suggestion the writer has not taken; ask again with acknowledgeQuality: true and the same key to send it as written. The API and MCP are never reminded.

Request body (JSON)
Field	Type	Notes
`draft`	`object`	required
`draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`draft.text`	`string`	required up to 600 characters
`draft.context`	`string`	up to 120 characters
`draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`draft.options`	`object[]`	up to 8 items, default []
`draft.options[].label`	`string`	required up to 40 characters
`draft.options[].imageUrl`	`string (URL)`
`draft.options[].imageUrls`	`string (URL)[]`	up to 4 items
`draft.scaleLabels`	`object`
`draft.scaleLabels.low`	`string`	required up to 24 characters
`draft.scaleLabels.high`	`string`	required up to 24 characters
`draft.neither`	`boolean`	default false
`draft.stimulus`	`object`
`draft.stimulus.imageUrl`	`string (URL)`
`draft.stimulus.audioUrl`	`string (URL)`
`draft.stimulus.text`	`string`	up to 120 characters
`draft.stimulus.exposureMs`	`integer`	2000–10000
`draft.n`	`integer`	10–5000, default 50
`draft.tier`	`1 \| 2 \| 3`	default 1
`draft.rush`	`boolean`	default false
`draft.targeting`	`object`
`draft.targeting.countries`	`string[]`	up to 50 items, default []
`draft.targeting.tags`	`string[]`	up to 20 items, default []
`draft.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`draft.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`draft.targeting.verifiedAge`	`boolean`
`draft.clickTest`	`object`
`draft.clickTest.maxTaps`	`integer`	1–5, default 1
`draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`draft.publicResults`	`boolean`	default false
`draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`draft.goRule`	`object`
`draft.goRule.goAbove`	`number`	required 0.5–0.95
`draft.goRule.minAnswers`	`integer`	required 5–5000
`draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`draft.interestAudienceId`	`string`	up to 40 characters
`draft.minGrade`	`1 \| 2 \| 3`
`draft.interestPrice`	`object`
`draft.interestPrice.perAnswerPence`	`integer`	required 1–10000
`draft.interestPrice.headShareBps`	`integer`	required 0–10000
`draft.answeredBy`	`"heads" \| "private"`	default "heads"
`draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`draft.shownAs`	`string`	up to 40 characters
`fromDraftId`	`string`
`then`	`object[]`	up to 3 items
`then[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	default "free_text"
`then[].text`	`string`	required up to 600 characters, at least 8 characters
`then[].options`	`object[]`	up to 8 items, default []
`then[].options[].label`	`string`	required up to 40 characters
`then[].options[].imageUrl`	`string (URL)`
`then[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`then[].n`	`integer`	10–5000, default 20
`then[].tier`	`1 \| 2 \| 3`	default 2
`then[].minConfidence`	`"low" \| "medium" \| "high"`
`then[].reason`	`"off" \| "optional" \| "required"`
`variantOf`	`string`
`followUpOf`	`string`	up to 64 characters
`templateId`	`string`
`projectId`	`string \| null`
`labels`	`string[]`	up to 10 items
`externalRef`	`string`	up to 100 characters, pattern ^[\w.:\-/#@+]+$
`privateDeclaration`	`object`
`privateDeclaration.version`	`integer`	required ≥ 1
`acknowledgeQuality`	`boolean`

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`

GET`/v2/questions`

Your questions, newest first.

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`
`since`	`string`
`limit`	`integer`	1–100
`cursor`	`string`
`projectId`	`string`
`label`	`string`
`externalRef`	`string`
`archived`	`"exclude" \| "only" \| "include"`
`bookmarked`	`boolean`
`mine`	`boolean`
`setId`	`string`

Response (JSON)
Field	Type	Notes
`questions`	`object[]`	required
`questions[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`questions[].text`	`string`	required up to 600 characters
`questions[].context`	`string`	up to 120 characters
`questions[].language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`questions[].options`	`object[]`	required up to 8 items, default []
`questions[].options[].label`	`string`	required up to 40 characters
`questions[].options[].imageUrl`	`string (URL)`
`questions[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`questions[].scaleLabels`	`object`
`questions[].scaleLabels.low`	`string`	required up to 24 characters
`questions[].scaleLabels.high`	`string`	required up to 24 characters
`questions[].neither`	`boolean`	required default false
`questions[].stimulus`	`object`
`questions[].stimulus.imageUrl`	`string (URL)`
`questions[].stimulus.audioUrl`	`string (URL)`
`questions[].stimulus.text`	`string`	up to 120 characters
`questions[].stimulus.exposureMs`	`integer`	2000–10000
`questions[].n`	`integer`	required 10–5000, default 50
`questions[].tier`	`1 \| 2 \| 3`	required default 1
`questions[].rush`	`boolean`	required default false
`questions[].targeting`	`object`
`questions[].targeting.countries`	`string[]`	required up to 50 items, default []
`questions[].targeting.tags`	`string[]`	required up to 20 items, default []
`questions[].targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`questions[].targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`questions[].targeting.verifiedAge`	`boolean`
`questions[].clickTest`	`object`
`questions[].clickTest.maxTaps`	`integer`	required 1–5, default 1
`questions[].scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`questions[].publicResults`	`boolean`	required default false
`questions[].reason`	`"off" \| "optional" \| "required"`	required default "off"
`questions[].goRule`	`object`
`questions[].goRule.goAbove`	`number`	required 0.5–0.95
`questions[].goRule.minAnswers`	`integer`	required 5–5000
`questions[].contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`questions[].interestAudienceId`	`string`	up to 40 characters
`questions[].minGrade`	`1 \| 2 \| 3`
`questions[].interestPrice`	`object`
`questions[].interestPrice.perAnswerPence`	`integer`	required 1–10000
`questions[].interestPrice.headShareBps`	`integer`	required 0–10000
`questions[].answeredBy`	`"heads" \| "private"`	required default "heads"
`questions[].openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`questions[].shownAs`	`string`	up to 40 characters
`questions[].id`	`string`	required
`questions[].status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`questions[].source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`questions[].answered`	`integer`	required
`questions[].creditsPerAnswer`	`integer`	required
`questions[].creditsReserved`	`integer`	required
`questions[].creditsSpent`	`integer`	required
`questions[].etaMinutes`	`integer`	required
`questions[].leaderLine`	`string \| null`	required
`questions[].refusedCategory`	`string \| null`	required
`questions[].publicCode`	`string \| null`	required
`questions[].createdAt`	`string`	required
`questions[].liveAt`	`string \| null`	required
`questions[].closedAt`	`string \| null`	required
`questions[].teamId`	`string \| null`
`questions[].askedBy`	`object \| null`
`questions[].askedBy.id`	`string`	required
`questions[].askedBy.name`	`string \| null`	required
`questions[].projectId`	`string \| null`
`questions[].labels`	`string[]`
`questions[].archived`	`boolean`
`questions[].bookmarked`	`boolean`
`questions[].externalRef`	`string \| null`
`questions[].link`	`object \| null`
`questions[].link.url`	`string`	required
`questions[].link.qrSvgUrl`	`string`	required
`questions[].link.qrPngUrl`	`string`	required
`questions[].link.closesAt`	`string \| null`	required
`questions[].link.views`	`integer`	required
`questions[].link.started`	`integer`	required
`questions[].setId`	`string \| null`
`questions[].setPosition`	`integer \| null`
`questions[].setCount`	`integer \| null`
`nextCursor`	`string \| null`	required

GET`/v2/questions/{id}`

One question and its progress.

API key or OAuth token with questions:read.

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`

PATCH`/v2/questions/{id}`

Complete early once minAnswers heads have answered, or file it: project, labels, archive, bookmark and a set-once externalRef.

API key or OAuth token with questions:write.

If that many have already answered, the question closes now and what was not answered is refunded. Changing an externalRef once set is refused with 409 external_ref_set.

Request body (JSON)
Field	Type	Notes
`minAnswers`	`integer`	1–5000
`projectId`	`string \| null`
`labels`	`string[]`	up to 10 items
`archived`	`boolean`
`bookmarked`	`boolean`
`externalRef`	`string`	up to 100 characters, pattern ^[\w.:\-/#@+]+$

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`

GET`/v2/questions/labels`

Labels in use in the account, most used first.

API key or OAuth token with questions:read.

Response (JSON)
Field	Type	Notes
`labels`	`object[]`	required
`labels[].label`	`string`	required
`labels[].count`	`integer`	required

GET`/v2/questions/{id}/result`

The result so far. Partial while the question is live.

API key or OAuth token with questions:read.

With a filter, the distribution, breakdowns and answers are of matching answers only; nUnfiltered counts them all and suppressed is true when a country or age band matched too few to show. insights is the summary of written answers once there is one.

Query parameters
Field	Type	Notes
`option`	`integer`	0–8
`tier`	`integer`	1–3
`country`	`string`	up to 2 characters, at least 2 characters
`age_band`	`string`
`q`	`string`	up to 100 characters

Response (JSON)
Field	Type	Notes
`result`	`object`	required
`result.questionId`	`string`	required
`result.status`	`"in_progress" \| "complete" \| "underfilled" \| "canceled"`	required
`result.nRequested`	`integer`	required
`result.nAccepted`	`integer`	required
`result.distribution`	`object[]`	required
`result.distribution[].option`	`string`	required
`result.distribution[].count`	`integer`	required
`result.distribution[].share`	`number`	required
`result.distribution[].averageRank`	`number`
`result.distribution[].mean`	`number`
`result.distribution[].ratings`	`integer[]`	up to 5 items
`result.distribution[].appearances`	`integer`
`result.distribution[].strength`	`number`
`result.distribution[].rank`	`integer`
`result.distribution[].low`	`number`
`result.distribution[].high`	`number`
`result.mean`	`number \| null`	required
`result.scaleLabels`	`object \| null`
`result.scaleLabels.low`	`string`	required up to 24 characters
`result.scaleLabels.high`	`string`	required up to 24 characters
`result.summary`	`object`	required
`result.summary.winner`	`string \| null`	required
`result.summary.margin`	`number \| null`	required
`result.summary.confidence`	`"low" \| "medium" \| "high" \| null`	required
`result.summary.note`	`string`	required
`result.summary.suggestedFollowUp`	`string \| null`	required
`result.tier`	`integer \| null`	required
`result.language`	`string`	required
`result.verificationLine`	`string`	required
`result.provenance`	`object`
`result.provenance.answeredBy`	`"heads" \| "private"`	required
`result.provenance.access`	`"app" \| "shared_link"`	required
`result.provenance.verified`	`boolean`	required
`result.provenance.answers`	`integer`	required
`result.provenance.issued`	`integer \| null`	required
`result.provenance.denominator`	`"known" \| "unknown"`	required
`result.medianSeconds`	`number \| null`	required
`result.creditsSpent`	`integer`	required
`result.answers`	`object[]`	required
`result.answers[].option`	`string \| null`	required
`result.answers[].text`	`string \| null`	required
`result.answers[].translatedText`	`string \| null`
`result.answers[].reason`	`string \| null`
`result.answers[].translatedReason`	`string \| null`
`result.answers[].tier`	`integer \| null`	required
`result.answers[].attestationRef`	`string \| null`	required
`result.answers[].answeredAt`	`string`	required
`result.answers[].pinned`	`boolean`
`result.answers[].flag`	`object \| null`
`result.answers[].taps`	`object[]`
`result.answers[].choice`	`object`
`result.breakdown`	`object[]`
`result.breakdown[].tagId`	`string`	required
`result.breakdown[].label`	`string`	required
`result.breakdown[].n`	`integer`	required
`result.breakdown[].distribution`	`object[]`	required
`result.refundCredits`	`integer`	required
`result.breakdowns`	`object[]`
`result.breakdowns[].dimension`	`"country" \| "tier" \| "age_band" \| "gender" \| "tag" \| "language"`	required
`result.breakdowns[].segments`	`object[]`	required
`result.clicks`	`object`
`result.clicks.imageUrl`	`string \| null`	required
`result.clicks.taps`	`integer`	required
`result.clicks.points`	`object[]`	required
`result.clicks.grid`	`integer[]`	required
`result.clicks.gridSize`	`integer`	required
`result.clicks.hotspots`	`object[]`	required
`result.clicks.heatmapUrl`	`string \| null`	required
`result.sentiment`	`object`
`result.sentiment.positive`	`number`	required
`result.sentiment.neutral`	`number`	required
`result.sentiment.negative`	`number`	required
`result.translationLanguage`	`string \| null`
`result.insights`	`object \| null`
`result.insights.questionId`	`string`	required
`result.insights.language`	`string`	required
`result.insights.sourceLanguage`	`string`	required
`result.insights.takeaway`	`string`	required
`result.insights.themes`	`object[]`	required up to 8 items
`result.insights.findings`	`object[]`	up to 5 items
`result.insights.byOption`	`object[]`	up to 9 items
`result.insights.followUp`	`object \| null`
`result.insights.sentiment`	`object`	required
`result.insights.basedOn`	`integer`	required
`result.insights.answersAtTime`	`integer`	required
`result.insights.original`	`object \| null`	required
`result.insights.kind`	`"interim" \| "final"`	required
`result.insights.generatedAt`	`string`	required
`result.insights.refreshAfter`	`string \| null`	required
`result.insights.engine`	`string`	required
`result.filter`	`object`
`result.filter.option`	`integer`	0–8
`result.filter.tier`	`integer`	1–3
`result.filter.country`	`object`
`result.filter.ageBand`	`string`	pattern ^[0-9]{2}(-[0-9]{2}\|\+)$
`result.filter.gender`	`"woman" \| "man" \| "non_binary"`
`result.filter.q`	`string`	up to 100 characters
`result.nUnfiltered`	`integer`
`result.suppressed`	`boolean`
`result.facets`	`object`
`result.facets.tiers`	`object[]`	required
`result.facets.countries`	`object[]`	required
`result.facets.ageBands`	`object[]`	required
`result.facets.genders`	`object[]`
`result.verdict`	`object`
`result.verdict.verdict`	`"go" \| "no_go" \| "unclear"`	required
`result.verdict.reason`	`"too_few" \| "too_close" \| null`	required
`result.verdict.yesShare`	`number`	required
`result.verdict.low`	`number`	required
`result.verdict.high`	`number`	required
`result.verdict.goAbove`	`number`	required
`result.verdict.minAnswers`	`integer`	required
`result.verdict.n`	`integer`	required
`result.headToHead`	`object`
`result.headToHead.options`	`string[]`	required
`result.headToHead.share`	`number \| null[][]`	required
`result.headToHead.n`	`integer[][]`	required
`result.cohortHash`	`string`

GET`/v2/questions/{id}/answers`

Matching answers, newest first, a page at a time, with reasons and translations.

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`option`	`integer`	0–8
`tier`	`integer`	1–3
`country`	`string`	up to 2 characters, at least 2 characters
`age_band`	`string`
`q`	`string`	up to 100 characters
`limit`	`integer`	1–200
`cursor`	`string`	up to 200 characters

Response (JSON)
Field	Type	Notes
`questionId`	`string`	required
`filter`	`object`	required
`filter.option`	`integer`	0–8
`filter.tier`	`integer`	1–3
`filter.country`	`object`
`filter.ageBand`	`string`	pattern ^[0-9]{2}(-[0-9]{2}\|\+)$
`filter.gender`	`"woman" \| "man" \| "non_binary"`
`filter.q`	`string`	up to 100 characters
`total`	`integer`	required
`nUnfiltered`	`integer`	required
`suppressed`	`boolean`	required
`answers`	`object[]`	required
`answers[].option`	`string \| null`	required
`answers[].text`	`string \| null`	required
`answers[].translatedText`	`string \| null`
`answers[].reason`	`string \| null`
`answers[].translatedReason`	`string \| null`
`answers[].tier`	`integer \| null`	required
`answers[].attestationRef`	`string \| null`	required
`answers[].answeredAt`	`string`	required
`answers[].pinned`	`boolean`
`answers[].flag`	`object \| null`
`answers[].flag.reason`	`"off_topic" \| "low_effort" \| "abusive" \| "automated"`	required
`answers[].flag.status`	`"open" \| "upheld" \| "dismissed"`	required
`answers[].flag.refundCredits`	`integer`	required
`answers[].flag.createdAt`	`string`	required
`answers[].flag.decidedAt`	`string \| null`	required
`answers[].taps`	`object[]`
`answers[].taps[].x`	`number`	required 0–1
`answers[].taps[].y`	`number`	required 0–1
`answers[].choice`	`object`
`answers[].choice.index`	`integer`
`answers[].choice.indexes`	`integer[]`
`answers[].choice.order`	`integer[]`
`answers[].choice.pair`	`array`	up to 2 items
`answers[].choice.ratings`	`integer[]`
`translationLanguage`	`string \| null`	required
`nextCursor`	`string \| null`	required

GET`/v2/questions/{id}/insights`

The summary of the written answers: themes with counts and quotes, sentiment, a takeaway.

API key or OAuth token with questions:read.

Made by a machine from the reasons and free text, never from who answered; counts and quotes are computed from the answers. Written in the account's language, with the question-language original.

Response (JSON)
Field	Type	Notes
`insights`	`object \| null`	required
`insights.questionId`	`string`	required
`insights.language`	`string`	required
`insights.sourceLanguage`	`string`	required
`insights.takeaway`	`string`	required
`insights.themes`	`object[]`	required up to 8 items
`insights.themes[].label`	`string`	required
`insights.themes[].count`	`integer`	required
`insights.themes[].share`	`number`	required
`insights.themes[].sentiment`	`"positive" \| "neutral" \| "negative"`	required
`insights.themes[].option`	`string \| null`	required
`insights.themes[].quotes`	`string[]`	required up to 3 items
`insights.findings`	`object[]`	up to 5 items
`insights.findings[].text`	`string`	required
`insights.findings[].count`	`integer`	required
`insights.findings[].option`	`string \| null`	required
`insights.findings[].quotes`	`string[]`	required up to 3 items
`insights.byOption`	`object[]`	up to 9 items
`insights.byOption[].option`	`string`	required
`insights.byOption[].n`	`integer`	required
`insights.byOption[].likes`	`object[]`	required up to 4 items
`insights.byOption[].dislikes`	`object[]`	required up to 4 items
`insights.followUp`	`object \| null`
`insights.followUp.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`insights.followUp.text`	`string`	required
`insights.followUp.options`	`string[]`	required up to 8 items
`insights.followUp.n`	`integer`	required 10–5000
`insights.followUp.tier`	`1 \| 2 \| 3`	required
`insights.followUp.reason`	`"off" \| "optional" \| "required"`	required
`insights.sentiment`	`object`	required
`insights.sentiment.positive`	`integer`	required
`insights.sentiment.neutral`	`integer`	required
`insights.sentiment.negative`	`integer`	required
`insights.basedOn`	`integer`	required
`insights.answersAtTime`	`integer`	required
`insights.original`	`object \| null`	required
`insights.original.takeaway`	`string`	required
`insights.original.themes`	`object[]`	required
`insights.original.findings`	`object[]`
`insights.original.followUp`	`object \| null`
`insights.kind`	`"interim" \| "final"`	required
`insights.generatedAt`	`string`	required
`insights.refreshAfter`	`string \| null`	required
`insights.engine`	`string`	required

POST`/v2/questions/{id}/insights`

Make a fresh summary now: once every 10 minutes while live; the final one when it closes.

API key or OAuth token with questions:read.

429 rate_limited with retryAfterMs while a recent summary stands; 409 too_few_answers under three written answers.

Response (JSON)
Field	Type	Notes
`insights`	`object \| null`	required
`insights.questionId`	`string`	required
`insights.language`	`string`	required
`insights.sourceLanguage`	`string`	required
`insights.takeaway`	`string`	required
`insights.themes`	`object[]`	required up to 8 items
`insights.themes[].label`	`string`	required
`insights.themes[].count`	`integer`	required
`insights.themes[].share`	`number`	required
`insights.themes[].sentiment`	`"positive" \| "neutral" \| "negative"`	required
`insights.themes[].option`	`string \| null`	required
`insights.themes[].quotes`	`string[]`	required up to 3 items
`insights.findings`	`object[]`	up to 5 items
`insights.findings[].text`	`string`	required
`insights.findings[].count`	`integer`	required
`insights.findings[].option`	`string \| null`	required
`insights.findings[].quotes`	`string[]`	required up to 3 items
`insights.byOption`	`object[]`	up to 9 items
`insights.byOption[].option`	`string`	required
`insights.byOption[].n`	`integer`	required
`insights.byOption[].likes`	`object[]`	required up to 4 items
`insights.byOption[].dislikes`	`object[]`	required up to 4 items
`insights.followUp`	`object \| null`
`insights.followUp.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`insights.followUp.text`	`string`	required
`insights.followUp.options`	`string[]`	required up to 8 items
`insights.followUp.n`	`integer`	required 10–5000
`insights.followUp.tier`	`1 \| 2 \| 3`	required
`insights.followUp.reason`	`"off" \| "optional" \| "required"`	required
`insights.sentiment`	`object`	required
`insights.sentiment.positive`	`integer`	required
`insights.sentiment.neutral`	`integer`	required
`insights.sentiment.negative`	`integer`	required
`insights.basedOn`	`integer`	required
`insights.answersAtTime`	`integer`	required
`insights.original`	`object \| null`	required
`insights.original.takeaway`	`string`	required
`insights.original.themes`	`object[]`	required
`insights.original.findings`	`object[]`
`insights.original.followUp`	`object \| null`
`insights.kind`	`"interim" \| "final"`	required
`insights.generatedAt`	`string`	required
`insights.refreshAfter`	`string \| null`	required
`insights.engine`	`string`	required

GET`/v2/questions/{id}/wait`

Hold the request until the question is answered, up to 25 seconds a call.

API key or OAuth token with questions:read.

Call again while done is false. minAnswers completes early once that many heads have answered.

Query parameters
Field	Type	Notes
`seconds`	`integer`	1–25
`minAnswers`	`integer`	≥ 1

Response (JSON)
Field	Type	Notes
`result`	`object`	required
`result.questionId`	`string`	required
`result.status`	`"in_progress" \| "complete" \| "underfilled" \| "canceled"`	required
`result.nRequested`	`integer`	required
`result.nAccepted`	`integer`	required
`result.distribution`	`object[]`	required
`result.distribution[].option`	`string`	required
`result.distribution[].count`	`integer`	required
`result.distribution[].share`	`number`	required
`result.distribution[].averageRank`	`number`
`result.distribution[].mean`	`number`
`result.distribution[].ratings`	`integer[]`	up to 5 items
`result.distribution[].appearances`	`integer`
`result.distribution[].strength`	`number`
`result.distribution[].rank`	`integer`
`result.distribution[].low`	`number`
`result.distribution[].high`	`number`
`result.mean`	`number \| null`	required
`result.scaleLabels`	`object \| null`
`result.scaleLabels.low`	`string`	required up to 24 characters
`result.scaleLabels.high`	`string`	required up to 24 characters
`result.summary`	`object`	required
`result.summary.winner`	`string \| null`	required
`result.summary.margin`	`number \| null`	required
`result.summary.confidence`	`"low" \| "medium" \| "high" \| null`	required
`result.summary.note`	`string`	required
`result.summary.suggestedFollowUp`	`string \| null`	required
`result.tier`	`integer \| null`	required
`result.language`	`string`	required
`result.verificationLine`	`string`	required
`result.provenance`	`object`
`result.provenance.answeredBy`	`"heads" \| "private"`	required
`result.provenance.access`	`"app" \| "shared_link"`	required
`result.provenance.verified`	`boolean`	required
`result.provenance.answers`	`integer`	required
`result.provenance.issued`	`integer \| null`	required
`result.provenance.denominator`	`"known" \| "unknown"`	required
`result.medianSeconds`	`number \| null`	required
`result.creditsSpent`	`integer`	required
`result.answers`	`object[]`	required
`result.answers[].option`	`string \| null`	required
`result.answers[].text`	`string \| null`	required
`result.answers[].translatedText`	`string \| null`
`result.answers[].reason`	`string \| null`
`result.answers[].translatedReason`	`string \| null`
`result.answers[].tier`	`integer \| null`	required
`result.answers[].attestationRef`	`string \| null`	required
`result.answers[].answeredAt`	`string`	required
`result.answers[].pinned`	`boolean`
`result.answers[].flag`	`object \| null`
`result.answers[].taps`	`object[]`
`result.answers[].choice`	`object`
`result.breakdown`	`object[]`
`result.breakdown[].tagId`	`string`	required
`result.breakdown[].label`	`string`	required
`result.breakdown[].n`	`integer`	required
`result.breakdown[].distribution`	`object[]`	required
`result.refundCredits`	`integer`	required
`result.breakdowns`	`object[]`
`result.breakdowns[].dimension`	`"country" \| "tier" \| "age_band" \| "gender" \| "tag" \| "language"`	required
`result.breakdowns[].segments`	`object[]`	required
`result.clicks`	`object`
`result.clicks.imageUrl`	`string \| null`	required
`result.clicks.taps`	`integer`	required
`result.clicks.points`	`object[]`	required
`result.clicks.grid`	`integer[]`	required
`result.clicks.gridSize`	`integer`	required
`result.clicks.hotspots`	`object[]`	required
`result.clicks.heatmapUrl`	`string \| null`	required
`result.sentiment`	`object`
`result.sentiment.positive`	`number`	required
`result.sentiment.neutral`	`number`	required
`result.sentiment.negative`	`number`	required
`result.translationLanguage`	`string \| null`
`result.insights`	`object \| null`
`result.insights.questionId`	`string`	required
`result.insights.language`	`string`	required
`result.insights.sourceLanguage`	`string`	required
`result.insights.takeaway`	`string`	required
`result.insights.themes`	`object[]`	required up to 8 items
`result.insights.findings`	`object[]`	up to 5 items
`result.insights.byOption`	`object[]`	up to 9 items
`result.insights.followUp`	`object \| null`
`result.insights.sentiment`	`object`	required
`result.insights.basedOn`	`integer`	required
`result.insights.answersAtTime`	`integer`	required
`result.insights.original`	`object \| null`	required
`result.insights.kind`	`"interim" \| "final"`	required
`result.insights.generatedAt`	`string`	required
`result.insights.refreshAfter`	`string \| null`	required
`result.insights.engine`	`string`	required
`result.filter`	`object`
`result.filter.option`	`integer`	0–8
`result.filter.tier`	`integer`	1–3
`result.filter.country`	`object`
`result.filter.ageBand`	`string`	pattern ^[0-9]{2}(-[0-9]{2}\|\+)$
`result.filter.gender`	`"woman" \| "man" \| "non_binary"`
`result.filter.q`	`string`	up to 100 characters
`result.nUnfiltered`	`integer`
`result.suppressed`	`boolean`
`result.facets`	`object`
`result.facets.tiers`	`object[]`	required
`result.facets.countries`	`object[]`	required
`result.facets.ageBands`	`object[]`	required
`result.facets.genders`	`object[]`
`result.verdict`	`object`
`result.verdict.verdict`	`"go" \| "no_go" \| "unclear"`	required
`result.verdict.reason`	`"too_few" \| "too_close" \| null`	required
`result.verdict.yesShare`	`number`	required
`result.verdict.low`	`number`	required
`result.verdict.high`	`number`	required
`result.verdict.goAbove`	`number`	required
`result.verdict.minAnswers`	`integer`	required
`result.verdict.n`	`integer`	required
`result.headToHead`	`object`
`result.headToHead.options`	`string[]`	required
`result.headToHead.share`	`number \| null[][]`	required
`result.headToHead.n`	`integer[][]`	required
`result.cohortHash`	`string`
`done`	`boolean`	required

POST`/v2/questions/{id}/cancel`

Stop a live question and refund the answers not given.

API key or OAuth token with questions:write.

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`
`refundCredits`	`integer`	required

POST`/v2/questions/{id}/rating`

Say how useful the answers were, from 1 to 5.

API key or OAuth token with questions:write.

Once the question has at least one answer (409 nothing_to_rate before). Sending it again replaces the earlier rating.

Request body (JSON)
Field	Type	Notes
`usefulness`	`integer`	required 1–5

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

POST`/v2/questions/{id}/share`

Turn the public results page on or off.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`public`	`boolean`	required

Response (JSON)
Field	Type	Notes
`publicCode`	`string \| null`	required
`url`	`string \| null`	required

GET`/v2/questions/{id}/export.csv`

Every answer as CSV: option or text, reason, translations, tier, attestation reference, time, and taps for a click test.

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`option`	`integer`	0–8
`tier`	`integer`	1–3
`country`	`string`	up to 2 characters, at least 2 characters
`age_band`	`string`
`q`	`string`	up to 100 characters

GET`/v2/questions/{id}/export.jsonl`

Every answer as JSON lines (application/x-ndjson), for scripts and model training: the CSV's fields plus `choice` (option indexes) and `cohortHash`.

API key or OAuth token with questions:read.

One JSON object per answer, each on its own line and newline-terminated; an empty body when no answers match. Takes the same filters as export.csv. Nothing identifies a head.

Query parameters
Field	Type	Notes
`option`	`integer`	0–8
`tier`	`integer`	1–3
`country`	`string`	up to 2 characters, at least 2 characters
`age_band`	`string`
`q`	`string`	up to 100 characters

GET`/v2/questions/{id}/link/qr.svg`

Your audience: the share link's QR code as SVG (quiet zone of four modules, error correction M).

API key or OAuth token with questions:read.

GET`/v2/questions/{id}/link/qr.png`

Your audience: the share link's QR code as a 1024-pixel PNG.

API key or OAuth token with questions:read.

GET`/v2/questions/{id}/export.pdf`

A one-page PDF report: the question, the chart, what it means and the answers (pinned first).

API key or OAuth token with questions:read.

GET`/v2/questions/{id}/export.png`

The chart as a PNG to share: size=square (1080×1080, default), wide (1200×675) or story (1080×1920).

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`size`	`"square" \| "wide" \| "story"`

POST`/v2/questions/{id}/exports`

A PDF report or PNG chart as a signed link that works for an hour without signing in.

API key or OAuth token with questions:read.

Request body (JSON)
Field	Type	Notes
`format`	`"pdf" \| "png"`	required
`size`	`"square" \| "wide" \| "story"`

Response (JSON)
Field	Type	Notes
`export`	`object`	required
`export.format`	`"pdf" \| "png"`	required
`export.size`	`"square" \| "wide" \| "story" \| null`	required
`export.url`	`string`	required
`export.filename`	`string`	required
`export.expiresAt`	`string`	required

POST`/v2/questions/{id}/heads`

Reopen a finished question for n more heads, same wording and targeting; answers merge. dryRun quotes only.

API key or OAuth token with questions:write. Idempotency-Key header required.

Needs an Idempotency-Key unless dryRun. The question must be complete or underfilled.

Request body (JSON)
Field	Type	Notes
`n`	`integer`	required 1–5000
`dryRun`	`boolean`

Response (JSON)
Field	Type	Notes
`question`	`object`
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`
`quote`	`object`	required
`quote.n`	`integer`	required
`quote.creditsPerAnswer`	`integer`	required
`quote.creditsTotal`	`integer`	required
`quote.etaMinutes`	`integer`	required
`quote.newTarget`	`integer`	required
`quote.line`	`string`	required
`creditsReserved`	`integer`

POST`/v2/questions/{id}/answers/{ref}/flag`

Flag one answer, named by its attestation reference, for review. Upheld: removed and refunded.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`reason`	`"off_topic" \| "low_effort" \| "abusive" \| "automated"`	required
`note`	`string`	up to 500 characters

Response (JSON)
Field	Type	Notes
`flag`	`object`	required
`flag.reason`	`"off_topic" \| "low_effort" \| "abusive" \| "automated"`	required
`flag.status`	`"open" \| "upheld" \| "dismissed"`	required
`flag.refundCredits`	`integer`	required
`flag.createdAt`	`string`	required
`flag.decidedAt`	`string \| null`	required
`flag.id`	`string`	required
`flag.attestationRef`	`string`	required

POST`/v2/questions/{id}/answers/{ref}/pin`

Pin an answer to the top of the results and the PDF report, or unpin it.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`pinned`	`boolean`	required

Response (JSON)
Field	Type	Notes
`pinned`	`boolean`	required

GET`/v2/questions/{id}/share-links`

Private share links for a question (tokens are never shown again).

API key or OAuth token with questions:read.

Response (JSON)
Field	Type	Notes
`links`	`object[]`	required
`links[].id`	`string`	required
`links[].url`	`string \| null`	required
`links[].createdAt`	`string`	required
`links[].expiresAt`	`string`	required
`links[].revokedAt`	`string \| null`	required
`links[].views`	`integer`	required
`links[].lastViewedAt`	`string \| null`	required

POST`/v2/questions/{id}/share-links`

A private, unlisted link to the full results with written answers; expires in 1 to 90 days.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`expiresInDays`	`integer`	1–90, default 30

Response (JSON)
Field	Type	Notes
`link`	`object`	required
`link.id`	`string`	required
`link.url`	`string \| null`	required
`link.createdAt`	`string`	required
`link.expiresAt`	`string`	required
`link.revokedAt`	`string \| null`	required
`link.views`	`integer`	required
`link.lastViewedAt`	`string \| null`	required

DELETE`/v2/questions/{id}/share-links/{linkId}`

Revoke a private share link; it stops working at once.

API key or OAuth token with questions:write.

Response (JSON)
Field	Type	Notes
`link`	`object`	required
`link.id`	`string`	required
`link.url`	`string \| null`	required
`link.createdAt`	`string`	required
`link.expiresAt`	`string`	required
`link.revokedAt`	`string \| null`	required
`link.views`	`integer`	required
`link.lastViewedAt`	`string \| null`	required

GET`/v1/public/link/{code}`

Your audience: what the answer page shows for a link. No sign-in; never cached; noindex.

No authentication.

The page for /y/{code}. Returns the question, the "Shown as" name and the link's state (live, scheduled, closed, full or paused) and nothing about the owner, the price or the counts.

Response (JSON)
Field	Type	Notes
`kind`	`"question" \| "set"`	required
`state`	`"live" \| "scheduled" \| "closed" \| "full" \| "paused"`	required
`shownAs`	`string \| null`	required
`language`	`string`	required
`question`	`object \| null`	required
`question.type`	`string`	required
`question.text`	`string`	required
`question.context`	`string \| null`	required
`question.language`	`string`	required
`question.options`	`object[]`	required
`question.options[].label`	`string`	required
`question.options[].imageUrl`	`string \| null`	required
`question.options[].imageUrls`	`string[]`
`question.neither`	`boolean`	required
`question.scaleLabels`	`object \| null`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.stimulus`	`object \| null`	required
`question.stimulus.imageUrl`	`string \| null`	required
`question.stimulus.audioUrl`	`string \| null`	required
`question.stimulus.text`	`string \| null`	required
`question.maxTaps`	`integer \| null`	required
`question.pair`	`array \| null`	required
`opensAt`	`string \| null`	required
`showResult`	`boolean`	required
`resultCode`	`string \| null`	required
`set`	`object \| null`	required
`set.count`	`integer`	required ≥ 1
`set.questions`	`object[]`	required
`set.questions[].position`	`integer`	required ≥ 1
`set.questions[].state`	`"live" \| "scheduled" \| "closed" \| "full" \| "paused"`	required
`set.questions[].question`	`object \| null`	required

POST`/v1/public/link/{code}/answers`

Your audience: one answer from the browser.

No authentication.

Needs a Turnstile token in production and a fresh UUID nonce per page load: a retry with the same nonce returns the first outcome. Fails with human_check_failed (403) or rate_limited (429). An answer after the link closed or filled returns accepted: false with the state to show.

Request body (JSON)
Field	Type	Notes
`answer`	`object`	required
`answer.optionIndex`	`integer`	0–8
`answer.optionIndexes`	`integer[]`	up to 9 items
`answer.ranking`	`integer[]`	up to 9 items
`answer.ratings`	`integer[]`	up to 8 items
`answer.pair`	`array`	up to 2 items
`answer.taps`	`object[]`	up to 5 items
`answer.taps[].x`	`number`	required 0–1
`answer.taps[].y`	`number`	required 0–1
`dwellMs`	`integer`	0–86400000, default 0
`interrupted`	`boolean`	default false
`nonce`	`string (uuid)`	required pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$
`turnstileToken`	`string`	up to 2048 characters
`locale`	`string`	up to 12 characters
`position`	`integer`	1–10
`visit`	`string`	up to 40 characters

Response (JSON)
Field	Type	Notes
`accepted`	`boolean`	required
`state`	`"live" \| "scheduled" \| "closed" \| "full" \| "paused"`	required
`showResult`	`boolean`	required
`resultCode`	`string \| null`	required
`visit`	`string \| null`	required
`remaining`	`integer[]`	required
`answered`	`object[]`	required
`answered[].position`	`integer`	required
`answered[].resultCode`	`string \| null`	required

POST`/v1/public/link/{code}/started`

Your audience: an option was chosen on the answer page.

No authentication. Idempotency-Key header required.

Counted once per page load (the nonce), so the link's started figure means people, not loads.

Request body (JSON)
Field	Type	Notes
`nonce`	`string (uuid)`	required pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

GET`/v1/public/shared/{token}`

The results behind a private share link. No sign-in; never cached; noindex.

No authentication.

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`
`result`	`object`	required
`result.questionId`	`string`	required
`result.status`	`"in_progress" \| "complete" \| "underfilled" \| "canceled"`	required
`result.nRequested`	`integer`	required
`result.nAccepted`	`integer`	required
`result.distribution`	`object[]`	required
`result.distribution[].option`	`string`	required
`result.distribution[].count`	`integer`	required
`result.distribution[].share`	`number`	required
`result.distribution[].averageRank`	`number`
`result.distribution[].mean`	`number`
`result.distribution[].ratings`	`integer[]`	up to 5 items
`result.distribution[].appearances`	`integer`
`result.distribution[].strength`	`number`
`result.distribution[].rank`	`integer`
`result.distribution[].low`	`number`
`result.distribution[].high`	`number`
`result.mean`	`number \| null`	required
`result.scaleLabels`	`object \| null`
`result.scaleLabels.low`	`string`	required up to 24 characters
`result.scaleLabels.high`	`string`	required up to 24 characters
`result.summary`	`object`	required
`result.summary.winner`	`string \| null`	required
`result.summary.margin`	`number \| null`	required
`result.summary.confidence`	`"low" \| "medium" \| "high" \| null`	required
`result.summary.note`	`string`	required
`result.summary.suggestedFollowUp`	`string \| null`	required
`result.tier`	`integer \| null`	required
`result.language`	`string`	required
`result.verificationLine`	`string`	required
`result.provenance`	`object`
`result.provenance.answeredBy`	`"heads" \| "private"`	required
`result.provenance.access`	`"app" \| "shared_link"`	required
`result.provenance.verified`	`boolean`	required
`result.provenance.answers`	`integer`	required
`result.provenance.issued`	`integer \| null`	required
`result.provenance.denominator`	`"known" \| "unknown"`	required
`result.medianSeconds`	`number \| null`	required
`result.creditsSpent`	`integer`	required
`result.answers`	`object[]`	required
`result.answers[].option`	`string \| null`	required
`result.answers[].text`	`string \| null`	required
`result.answers[].translatedText`	`string \| null`
`result.answers[].reason`	`string \| null`
`result.answers[].translatedReason`	`string \| null`
`result.answers[].tier`	`integer \| null`	required
`result.answers[].attestationRef`	`string \| null`	required
`result.answers[].answeredAt`	`string`	required
`result.answers[].pinned`	`boolean`
`result.answers[].flag`	`object \| null`
`result.answers[].taps`	`object[]`
`result.answers[].choice`	`object`
`result.breakdown`	`object[]`
`result.breakdown[].tagId`	`string`	required
`result.breakdown[].label`	`string`	required
`result.breakdown[].n`	`integer`	required
`result.breakdown[].distribution`	`object[]`	required
`result.refundCredits`	`integer`	required
`result.breakdowns`	`object[]`
`result.breakdowns[].dimension`	`"country" \| "tier" \| "age_band" \| "gender" \| "tag" \| "language"`	required
`result.breakdowns[].segments`	`object[]`	required
`result.clicks`	`object`
`result.clicks.imageUrl`	`string \| null`	required
`result.clicks.taps`	`integer`	required
`result.clicks.points`	`object[]`	required
`result.clicks.grid`	`integer[]`	required
`result.clicks.gridSize`	`integer`	required
`result.clicks.hotspots`	`object[]`	required
`result.clicks.heatmapUrl`	`string \| null`	required
`result.sentiment`	`object`
`result.sentiment.positive`	`number`	required
`result.sentiment.neutral`	`number`	required
`result.sentiment.negative`	`number`	required
`result.translationLanguage`	`string \| null`
`result.insights`	`object \| null`
`result.insights.questionId`	`string`	required
`result.insights.language`	`string`	required
`result.insights.sourceLanguage`	`string`	required
`result.insights.takeaway`	`string`	required
`result.insights.themes`	`object[]`	required up to 8 items
`result.insights.findings`	`object[]`	up to 5 items
`result.insights.byOption`	`object[]`	up to 9 items
`result.insights.followUp`	`object \| null`
`result.insights.sentiment`	`object`	required
`result.insights.basedOn`	`integer`	required
`result.insights.answersAtTime`	`integer`	required
`result.insights.original`	`object \| null`	required
`result.insights.kind`	`"interim" \| "final"`	required
`result.insights.generatedAt`	`string`	required
`result.insights.refreshAfter`	`string \| null`	required
`result.insights.engine`	`string`	required
`result.filter`	`object`
`result.filter.option`	`integer`	0–8
`result.filter.tier`	`integer`	1–3
`result.filter.country`	`object`
`result.filter.ageBand`	`string`	pattern ^[0-9]{2}(-[0-9]{2}\|\+)$
`result.filter.gender`	`"woman" \| "man" \| "non_binary"`
`result.filter.q`	`string`	up to 100 characters
`result.nUnfiltered`	`integer`
`result.suppressed`	`boolean`
`result.facets`	`object`
`result.facets.tiers`	`object[]`	required
`result.facets.countries`	`object[]`	required
`result.facets.ageBands`	`object[]`	required
`result.facets.genders`	`object[]`
`result.verdict`	`object`
`result.verdict.verdict`	`"go" \| "no_go" \| "unclear"`	required
`result.verdict.reason`	`"too_few" \| "too_close" \| null`	required
`result.verdict.yesShare`	`number`	required
`result.verdict.low`	`number`	required
`result.verdict.high`	`number`	required
`result.verdict.goAbove`	`number`	required
`result.verdict.minAnswers`	`integer`	required
`result.verdict.n`	`integer`	required
`result.headToHead`	`object`
`result.headToHead.options`	`string[]`	required
`result.headToHead.share`	`number \| null[][]`	required
`result.headToHead.n`	`integer[][]`	required
`result.cohortHash`	`string`
`expiresAt`	`string`	required

GET`/v2/questions/{id}/heatmap.png`

A click test's heatmap as a transparent PNG to lay over the image. Add ?aspect=width/height to match it.

API key or OAuth token with questions:read.

POST`/v2/questions/{id}/dispute`

Dispute a result within 7 days of it closing.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`reason`	`string`	required up to 2000 characters, at least 10 characters

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

GET`/v1/public/results/{code}`

A result its requester made public.

No authentication.

Response (JSON)
Field	Type	Notes
`question`	`object`	required
`question.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`question.text`	`string`	required up to 600 characters
`question.context`	`string`	up to 120 characters
`question.language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`question.options`	`object[]`	required up to 8 items, default []
`question.options[].label`	`string`	required up to 40 characters
`question.options[].imageUrl`	`string (URL)`
`question.options[].imageUrls`	`string (URL)[]`	up to 4 items
`question.scaleLabels`	`object`
`question.scaleLabels.low`	`string`	required up to 24 characters
`question.scaleLabels.high`	`string`	required up to 24 characters
`question.neither`	`boolean`	required default false
`question.stimulus`	`object`
`question.stimulus.imageUrl`	`string (URL)`
`question.stimulus.audioUrl`	`string (URL)`
`question.stimulus.text`	`string`	up to 120 characters
`question.stimulus.exposureMs`	`integer`	2000–10000
`question.n`	`integer`	required 10–5000, default 50
`question.tier`	`1 \| 2 \| 3`	required default 1
`question.rush`	`boolean`	required default false
`question.targeting`	`object`
`question.targeting.countries`	`string[]`	required up to 50 items, default []
`question.targeting.tags`	`string[]`	required up to 20 items, default []
`question.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`question.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`question.targeting.verifiedAge`	`boolean`
`question.clickTest`	`object`
`question.clickTest.maxTaps`	`integer`	required 1–5, default 1
`question.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`question.publicResults`	`boolean`	required default false
`question.reason`	`"off" \| "optional" \| "required"`	required default "off"
`question.goRule`	`object`
`question.goRule.goAbove`	`number`	required 0.5–0.95
`question.goRule.minAnswers`	`integer`	required 5–5000
`question.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`question.interestAudienceId`	`string`	up to 40 characters
`question.minGrade`	`1 \| 2 \| 3`
`question.interestPrice`	`object`
`question.interestPrice.perAnswerPence`	`integer`	required 1–10000
`question.interestPrice.headShareBps`	`integer`	required 0–10000
`question.answeredBy`	`"heads" \| "private"`	required default "heads"
`question.openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`question.shownAs`	`string`	up to 40 characters
`question.id`	`string`	required
`question.status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`question.source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`question.answered`	`integer`	required
`question.creditsPerAnswer`	`integer`	required
`question.creditsReserved`	`integer`	required
`question.creditsSpent`	`integer`	required
`question.etaMinutes`	`integer`	required
`question.leaderLine`	`string \| null`	required
`question.refusedCategory`	`string \| null`	required
`question.publicCode`	`string \| null`	required
`question.createdAt`	`string`	required
`question.liveAt`	`string \| null`	required
`question.closedAt`	`string \| null`	required
`question.teamId`	`string \| null`
`question.askedBy`	`object \| null`
`question.askedBy.id`	`string`	required
`question.askedBy.name`	`string \| null`	required
`question.projectId`	`string \| null`
`question.labels`	`string[]`
`question.archived`	`boolean`
`question.bookmarked`	`boolean`
`question.externalRef`	`string \| null`
`question.link`	`object \| null`
`question.link.url`	`string`	required
`question.link.qrSvgUrl`	`string`	required
`question.link.qrPngUrl`	`string`	required
`question.link.closesAt`	`string \| null`	required
`question.link.views`	`integer`	required
`question.link.started`	`integer`	required
`question.setId`	`string \| null`
`question.setPosition`	`integer \| null`
`question.setCount`	`integer \| null`
`result`	`object`	required
`result.questionId`	`string`	required
`result.status`	`"in_progress" \| "complete" \| "underfilled" \| "canceled"`	required
`result.nRequested`	`integer`	required
`result.nAccepted`	`integer`	required
`result.distribution`	`object[]`	required
`result.distribution[].option`	`string`	required
`result.distribution[].count`	`integer`	required
`result.distribution[].share`	`number`	required
`result.distribution[].averageRank`	`number`
`result.distribution[].mean`	`number`
`result.distribution[].ratings`	`integer[]`	up to 5 items
`result.distribution[].appearances`	`integer`
`result.distribution[].strength`	`number`
`result.distribution[].rank`	`integer`
`result.distribution[].low`	`number`
`result.distribution[].high`	`number`
`result.mean`	`number \| null`	required
`result.scaleLabels`	`object \| null`
`result.scaleLabels.low`	`string`	required up to 24 characters
`result.scaleLabels.high`	`string`	required up to 24 characters
`result.summary`	`object`	required
`result.summary.winner`	`string \| null`	required
`result.summary.margin`	`number \| null`	required
`result.summary.confidence`	`"low" \| "medium" \| "high" \| null`	required
`result.summary.note`	`string`	required
`result.summary.suggestedFollowUp`	`string \| null`	required
`result.tier`	`integer \| null`	required
`result.language`	`string`	required
`result.verificationLine`	`string`	required
`result.provenance`	`object`
`result.provenance.answeredBy`	`"heads" \| "private"`	required
`result.provenance.access`	`"app" \| "shared_link"`	required
`result.provenance.verified`	`boolean`	required
`result.provenance.answers`	`integer`	required
`result.provenance.issued`	`integer \| null`	required
`result.provenance.denominator`	`"known" \| "unknown"`	required
`result.medianSeconds`	`number \| null`	required
`result.creditsSpent`	`integer`	required
`result.answers`	`object[]`	required
`result.answers[].option`	`string \| null`	required
`result.answers[].text`	`string \| null`	required
`result.answers[].translatedText`	`string \| null`
`result.answers[].reason`	`string \| null`
`result.answers[].translatedReason`	`string \| null`
`result.answers[].tier`	`integer \| null`	required
`result.answers[].attestationRef`	`string \| null`	required
`result.answers[].answeredAt`	`string`	required
`result.answers[].pinned`	`boolean`
`result.answers[].flag`	`object \| null`
`result.answers[].taps`	`object[]`
`result.answers[].choice`	`object`
`result.breakdown`	`object[]`
`result.breakdown[].tagId`	`string`	required
`result.breakdown[].label`	`string`	required
`result.breakdown[].n`	`integer`	required
`result.breakdown[].distribution`	`object[]`	required
`result.refundCredits`	`integer`	required
`result.breakdowns`	`object[]`
`result.breakdowns[].dimension`	`"country" \| "tier" \| "age_band" \| "gender" \| "tag" \| "language"`	required
`result.breakdowns[].segments`	`object[]`	required
`result.clicks`	`object`
`result.clicks.imageUrl`	`string \| null`	required
`result.clicks.taps`	`integer`	required
`result.clicks.points`	`object[]`	required
`result.clicks.grid`	`integer[]`	required
`result.clicks.gridSize`	`integer`	required
`result.clicks.hotspots`	`object[]`	required
`result.clicks.heatmapUrl`	`string \| null`	required
`result.sentiment`	`object`
`result.sentiment.positive`	`number`	required
`result.sentiment.neutral`	`number`	required
`result.sentiment.negative`	`number`	required
`result.translationLanguage`	`string \| null`
`result.insights`	`object \| null`
`result.insights.questionId`	`string`	required
`result.insights.language`	`string`	required
`result.insights.sourceLanguage`	`string`	required
`result.insights.takeaway`	`string`	required
`result.insights.themes`	`object[]`	required up to 8 items
`result.insights.findings`	`object[]`	up to 5 items
`result.insights.byOption`	`object[]`	up to 9 items
`result.insights.followUp`	`object \| null`
`result.insights.sentiment`	`object`	required
`result.insights.basedOn`	`integer`	required
`result.insights.answersAtTime`	`integer`	required
`result.insights.original`	`object \| null`	required
`result.insights.kind`	`"interim" \| "final"`	required
`result.insights.generatedAt`	`string`	required
`result.insights.refreshAfter`	`string \| null`	required
`result.insights.engine`	`string`	required
`result.filter`	`object`
`result.filter.option`	`integer`	0–8
`result.filter.tier`	`integer`	1–3
`result.filter.country`	`object`
`result.filter.ageBand`	`string`	pattern ^[0-9]{2}(-[0-9]{2}\|\+)$
`result.filter.gender`	`"woman" \| "man" \| "non_binary"`
`result.filter.q`	`string`	up to 100 characters
`result.nUnfiltered`	`integer`
`result.suppressed`	`boolean`
`result.facets`	`object`
`result.facets.tiers`	`object[]`	required
`result.facets.countries`	`object[]`	required
`result.facets.ageBands`	`object[]`	required
`result.facets.genders`	`object[]`
`result.verdict`	`object`
`result.verdict.verdict`	`"go" \| "no_go" \| "unclear"`	required
`result.verdict.reason`	`"too_few" \| "too_close" \| null`	required
`result.verdict.yesShare`	`number`	required
`result.verdict.low`	`number`	required
`result.verdict.high`	`number`	required
`result.verdict.goAbove`	`number`	required
`result.verdict.minAnswers`	`integer`	required
`result.verdict.n`	`integer`	required
`result.headToHead`	`object`
`result.headToHead.options`	`string[]`	required
`result.headToHead.share`	`number \| null[][]`	required
`result.headToHead.n`	`integer[][]`	required
`result.cohortHash`	`string`

Sets

Your audience: two to ten questions behind one link, answered in order. Each question in a set is an ordinary question with its own result and exports; the set owns the link and the closing date.

POST`/v2/sets`

Your audience: publish a set of two to ten questions behind one link.

API key or OAuth token with questions:write. Idempotency-Key header required.

Requires an Idempotency-Key header (a UUID); the same key returns the same set. Every question is reserved at 5 credits an answer times maxAnswers. Fails with insufficient_credits, private_link_limit, private_declaration_required or content_refused without spending anything.

Request body (JSON)
Field	Type	Notes
`questions`	`object[]`	required up to 10 items
`questions[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`questions[].text`	`string`	required up to 600 characters
`questions[].context`	`string`	up to 120 characters
`questions[].language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`questions[].options`	`object[]`	up to 8 items, default []
`questions[].options[].label`	`string`	required up to 40 characters
`questions[].options[].imageUrl`	`string (URL)`
`questions[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`questions[].scaleLabels`	`object`
`questions[].scaleLabels.low`	`string`	required up to 24 characters
`questions[].scaleLabels.high`	`string`	required up to 24 characters
`questions[].neither`	`boolean`	default false
`questions[].stimulus`	`object`
`questions[].stimulus.imageUrl`	`string (URL)`
`questions[].stimulus.audioUrl`	`string (URL)`
`questions[].stimulus.text`	`string`	up to 120 characters
`questions[].stimulus.exposureMs`	`integer`	2000–10000
`questions[].clickTest`	`object`
`questions[].clickTest.maxTaps`	`integer`	1–5, default 1
`questions[].goRule`	`object`
`questions[].goRule.goAbove`	`number`	required 0.5–0.95
`questions[].goRule.minAnswers`	`integer`	required 5–5000
`maxAnswers`	`integer`	10–5000, default 100
`openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`shownAs`	`string`	up to 40 characters
`publicResults`	`boolean`	default false
`projectId`	`string \| null`
`labels`	`string[]`	up to 10 items
`privateDeclaration`	`object`
`privateDeclaration.version`	`integer`	required ≥ 1

Response (JSON)
Field	Type	Notes
`set`	`object`	required
`set.id`	`string`	required
`set.status`	`"open" \| "closed"`	required
`set.shownAs`	`string \| null`	required
`set.maxAnswers`	`integer`	required
`set.openForDays`	`1 \| 7 \| 14 \| 30`	required
`set.publicResults`	`boolean`	required
`set.expiresAt`	`string`	required
`set.questionIds`	`string[]`	required
`set.answered`	`integer`	required
`set.creditsReserved`	`integer`	required
`set.creditsSpent`	`integer`	required
`set.link`	`object \| null`	required
`set.link.url`	`string`	required
`set.link.qrSvgUrl`	`string`	required
`set.link.qrPngUrl`	`string`	required
`set.link.closesAt`	`string \| null`	required
`set.link.views`	`integer`	required
`set.link.started`	`integer`	required
`set.teamId`	`string \| null`	required
`set.createdAt`	`string`	required
`set.closedAt`	`string \| null`	required
`questions`	`object[]`	required
`questions[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`questions[].text`	`string`	required up to 600 characters
`questions[].context`	`string`	up to 120 characters
`questions[].language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`questions[].options`	`object[]`	required up to 8 items, default []
`questions[].options[].label`	`string`	required up to 40 characters
`questions[].options[].imageUrl`	`string (URL)`
`questions[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`questions[].scaleLabels`	`object`
`questions[].scaleLabels.low`	`string`	required up to 24 characters
`questions[].scaleLabels.high`	`string`	required up to 24 characters
`questions[].neither`	`boolean`	required default false
`questions[].stimulus`	`object`
`questions[].stimulus.imageUrl`	`string (URL)`
`questions[].stimulus.audioUrl`	`string (URL)`
`questions[].stimulus.text`	`string`	up to 120 characters
`questions[].stimulus.exposureMs`	`integer`	2000–10000
`questions[].n`	`integer`	required 10–5000, default 50
`questions[].tier`	`1 \| 2 \| 3`	required default 1
`questions[].rush`	`boolean`	required default false
`questions[].targeting`	`object`
`questions[].targeting.countries`	`string[]`	required up to 50 items, default []
`questions[].targeting.tags`	`string[]`	required up to 20 items, default []
`questions[].targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`questions[].targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`questions[].targeting.verifiedAge`	`boolean`
`questions[].clickTest`	`object`
`questions[].clickTest.maxTaps`	`integer`	required 1–5, default 1
`questions[].scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`questions[].publicResults`	`boolean`	required default false
`questions[].reason`	`"off" \| "optional" \| "required"`	required default "off"
`questions[].goRule`	`object`
`questions[].goRule.goAbove`	`number`	required 0.5–0.95
`questions[].goRule.minAnswers`	`integer`	required 5–5000
`questions[].contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`questions[].interestAudienceId`	`string`	up to 40 characters
`questions[].minGrade`	`1 \| 2 \| 3`
`questions[].interestPrice`	`object`
`questions[].interestPrice.perAnswerPence`	`integer`	required 1–10000
`questions[].interestPrice.headShareBps`	`integer`	required 0–10000
`questions[].answeredBy`	`"heads" \| "private"`	required default "heads"
`questions[].openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`questions[].shownAs`	`string`	up to 40 characters
`questions[].id`	`string`	required
`questions[].status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`questions[].source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`questions[].answered`	`integer`	required
`questions[].creditsPerAnswer`	`integer`	required
`questions[].creditsReserved`	`integer`	required
`questions[].creditsSpent`	`integer`	required
`questions[].etaMinutes`	`integer`	required
`questions[].leaderLine`	`string \| null`	required
`questions[].refusedCategory`	`string \| null`	required
`questions[].publicCode`	`string \| null`	required
`questions[].createdAt`	`string`	required
`questions[].liveAt`	`string \| null`	required
`questions[].closedAt`	`string \| null`	required
`questions[].teamId`	`string \| null`
`questions[].askedBy`	`object \| null`
`questions[].askedBy.id`	`string`	required
`questions[].askedBy.name`	`string \| null`	required
`questions[].projectId`	`string \| null`
`questions[].labels`	`string[]`
`questions[].archived`	`boolean`
`questions[].bookmarked`	`boolean`
`questions[].externalRef`	`string \| null`
`questions[].link`	`object \| null`
`questions[].link.url`	`string`	required
`questions[].link.qrSvgUrl`	`string`	required
`questions[].link.qrPngUrl`	`string`	required
`questions[].link.closesAt`	`string \| null`	required
`questions[].link.views`	`integer`	required
`questions[].link.started`	`integer`	required
`questions[].setId`	`string \| null`
`questions[].setPosition`	`integer \| null`
`questions[].setCount`	`integer \| null`

GET`/v2/sets`

Your sets, newest first.

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`status`	`"open" \| "closed"`
`limit`	`integer`	1–100
`cursor`	`string`

Response (JSON)
Field	Type	Notes
`sets`	`object[]`	required
`sets[].id`	`string`	required
`sets[].status`	`"open" \| "closed"`	required
`sets[].shownAs`	`string \| null`	required
`sets[].maxAnswers`	`integer`	required
`sets[].openForDays`	`1 \| 7 \| 14 \| 30`	required
`sets[].publicResults`	`boolean`	required
`sets[].expiresAt`	`string`	required
`sets[].questionIds`	`string[]`	required
`sets[].answered`	`integer`	required
`sets[].creditsReserved`	`integer`	required
`sets[].creditsSpent`	`integer`	required
`sets[].link`	`object \| null`	required
`sets[].link.url`	`string`	required
`sets[].link.qrSvgUrl`	`string`	required
`sets[].link.qrPngUrl`	`string`	required
`sets[].link.closesAt`	`string \| null`	required
`sets[].link.views`	`integer`	required
`sets[].link.started`	`integer`	required
`sets[].teamId`	`string \| null`	required
`sets[].createdAt`	`string`	required
`sets[].closedAt`	`string \| null`	required
`nextCursor`	`string \| null`	required

GET`/v2/sets/{id}`

A set and its questions in order.

API key or OAuth token with questions:read.

Response (JSON)
Field	Type	Notes
`set`	`object`	required
`set.id`	`string`	required
`set.status`	`"open" \| "closed"`	required
`set.shownAs`	`string \| null`	required
`set.maxAnswers`	`integer`	required
`set.openForDays`	`1 \| 7 \| 14 \| 30`	required
`set.publicResults`	`boolean`	required
`set.expiresAt`	`string`	required
`set.questionIds`	`string[]`	required
`set.answered`	`integer`	required
`set.creditsReserved`	`integer`	required
`set.creditsSpent`	`integer`	required
`set.link`	`object \| null`	required
`set.link.url`	`string`	required
`set.link.qrSvgUrl`	`string`	required
`set.link.qrPngUrl`	`string`	required
`set.link.closesAt`	`string \| null`	required
`set.link.views`	`integer`	required
`set.link.started`	`integer`	required
`set.teamId`	`string \| null`	required
`set.createdAt`	`string`	required
`set.closedAt`	`string \| null`	required
`questions`	`object[]`	required
`questions[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`questions[].text`	`string`	required up to 600 characters
`questions[].context`	`string`	up to 120 characters
`questions[].language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`questions[].options`	`object[]`	required up to 8 items, default []
`questions[].options[].label`	`string`	required up to 40 characters
`questions[].options[].imageUrl`	`string (URL)`
`questions[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`questions[].scaleLabels`	`object`
`questions[].scaleLabels.low`	`string`	required up to 24 characters
`questions[].scaleLabels.high`	`string`	required up to 24 characters
`questions[].neither`	`boolean`	required default false
`questions[].stimulus`	`object`
`questions[].stimulus.imageUrl`	`string (URL)`
`questions[].stimulus.audioUrl`	`string (URL)`
`questions[].stimulus.text`	`string`	up to 120 characters
`questions[].stimulus.exposureMs`	`integer`	2000–10000
`questions[].n`	`integer`	required 10–5000, default 50
`questions[].tier`	`1 \| 2 \| 3`	required default 1
`questions[].rush`	`boolean`	required default false
`questions[].targeting`	`object`
`questions[].targeting.countries`	`string[]`	required up to 50 items, default []
`questions[].targeting.tags`	`string[]`	required up to 20 items, default []
`questions[].targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`questions[].targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`questions[].targeting.verifiedAge`	`boolean`
`questions[].clickTest`	`object`
`questions[].clickTest.maxTaps`	`integer`	required 1–5, default 1
`questions[].scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`questions[].publicResults`	`boolean`	required default false
`questions[].reason`	`"off" \| "optional" \| "required"`	required default "off"
`questions[].goRule`	`object`
`questions[].goRule.goAbove`	`number`	required 0.5–0.95
`questions[].goRule.minAnswers`	`integer`	required 5–5000
`questions[].contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`questions[].interestAudienceId`	`string`	up to 40 characters
`questions[].minGrade`	`1 \| 2 \| 3`
`questions[].interestPrice`	`object`
`questions[].interestPrice.perAnswerPence`	`integer`	required 1–10000
`questions[].interestPrice.headShareBps`	`integer`	required 0–10000
`questions[].answeredBy`	`"heads" \| "private"`	required default "heads"
`questions[].openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`questions[].shownAs`	`string`	up to 40 characters
`questions[].id`	`string`	required
`questions[].status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`questions[].source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`questions[].answered`	`integer`	required
`questions[].creditsPerAnswer`	`integer`	required
`questions[].creditsReserved`	`integer`	required
`questions[].creditsSpent`	`integer`	required
`questions[].etaMinutes`	`integer`	required
`questions[].leaderLine`	`string \| null`	required
`questions[].refusedCategory`	`string \| null`	required
`questions[].publicCode`	`string \| null`	required
`questions[].createdAt`	`string`	required
`questions[].liveAt`	`string \| null`	required
`questions[].closedAt`	`string \| null`	required
`questions[].teamId`	`string \| null`
`questions[].askedBy`	`object \| null`
`questions[].askedBy.id`	`string`	required
`questions[].askedBy.name`	`string \| null`	required
`questions[].projectId`	`string \| null`
`questions[].labels`	`string[]`
`questions[].archived`	`boolean`
`questions[].bookmarked`	`boolean`
`questions[].externalRef`	`string \| null`
`questions[].link`	`object \| null`
`questions[].link.url`	`string`	required
`questions[].link.qrSvgUrl`	`string`	required
`questions[].link.qrPngUrl`	`string`	required
`questions[].link.closesAt`	`string \| null`	required
`questions[].link.views`	`integer`	required
`questions[].link.started`	`integer`	required
`questions[].setId`	`string \| null`
`questions[].setPosition`	`integer \| null`
`questions[].setCount`	`integer \| null`

POST`/v2/sets/{id}/close`

Close the set now: every open question closes with the answers it has and the unused reserve comes back.

API key or OAuth token with questions:write.

Response (JSON)
Field	Type	Notes
`set`	`object`	required
`set.id`	`string`	required
`set.status`	`"open" \| "closed"`	required
`set.shownAs`	`string \| null`	required
`set.maxAnswers`	`integer`	required
`set.openForDays`	`1 \| 7 \| 14 \| 30`	required
`set.publicResults`	`boolean`	required
`set.expiresAt`	`string`	required
`set.questionIds`	`string[]`	required
`set.answered`	`integer`	required
`set.creditsReserved`	`integer`	required
`set.creditsSpent`	`integer`	required
`set.link`	`object \| null`	required
`set.link.url`	`string`	required
`set.link.qrSvgUrl`	`string`	required
`set.link.qrPngUrl`	`string`	required
`set.link.closesAt`	`string \| null`	required
`set.link.views`	`integer`	required
`set.link.started`	`integer`	required
`set.teamId`	`string \| null`	required
`set.createdAt`	`string`	required
`set.closedAt`	`string \| null`	required
`questions`	`object[]`	required
`questions[].type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`questions[].text`	`string`	required up to 600 characters
`questions[].context`	`string`	up to 120 characters
`questions[].language`	`string`	required pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`questions[].options`	`object[]`	required up to 8 items, default []
`questions[].options[].label`	`string`	required up to 40 characters
`questions[].options[].imageUrl`	`string (URL)`
`questions[].options[].imageUrls`	`string (URL)[]`	up to 4 items
`questions[].scaleLabels`	`object`
`questions[].scaleLabels.low`	`string`	required up to 24 characters
`questions[].scaleLabels.high`	`string`	required up to 24 characters
`questions[].neither`	`boolean`	required default false
`questions[].stimulus`	`object`
`questions[].stimulus.imageUrl`	`string (URL)`
`questions[].stimulus.audioUrl`	`string (URL)`
`questions[].stimulus.text`	`string`	up to 120 characters
`questions[].stimulus.exposureMs`	`integer`	2000–10000
`questions[].n`	`integer`	required 10–5000, default 50
`questions[].tier`	`1 \| 2 \| 3`	required default 1
`questions[].rush`	`boolean`	required default false
`questions[].targeting`	`object`
`questions[].targeting.countries`	`string[]`	required up to 50 items, default []
`questions[].targeting.tags`	`string[]`	required up to 20 items, default []
`questions[].targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`questions[].targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`questions[].targeting.verifiedAge`	`boolean`
`questions[].clickTest`	`object`
`questions[].clickTest.maxTaps`	`integer`	required 1–5, default 1
`questions[].scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`questions[].publicResults`	`boolean`	required default false
`questions[].reason`	`"off" \| "optional" \| "required"`	required default "off"
`questions[].goRule`	`object`
`questions[].goRule.goAbove`	`number`	required 0.5–0.95
`questions[].goRule.minAnswers`	`integer`	required 5–5000
`questions[].contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`questions[].interestAudienceId`	`string`	up to 40 characters
`questions[].minGrade`	`1 \| 2 \| 3`
`questions[].interestPrice`	`object`
`questions[].interestPrice.perAnswerPence`	`integer`	required 1–10000
`questions[].interestPrice.headShareBps`	`integer`	required 0–10000
`questions[].answeredBy`	`"heads" \| "private"`	required default "heads"
`questions[].openForDays`	`1 \| 7 \| 14 \| 30`	required default 7
`questions[].shownAs`	`string`	up to 40 characters
`questions[].id`	`string`	required
`questions[].status`	`"draft" \| "scheduled" \| "live" \| "complete" \| "underfilled" \| "canceled" \| "refused" \| "pending_approval" \| "closed"`	required
`questions[].source`	`"app" \| "portal" \| "api" \| "mcp"`	required
`questions[].answered`	`integer`	required
`questions[].creditsPerAnswer`	`integer`	required
`questions[].creditsReserved`	`integer`	required
`questions[].creditsSpent`	`integer`	required
`questions[].etaMinutes`	`integer`	required
`questions[].leaderLine`	`string \| null`	required
`questions[].refusedCategory`	`string \| null`	required
`questions[].publicCode`	`string \| null`	required
`questions[].createdAt`	`string`	required
`questions[].liveAt`	`string \| null`	required
`questions[].closedAt`	`string \| null`	required
`questions[].teamId`	`string \| null`
`questions[].askedBy`	`object \| null`
`questions[].askedBy.id`	`string`	required
`questions[].askedBy.name`	`string \| null`	required
`questions[].projectId`	`string \| null`
`questions[].labels`	`string[]`
`questions[].archived`	`boolean`
`questions[].bookmarked`	`boolean`
`questions[].externalRef`	`string \| null`
`questions[].link`	`object \| null`
`questions[].link.url`	`string`	required
`questions[].link.qrSvgUrl`	`string`	required
`questions[].link.qrPngUrl`	`string`	required
`questions[].link.closesAt`	`string \| null`	required
`questions[].link.views`	`integer`	required
`questions[].link.started`	`integer`	required
`questions[].setId`	`string \| null`
`questions[].setPosition`	`integer \| null`
`questions[].setCount`	`integer \| null`
`refundCredits`	`integer`	required

GET`/v2/sets/{id}/export.csv`

Every accepted answer across the set as CSV: position, question, time, answer, visit (the random id grouping one browser's pass), answered_by and access.

API key or OAuth token with questions:read.

GET`/v2/sets/{id}/export.jsonl`

Every accepted answer across the set as JSON lines: position, question, options, answer, `choice`, each question's `cohortHash` and the visit.

API key or OAuth token with questions:read.

GET`/v2/sets/{id}/link/qr.svg`

The set link's QR code as SVG.

API key or OAuth token with questions:read.

GET`/v2/sets/{id}/link/qr.png`

The set link's QR code as a 1024-pixel PNG.

API key or OAuth token with questions:read.

Drafts and uploads

Save work in progress and upload images before you ask.

GET`/v1/drafts`

Saved drafts.

API key or OAuth token with questions:read.

Response (JSON)
Field	Type	Notes
`drafts`	`object[]`	required
`drafts[].id`	`string`	required
`drafts[].draft`	`object`	required
`drafts[].draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`drafts[].draft.text`	`string`	up to 600 characters
`drafts[].draft.context`	`string`	up to 120 characters
`drafts[].draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`drafts[].draft.options`	`object[]`	up to 8 items, default []
`drafts[].draft.scaleLabels`	`object`
`drafts[].draft.neither`	`boolean`	default false
`drafts[].draft.stimulus`	`object`
`drafts[].draft.n`	`integer`	10–5000, default 50
`drafts[].draft.tier`	`1 \| 2 \| 3`	default 1
`drafts[].draft.rush`	`boolean`	default false
`drafts[].draft.targeting`	`object`
`drafts[].draft.clickTest`	`object`
`drafts[].draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`drafts[].draft.publicResults`	`boolean`	default false
`drafts[].draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`drafts[].draft.goRule`	`object`
`drafts[].draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`drafts[].draft.interestAudienceId`	`string`	up to 40 characters
`drafts[].draft.minGrade`	`1 \| 2 \| 3`
`drafts[].draft.interestPrice`	`object`
`drafts[].draft.answeredBy`	`"heads" \| "private"`	default "heads"
`drafts[].draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`drafts[].draft.shownAs`	`string`	up to 40 characters
`drafts[].updatedAt`	`string`	required
`drafts[].origin`	`"zapier_test" \| null`

POST`/v1/drafts`

Save a draft. PUT /v1/drafts/{id} updates one; DELETE removes it.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`text`	`string`	up to 600 characters
`context`	`string`	up to 120 characters
`language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`options`	`object[]`	up to 8 items, default []
`options[].label`	`string`	required up to 40 characters
`options[].imageUrl`	`string (URL)`
`options[].imageUrls`	`string (URL)[]`	up to 4 items
`scaleLabels`	`object`
`scaleLabels.low`	`string`	required up to 24 characters
`scaleLabels.high`	`string`	required up to 24 characters
`neither`	`boolean`	default false
`stimulus`	`object`
`stimulus.imageUrl`	`string (URL)`
`stimulus.audioUrl`	`string (URL)`
`stimulus.text`	`string`	up to 120 characters
`stimulus.exposureMs`	`integer`	2000–10000
`n`	`integer`	10–5000, default 50
`tier`	`1 \| 2 \| 3`	default 1
`rush`	`boolean`	default false
`targeting`	`object`
`targeting.countries`	`string[]`	up to 50 items, default []
`targeting.tags`	`string[]`	up to 20 items, default []
`targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`targeting.verifiedAge`	`boolean`
`clickTest`	`object`
`clickTest.maxTaps`	`integer`	1–5, default 1
`scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`publicResults`	`boolean`	default false
`reason`	`"off" \| "optional" \| "required"`	default "off"
`goRule`	`object`
`goRule.goAbove`	`number`	required 0.5–0.95
`goRule.minAnswers`	`integer`	required 5–5000
`contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`interestAudienceId`	`string`	up to 40 characters
`minGrade`	`1 \| 2 \| 3`
`interestPrice`	`object`
`interestPrice.perAnswerPence`	`integer`	required 1–10000
`interestPrice.headShareBps`	`integer`	required 0–10000
`answeredBy`	`"heads" \| "private"`	default "heads"
`openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`shownAs`	`string`	up to 40 characters
`origin`	`"zapier_test"`

Response (JSON)
Field	Type	Notes
`id`	`string`	required
`draft`	`object`	required
`draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`draft.text`	`string`	up to 600 characters
`draft.context`	`string`	up to 120 characters
`draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`draft.options`	`object[]`	up to 8 items, default []
`draft.options[].label`	`string`	required up to 40 characters
`draft.options[].imageUrl`	`string (URL)`
`draft.options[].imageUrls`	`string (URL)[]`	up to 4 items
`draft.scaleLabels`	`object`
`draft.scaleLabels.low`	`string`	required up to 24 characters
`draft.scaleLabels.high`	`string`	required up to 24 characters
`draft.neither`	`boolean`	default false
`draft.stimulus`	`object`
`draft.stimulus.imageUrl`	`string (URL)`
`draft.stimulus.audioUrl`	`string (URL)`
`draft.stimulus.text`	`string`	up to 120 characters
`draft.stimulus.exposureMs`	`integer`	2000–10000
`draft.n`	`integer`	10–5000, default 50
`draft.tier`	`1 \| 2 \| 3`	default 1
`draft.rush`	`boolean`	default false
`draft.targeting`	`object`
`draft.targeting.countries`	`string[]`	required up to 50 items, default []
`draft.targeting.tags`	`string[]`	required up to 20 items, default []
`draft.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`draft.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`draft.targeting.verifiedAge`	`boolean`
`draft.clickTest`	`object`
`draft.clickTest.maxTaps`	`integer`	required 1–5, default 1
`draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`draft.publicResults`	`boolean`	default false
`draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`draft.goRule`	`object`
`draft.goRule.goAbove`	`number`	required 0.5–0.95
`draft.goRule.minAnswers`	`integer`	required 5–5000
`draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`draft.interestAudienceId`	`string`	up to 40 characters
`draft.minGrade`	`1 \| 2 \| 3`
`draft.interestPrice`	`object`
`draft.interestPrice.perAnswerPence`	`integer`	required 1–10000
`draft.interestPrice.headShareBps`	`integer`	required 0–10000
`draft.answeredBy`	`"heads" \| "private"`	default "heads"
`draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`draft.shownAs`	`string`	up to 40 characters
`updatedAt`	`string`	required
`origin`	`"zapier_test" \| null`

PUT`/v1/drafts/{id}`

Replace a saved draft.

API key or OAuth token with questions:write.

404 not_found when the draft is not in the account the caller acts for.

Request body (JSON)
Field	Type	Notes
`type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`text`	`string`	up to 600 characters
`context`	`string`	up to 120 characters
`language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`options`	`object[]`	up to 8 items, default []
`options[].label`	`string`	required up to 40 characters
`options[].imageUrl`	`string (URL)`
`options[].imageUrls`	`string (URL)[]`	up to 4 items
`scaleLabels`	`object`
`scaleLabels.low`	`string`	required up to 24 characters
`scaleLabels.high`	`string`	required up to 24 characters
`neither`	`boolean`	default false
`stimulus`	`object`
`stimulus.imageUrl`	`string (URL)`
`stimulus.audioUrl`	`string (URL)`
`stimulus.text`	`string`	up to 120 characters
`stimulus.exposureMs`	`integer`	2000–10000
`n`	`integer`	10–5000, default 50
`tier`	`1 \| 2 \| 3`	default 1
`rush`	`boolean`	default false
`targeting`	`object`
`targeting.countries`	`string[]`	up to 50 items, default []
`targeting.tags`	`string[]`	up to 20 items, default []
`targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`targeting.verifiedAge`	`boolean`
`clickTest`	`object`
`clickTest.maxTaps`	`integer`	1–5, default 1
`scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`publicResults`	`boolean`	default false
`reason`	`"off" \| "optional" \| "required"`	default "off"
`goRule`	`object`
`goRule.goAbove`	`number`	required 0.5–0.95
`goRule.minAnswers`	`integer`	required 5–5000
`contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`interestAudienceId`	`string`	up to 40 characters
`minGrade`	`1 \| 2 \| 3`
`interestPrice`	`object`
`interestPrice.perAnswerPence`	`integer`	required 1–10000
`interestPrice.headShareBps`	`integer`	required 0–10000
`answeredBy`	`"heads" \| "private"`	default "heads"
`openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`shownAs`	`string`	up to 40 characters

Response (JSON)
Field	Type	Notes
`id`	`string`	required
`draft`	`object`	required
`draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`draft.text`	`string`	up to 600 characters
`draft.context`	`string`	up to 120 characters
`draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`draft.options`	`object[]`	up to 8 items, default []
`draft.options[].label`	`string`	required up to 40 characters
`draft.options[].imageUrl`	`string (URL)`
`draft.options[].imageUrls`	`string (URL)[]`	up to 4 items
`draft.scaleLabels`	`object`
`draft.scaleLabels.low`	`string`	required up to 24 characters
`draft.scaleLabels.high`	`string`	required up to 24 characters
`draft.neither`	`boolean`	default false
`draft.stimulus`	`object`
`draft.stimulus.imageUrl`	`string (URL)`
`draft.stimulus.audioUrl`	`string (URL)`
`draft.stimulus.text`	`string`	up to 120 characters
`draft.stimulus.exposureMs`	`integer`	2000–10000
`draft.n`	`integer`	10–5000, default 50
`draft.tier`	`1 \| 2 \| 3`	default 1
`draft.rush`	`boolean`	default false
`draft.targeting`	`object`
`draft.targeting.countries`	`string[]`	required up to 50 items, default []
`draft.targeting.tags`	`string[]`	required up to 20 items, default []
`draft.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`draft.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`draft.targeting.verifiedAge`	`boolean`
`draft.clickTest`	`object`
`draft.clickTest.maxTaps`	`integer`	required 1–5, default 1
`draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`draft.publicResults`	`boolean`	default false
`draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`draft.goRule`	`object`
`draft.goRule.goAbove`	`number`	required 0.5–0.95
`draft.goRule.minAnswers`	`integer`	required 5–5000
`draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`draft.interestAudienceId`	`string`	up to 40 characters
`draft.minGrade`	`1 \| 2 \| 3`
`draft.interestPrice`	`object`
`draft.interestPrice.perAnswerPence`	`integer`	required 1–10000
`draft.interestPrice.headShareBps`	`integer`	required 0–10000
`draft.answeredBy`	`"heads" \| "private"`	default "heads"
`draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`draft.shownAs`	`string`	up to 40 characters
`updatedAt`	`string`	required
`origin`	`"zapier_test" \| null`

DELETE`/v1/drafts/{id}`

Delete a saved draft.

API key or OAuth token with questions:write.

Deleting a draft that is already gone still answers { ok: true }.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

POST`/v1/question-reviews`

Start a background review of a draft's wording, or find the one already done.

API key or OAuth token with questions:write.

Advice only: it never spends and never changes the price. Returns at once with pending; ask again (GET) after retryMs. The same words are reviewed once a day, so calling it on every save is fine. skipped means there was nothing to review, with the reason in review.skippedReason. Each suggestion is one change to the draft (op) that you apply yourself; a tidy suggestion fixes capitals and spacing.

Request body (JSON)
Field	Type	Notes
`draft`	`object`	required
`draft.type`	`"single_choice" \| "multi_choice" \| "ab_image" \| "pairwise" \| "scale_1_5" \| "ranking" \| "yes_no" \| "yes_mostly_no" \| "free_text" \| "click_test" \| "reaction" \| "rate_each"`	required
`draft.text`	`string`	required up to 600 characters
`draft.context`	`string`	up to 120 characters
`draft.language`	`string`	pattern ^[a-z]{2}(-[A-Z]{2})?$, default "en"
`draft.options`	`object[]`	up to 8 items, default []
`draft.options[].label`	`string`	required up to 40 characters
`draft.options[].imageUrl`	`string (URL)`
`draft.options[].imageUrls`	`string (URL)[]`	up to 4 items
`draft.scaleLabels`	`object`
`draft.scaleLabels.low`	`string`	required up to 24 characters
`draft.scaleLabels.high`	`string`	required up to 24 characters
`draft.neither`	`boolean`	default false
`draft.stimulus`	`object`
`draft.stimulus.imageUrl`	`string (URL)`
`draft.stimulus.audioUrl`	`string (URL)`
`draft.stimulus.text`	`string`	up to 120 characters
`draft.stimulus.exposureMs`	`integer`	2000–10000
`draft.n`	`integer`	10–5000, default 50
`draft.tier`	`1 \| 2 \| 3`	default 1
`draft.rush`	`boolean`	default false
`draft.targeting`	`object`
`draft.targeting.countries`	`string[]`	up to 50 items, default []
`draft.targeting.tags`	`string[]`	up to 20 items, default []
`draft.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`draft.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`draft.targeting.verifiedAge`	`boolean`
`draft.clickTest`	`object`
`draft.clickTest.maxTaps`	`integer`	1–5, default 1
`draft.scheduledFor`	`string (date-time)`	pattern ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
`draft.publicResults`	`boolean`	default false
`draft.reason`	`"off" \| "optional" \| "required"`	default "off"
`draft.goRule`	`object`
`draft.goRule.goAbove`	`number`	required 0.5–0.95
`draft.goRule.minAnswers`	`integer`	required 5–5000
`draft.contentFlag`	`"none" \| "medical" \| "violence" \| "distressing" \| "alcohol_gambling" \| "political"`
`draft.interestAudienceId`	`string`	up to 40 characters
`draft.minGrade`	`1 \| 2 \| 3`
`draft.interestPrice`	`object`
`draft.interestPrice.perAnswerPence`	`integer`	required 1–10000
`draft.interestPrice.headShareBps`	`integer`	required 0–10000
`draft.answeredBy`	`"heads" \| "private"`	default "heads"
`draft.openForDays`	`1 \| 7 \| 14 \| 30`	default 7
`draft.shownAs`	`string`	up to 40 characters

Response (JSON)
Field	Type	Notes
`inputHash`	`string`	required
`status`	`"pending" \| "ready" \| "skipped" \| "failed"`	required
`review`	`object`
`review.status`	`"ok" \| "skipped" \| "unavailable"`	required
`review.rubricVersion`	`string`	required
`review.model`	`string`
`review.inputHash`	`string`
`review.overall`	`"pass" \| "suggest"`
`review.scores`	`object`
`review.scores.clarity`	`integer`	required 1–5
`review.scores.singleIdea`	`integer`	required 1–5
`review.scores.neutral`	`integer`	required 1–5
`review.scores.options`	`integer`	required 1–5
`review.scores.answerable`	`integer`	required 1–5
`review.scores.length`	`integer`	required 1–5
`review.suggestions`	`object[]`
`review.suggestions[].id`	`string`	required
`review.suggestions[].code`	`"tidy" \| "spelling" \| "clarity" \| "single_idea" \| "leading" \| "overlap" \| "neither" \| "length" \| "jargon" \| "not_a_preference" \| "show_the_thing" \| "parallel" \| "policy"`	required
`review.suggestions[].severity`	`"info" \| "suggest" \| "strong"`	required
`review.suggestions[].field`	`string`	required
`review.suggestions[].reason`	`string`	required up to 180 characters
`review.suggestions[].op`	`object \| object \| object \| object \| object \| object \| object \| object \| object \| object`
`review.skippedReason`	`"flag_off" \| "incomplete" \| "no_text" \| "content_refused" \| "ai_off" \| "asks_killed"`
`retryMs`	`integer`

GET`/v1/question-reviews/{hash}`

Where a draft's review stands: pending, ready, skipped or failed.

API key or OAuth token with questions:write.

Response (JSON)
Field	Type	Notes
`inputHash`	`string`	required
`status`	`"pending" \| "ready" \| "skipped" \| "failed"`	required
`review`	`object`
`review.status`	`"ok" \| "skipped" \| "unavailable"`	required
`review.rubricVersion`	`string`	required
`review.model`	`string`
`review.inputHash`	`string`
`review.overall`	`"pass" \| "suggest"`
`review.scores`	`object`
`review.scores.clarity`	`integer`	required 1–5
`review.scores.singleIdea`	`integer`	required 1–5
`review.scores.neutral`	`integer`	required 1–5
`review.scores.options`	`integer`	required 1–5
`review.scores.answerable`	`integer`	required 1–5
`review.scores.length`	`integer`	required 1–5
`review.suggestions`	`object[]`
`review.suggestions[].id`	`string`	required
`review.suggestions[].code`	`"tidy" \| "spelling" \| "clarity" \| "single_idea" \| "leading" \| "overlap" \| "neither" \| "length" \| "jargon" \| "not_a_preference" \| "show_the_thing" \| "parallel" \| "policy"`	required
`review.suggestions[].severity`	`"info" \| "suggest" \| "strong"`	required
`review.suggestions[].field`	`string`	required
`review.suggestions[].reason`	`string`	required up to 180 characters
`review.suggestions[].op`	`object \| object \| object \| object \| object \| object \| object \| object \| object \| object`
`review.skippedReason`	`"flag_off" \| "incomplete" \| "no_text" \| "content_refused" \| "ai_off" \| "asks_killed"`
`retryMs`	`integer`

POST`/v1/uploads`

A pre-signed URL to upload an image or sound clip.

API key or OAuth token with questions:write.

PUT the file to uploadUrl with the returned headers (the URL is the credential, for 15 minutes), then use publicUrl in the question. Images are checked and their metadata stripped before heads see them.

Request body (JSON)
Field	Type	Notes
`kind`	`"image" \| "audio"`	required
`contentType`	`string`	required
`bytes`	`integer`	required

Response (JSON)
Field	Type	Notes
`uploadUrl`	`string`	required
`publicUrl`	`string`	required
`headers`	`map of string`	required

POST`/v1/uploads/import`

Copy an image from a public https link into 50heads.

API key or OAuth token with questions:write.

The image is fetched on our side (public https hosts only, three redirects at most), checked like an upload and stored. JPEG, PNG or WebP up to 5 MB.

Request body (JSON)
Field	Type	Notes
`url`	`string (URL)`	required

Response (JSON)
Field	Type	Notes
`publicUrl`	`string`	required
`width`	`integer \| null`	required
`height`	`integer \| null`	required

POST`/v1/mockups`

Draw a store listing or search result mockup from your details.

API key or OAuth token with questions:write.

A listing or a search result in 50heads styling (never a marketplace's), 1200 × 1600, drawn from a title, a price, a rating, a review count and your image, then stored like an upload. Use imageUrl on an option or the stimulus within 15 minutes. See docs/specs/mockups.md.

Request body (JSON)
Field	Type	Notes
`kind`	`"listing" \| "search_result"`	required
`title`	`string`	required up to 120 characters
`price`	`object`	required
`price.amount`	`number`	required 0–1000000
`price.currency`	`"GBP" \| "USD" \| "EUR" \| "CAD" \| "JPY" \| "KRW" \| "SEK" \| "DKK" \| "NOK" \| "PLN" \| "BRL" \| "CZK" \| "RON" \| "TRY" \| "CLP" \| "COP" \| "ARS" \| "PEN" \| "UYU"`	required
`rating`	`number`	0–5
`reviews`	`integer`	0–100000000
`imageUrl`	`string (URL)`	required
`line`	`string`	up to 40 characters

Response (JSON)
Field	Type	Notes
`kind`	`"listing" \| "search_result"`	required
`imageUrl`	`string`	required
`width`	`integer`	required
`height`	`integer`	required
`expiresAt`	`string`	required

Projects

Group questions into projects in the account the key belongs to (yours or a team's). Label, archive and give each question your own reference with the question routes.

GET`/v1/projects`

Projects in use, or the archived ones.

API key or OAuth token with questions:read.

Query parameters
Field	Type	Notes
`archived`	`boolean`

Response (JSON)
Field	Type	Notes
`projects`	`object[]`	required
`projects[].id`	`string`	required
`projects[].name`	`string`	required
`projects[].description`	`string \| null`	required
`projects[].goal`	`string \| null`	required
`projects[].bookmarked`	`boolean`	required
`projects[].archived`	`boolean`	required
`projects[].costCenter`	`string \| null`
`projects[].questionCount`	`integer`	required
`projects[].createdAt`	`string`	required
`projects[].updatedAt`	`string`	required

POST`/v1/projects`

Make a project.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 80 characters
`description`	`string \| null`
`goal`	`string \| null`

Response (JSON)
Field	Type	Notes
`project`	`object`	required
`project.id`	`string`	required
`project.name`	`string`	required
`project.description`	`string \| null`	required
`project.goal`	`string \| null`	required
`project.bookmarked`	`boolean`	required
`project.archived`	`boolean`	required
`project.costCenter`	`string \| null`
`project.questionCount`	`integer`	required
`project.createdAt`	`string`	required
`project.updatedAt`	`string`	required

PATCH`/v1/projects/{id}`

Rename, bookmark or archive a project.

API key or OAuth token with questions:write.

Request body (JSON)
Field	Type	Notes
`name`	`string`	up to 80 characters
`description`	`string \| null`
`goal`	`string \| null`
`bookmarked`	`boolean`
`archived`	`boolean`
`costCenter`	`string \| null`

Response (JSON)
Field	Type	Notes
`project`	`object`	required
`project.id`	`string`	required
`project.name`	`string`	required
`project.description`	`string \| null`	required
`project.goal`	`string \| null`	required
`project.bookmarked`	`boolean`	required
`project.archived`	`boolean`	required
`project.costCenter`	`string \| null`
`project.questionCount`	`integer`	required
`project.createdAt`	`string`	required
`project.updatedAt`	`string`	required

DELETE`/v1/projects/{id}`

Delete a project. Its questions stay, outside any project.

API key or OAuth token with questions:write.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Audiences

Panels of heads who proved they fit something (UK commuter cyclists, for example). Ask one by putting its id in a draft's `interestAudienceId`, with a `minGrade`: it replaces targeting, and the price per answer is the audience's at that grade.

GET`/v1/interest-audiences`

Audiences you can ask, with their size band and price per answer by grade.

No authentication.

open=1 keeps only audiences open to join from the caller's country. With a key and mine=asking, private audiences your team sponsors are listed too. Sizes are bands, never counts.

Query parameters
Field	Type	Notes
`q`	`string`	up to 60 characters
`country`	`string`	pattern ^[A-Z]{2}$
`lang`	`string`	up to 5 characters
`category`	`"outdoors" \| "home" \| "family" \| "food_drink" \| "games_tech" \| "travel" \| "motoring" \| "work" \| "shopping" \| "pets" \| "seasonal"`
`open`	`"0" \| "1"`
`mine`	`"asking"`

Response (JSON)
Field	Type	Notes
`audiences`	`object[]`	required
`audiences[].id`	`string`	required
`audiences[].slug`	`string`	required
`audiences[].name`	`string`	required
`audiences[].summary`	`string`	required
`audiences[].imageUrl`	`string \| null`	required
`audiences[].status`	`"draft" \| "recruiting" \| "live" \| "closed"`	required
`audiences[].category`	`string`	required
`audiences[].geoAllow`	`string[]`	required
`audiences[].languages`	`string[]`	required
`audiences[].poolBand`	`"under_50" \| "50_200" \| "200_500" \| "500_plus"`	required
`audiences[].prices`	`object`	required
`audiences[].prices.grade1`	`integer`	required
`audiences[].prices.grade2`	`integer`	required
`audiences[].prices.grade3`	`integer`	required
`audiences[].headShareBps`	`integer`	required
`audiences[].payFromPence`	`integer`	required
`audiences[].geoOk`	`boolean`	required
`audiences[].sponsored`	`boolean`	required
`audiences[].expiresAt`	`string \| null`	required

GET`/v1/interest-audiences/{slug}`

One audience: what it is, the tags it stamps, grades and pay.

No authentication.

Response (JSON)
Field	Type	Notes
`audience`	`object`	required
`audience.slug`	`string`	required
`audience.name`	`string`	required
`audience.summary`	`string`	required
`audience.overview`	`string[]`	required
`audience.whoFor`	`string`	required
`audience.imageUrl`	`string \| null`	required
`audience.status`	`"draft" \| "recruiting" \| "live" \| "closed"`	required
`audience.geoAllow`	`string[]`	required
`audience.languages`	`string[]`	required
`audience.tags`	`object[]`	required
`audience.tags[].id`	`string`	required
`audience.tags[].label`	`string`	required
`audience.grades`	`object[]`	required
`audience.grades[].grade`	`1 \| 2 \| 3`	required
`audience.grades[].name`	`string`	required
`audience.grades[].pricePence`	`integer`	required
`audience.grades[].headPayPence`	`integer`	required
`audience.grades[].how`	`"quiz" \| "work_email_domain" \| "org_code" \| "review"`	required
`audience.poolBand`	`"under_50" \| "50_200" \| "200_500" \| "500_plus"`	required
`audience.country`	`string \| null`	required
`audience.geoOk`	`boolean`	required
`audience.quiz`	`object`	required
`audience.quiz.items`	`integer`	required
`audience.quiz.passMark`	`integer`	required
`audience.quiz.timeLimitS`	`integer`	required
`audience.trustedDomains`	`string[]`	required

Saved audiences

A targeting setup you reuse: how many heads, tier, rush, language and who to ask, saved under a name in the account the caller acts for (yours or a team's). They are for the portal and the app composer, so these routes need a signed-in person; API keys and connected apps get 403 `session_required`. To ask the same audience from a key, send the same fields in the draft.

GET`/v1/audiences`

Saved audiences in the account.

Portal session only.

A person signed in at 50heads.com or in the app. Keys and connected apps get 403 session_required.

Response (JSON)
Field	Type	Notes
`audiences`	`object[]`	required
`audiences[].id`	`string`	required
`audiences[].name`	`string`	required up to 60 characters
`audiences[].n`	`integer`	required 10–5000
`audiences[].tier`	`1 \| 2 \| 3`	required
`audiences[].rush`	`boolean`	required
`audiences[].language`	`string`	required
`audiences[].targeting`	`object`	required
`audiences[].targeting.countries`	`string[]`	required up to 50 items, default []
`audiences[].targeting.tags`	`string[]`	required up to 20 items, default []
`audiences[].targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`audiences[].targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`audiences[].targeting.verifiedAge`	`boolean`

POST`/v1/audiences`

Save an audience under a name.

Portal session only.

A person signed in. Team members who can ask can save for the team. At most 50 per account: 409 too_many_audiences after that.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 60 characters
`n`	`integer`	required 10–5000
`tier`	`1 \| 2 \| 3`	required
`rush`	`boolean`	required
`language`	`string`	required
`targeting`	`object`	required
`targeting.countries`	`string[]`	up to 50 items, default []
`targeting.tags`	`string[]`	up to 20 items, default []
`targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`targeting.verifiedAge`	`boolean`

Response (JSON)
Field	Type	Notes
`audience`	`object`	required
`audience.id`	`string`	required
`audience.name`	`string`	required up to 60 characters
`audience.n`	`integer`	required 10–5000
`audience.tier`	`1 \| 2 \| 3`	required
`audience.rush`	`boolean`	required
`audience.language`	`string`	required
`audience.targeting`	`object`	required
`audience.targeting.countries`	`string[]`	required up to 50 items, default []
`audience.targeting.tags`	`string[]`	required up to 20 items, default []
`audience.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`audience.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`audience.targeting.verifiedAge`	`boolean`

PUT`/v1/audiences/{id}`

Replace a saved audience.

Portal session only.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 60 characters
`n`	`integer`	required 10–5000
`tier`	`1 \| 2 \| 3`	required
`rush`	`boolean`	required
`language`	`string`	required
`targeting`	`object`	required
`targeting.countries`	`string[]`	up to 50 items, default []
`targeting.tags`	`string[]`	up to 20 items, default []
`targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`targeting.verifiedAge`	`boolean`

Response (JSON)
Field	Type	Notes
`audience`	`object`	required
`audience.id`	`string`	required
`audience.name`	`string`	required up to 60 characters
`audience.n`	`integer`	required 10–5000
`audience.tier`	`1 \| 2 \| 3`	required
`audience.rush`	`boolean`	required
`audience.language`	`string`	required
`audience.targeting`	`object`	required
`audience.targeting.countries`	`string[]`	required up to 50 items, default []
`audience.targeting.tags`	`string[]`	required up to 20 items, default []
`audience.targeting.ageBands`	`"18-24" \| "25-34" \| "35-44" \| "45-54" \| "55-64" \| "65+"[]`	up to 6 items
`audience.targeting.genders`	`"woman" \| "man" \| "non_binary"[]`	up to 3 items
`audience.targeting.verifiedAge`	`boolean`

DELETE`/v1/audiences/{id}`

Delete a saved audience.

Portal session only.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Credits and account

Balance, ledger, invoices and statements. Credits are bought on the web; the API spends them.

GET`/v1/billing/balance`

Credits, what is reserved by live questions, and what is left under this key's daily cap.

API key or OAuth token with account:read.

Response (JSON)
Field	Type	Notes
`credits`	`integer`	required
`reserved`	`integer`	required
`expiring`	`object[]`	required
`expiring[].credits`	`integer`	required
`expiring[].expiresAt`	`string`	required
`currency`	`"GBP" \| "USD" \| "EUR" \| "CAD" \| "JPY" \| "KRW" \| "BRL" \| "TRY" \| "SEK" \| "DKK" \| "NOK" \| "PLN" \| "CZK" \| "RON"`	required
`capRemaining`	`integer \| null`	required
`freeQuestionToday`	`boolean`	required
`privateDeclaredAt`	`string \| null`
`privateFreeAnswersLeft`	`integer`

GET`/v1/billing/ledger`

Every credit movement, newest first.

API key or OAuth token with account:read.

Query parameters
Field	Type	Notes
`cursor`	`string`

Response (JSON)
Field	Type	Notes
`rows`	`object[]`	required
`rows[].id`	`string`	required
`rows[].at`	`string`	required
`rows[].kind`	`"purchase" \| "ask" \| "refund" \| "say" \| "bonus" \| "referral" \| "payout" \| "payout_returned" \| "fee" \| "expiry" \| "clawback" \| "adjustment" \| "tier2_fee" \| "not_paid" \| "founder_credits"`	required
`rows[].title`	`string`	required
`rows[].state`	`"pending" \| "available" \| "in_flight" \| "paid" \| "reversed" \| "not_paid"`	required
`rows[].amount`	`integer`	required
`rows[].ref`	`string \| null`	required
`rows[].notPaid`	`object \| null`
`rows[].notPaid.id`	`string`	required
`rows[].notPaid.source`	`"rejected" \| "clawback"`	required
`rows[].notPaid.reason`	`"too_fast" \| "repeat" \| "check_question" \| "automated" \| "linked_accounts" \| "shared_payout_method" \| "confirmed_fraud"`	required
`rows[].notPaid.amount`	`integer`	required
`rows[].notPaid.status`	`"not_paid" \| "appealed" \| "upheld" \| "not_upheld"`	required
`rows[].notPaid.appealBy`	`string \| null`	required
`rows[].notPaid.decisionBy`	`string \| null`	required
`rows[].by`	`string \| null`
`rows[].source`	`"web" \| "apple" \| "google"`
`rows[].releaseAt`	`string \| null`
`nextCursor`	`string \| null`	required

POST`/v1/billing/checkout`

Start a card or bank-transfer purchase (portal session only).

Portal session only.

Not available to API keys: buying credits needs a signed-in person.

Request body (JSON)
Field	Type	Notes
`pack`	`string`	required
`currency`	`"GBP" \| "USD" \| "EUR" \| "CAD"`	required
`method`	`"card" \| "bank_transfer"`	required
`returnPath`	`string`	pattern ^\/app(\/[\w\-/]*)?$

POST`/v1/billing/store-purchases/intent`

Start an App Store or Google Play credit-pack purchase. Returns the account token to pass to the store.

Portal session only.

The app sends appAccountToken to StoreKit and obfuscatedAccountId to Play Billing. Credits are granted by storePurchase after the store returns a signed transaction or purchase token.

Request body (JSON)
Field	Type	Notes
`store`	`"apple" \| "google"`	required

Response (JSON)
Field	Type	Notes
`appAccountToken`	`string`	required
`obfuscatedAccountId`	`string`	required

POST`/v1/billing/store-purchases`

Verify an App Store or Google Play credit-pack purchase and grant the credits once.

Portal session only.

Apple: signedTransaction is the StoreKit 2 JWS. Google: purchaseToken is checked with the Play Developer API, then consumed. A repeat of the same transaction returns status duplicate and does not grant again. Finish the store transaction only after this succeeds. The stores are the merchant of record, so this does not create a VAT invoice.

Request body (JSON)
Field	Type	Notes
`store`	`"apple" \| "google"`	required
`productId`	`string`	required
`signedTransaction`	`string`	at least 20 characters
`purchaseToken`	`string`	at least 8 characters

Response (JSON)
Field	Type	Notes
`status`	`"granted" \| "duplicate"`	required
`credits`	`integer`	required
`transactionId`	`string`	required
`productId`	`string`	required
`balance`	`integer`	required
`testPurchase`	`boolean`

GET`/v1/billing/store-purchases`

Recent App Store and Google Play credit-pack purchases on the account, newest first.

Portal session only.

Each purchase has the credits added, when, its state (granted or refunded) and the receipt currency and price in minor units. Currency and price are null where the store's receipt does not state them (Google Play). Test purchases that added no credits are left out.

Response (JSON)
Field	Type	Notes
`purchases`	`object[]`	required
`purchases[].id`	`string`	required
`purchases[].store`	`"apple" \| "google"`	required
`purchases[].productId`	`string`	required
`purchases[].credits`	`integer`	required
`purchases[].state`	`"granted" \| "refunded"`	required
`purchases[].at`	`string`	required
`purchases[].refundedAt`	`string \| null`	required
`purchases[].currency`	`string \| null`	required
`purchases[].priceMinor`	`integer \| null`	required
`purchases[].orderId`	`string`	required

GET`/v1/billing/invoices`

Invoices, credit notes and self-billing statements, newest first.

API key or OAuth token with account:read.

Each has a pdfUrl on this API; fetch it with the same key.

Response (JSON)
Field	Type	Notes
`invoices`	`object[]`	required
`invoices[].id`	`string`	required
`invoices[].number`	`string`	required
`invoices[].kind`	`"invoice" \| "credit_note" \| "self_billing"`	required
`invoices[].issuedAt`	`string`	required
`invoices[].currency`	`string`	required
`invoices[].net`	`number`	required
`invoices[].vat`	`number`	required
`invoices[].total`	`number`	required
`invoices[].vatTreatment`	`"uk_standard" \| "reverse_charge" \| "outside_scope" \| "none"`	required
`invoices[].pdfUrl`	`string`	required

GET`/v1/billing/invoices/{id}/pdf`

An invoice or credit note as a PDF.

API key or OAuth token with account:read.

GET`/v1/billing/profile`

The legal name, address and VAT number printed on invoices.

API key or OAuth token with account:read.

Changing it (PUT) needs a signed-in person.

Response (JSON)
Field	Type	Notes
`legalName`	`string \| null`	required
`address`	`string \| null`	required
`country`	`string \| null`	required
`vatNumber`	`string \| null`	required
`vatValid`	`boolean \| null`	required

GET`/v1/billing/statements`

Monthly and annual credit statements.

API key or OAuth token with account:read.

Response (JSON)
Field	Type	Notes
`statements`	`object[]`	required
`statements[].id`	`string`	required
`statements[].period`	`string`	required
`statements[].kind`	`"monthly" \| "annual"`	required
`statements[].total`	`integer`	required
`statements[].pdfUrl`	`string`	required
`statements[].csvUrl`	`string \| null`

GET`/v1/billing/statements/{id}/{format}`

One statement as a PDF, or as CSV (`format` is `pdf` or `csv`).

API key or OAuth token with account:read.

format csv answers text/csv instead.

GET`/v1/billing/transfers`

Bank transfers waiting for the money to arrive, or matched.

API key or OAuth token with account:read.

Response (JSON)
Field	Type	Notes
`transfers`	`object[]`	required
`transfers[].reference`	`string`	required
`transfers[].pack`	`string`	required
`transfers[].credits`	`integer`	required
`transfers[].amount`	`number`	required
`transfers[].currency`	`"GBP" \| "USD" \| "EUR" \| "CAD"`	required
`transfers[].status`	`"awaiting" \| "received" \| "expired"`	required
`transfers[].createdAt`	`string`	required
`transfers[].expiresAt`	`string`	required

GET`/v1/billing/invoice-terms`

Whether you have 14-day invoice terms for the larger packs.

API key or OAuth token with account:read.

Asking for terms (POST) needs a signed-in person.

Response (JSON)
Field	Type	Notes
`status`	`"none" \| "pending" \| "approved" \| "declined"`	required
`termsDays`	`integer \| null`	required
`decidedAt`	`string \| null`	required
`purchaseOrder`	`string \| null`
`billingContactName`	`string \| null`
`billingContactEmail`	`string \| null`

GET`/v1/billing/disputes`

Disputes you opened on questions, and how they ended.

API key or OAuth token with account:read.

Response (JSON)
Field	Type	Notes
`disputes`	`object[]`	required
`disputes[].id`	`string`	required
`disputes[].questionId`	`string`	required
`disputes[].title`	`string`	required
`disputes[].reason`	`string`	required
`disputes[].status`	`"open" \| "upheld" \| "partly_upheld" \| "not_upheld"`	required
`disputes[].refundCredits`	`integer`	required
`disputes[].creditNoteId`	`string \| null`	required
`disputes[].createdAt`	`string`	required
`disputes[].resolvedAt`	`string \| null`	required

GET`/v1/billing/packs`

The credit packs on sale and their price in a currency.

No authentication.

Query parameters
Field	Type	Notes
`currency`	`string`

Response (JSON)
Field	Type	Notes
`packs`	`object[]`	required
`packs[].id`	`string`	required
`packs[].credits`	`integer`	required
`packs[].bonusCredits`	`integer`	required
`packs[].price`	`number`	required
`packs[].currency`	`string`	required
`packs[].bankTransfer`	`boolean`	required

GET`/v1/me`

The account behind the key: name, tier, languages, credits and sign-in providers.

API key or OAuth token with account:read.

Response (JSON)
Field	Type	Notes
`user`	`object`	required
`user.id`	`string`	required
`user.email`	`string (email)`	required pattern ^(?:[A-Za-z0-9_'+\-]+\.)[A-Za-z0-9_'+\-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
`user.name`	`string \| null`	required
`user.tier`	`0 \| 1 \| 2 \| 3`	required
`user.country`	`string \| null`	required
`user.phone`	`string \| null`	required
`user.displayCurrency`	`"GBP" \| "USD" \| "EUR" \| "CAD" \| "JPY" \| "KRW" \| "BRL" \| "TRY" \| "SEK" \| "DKK" \| "NOK" \| "PLN" \| "CZK" \| "RON" \| null`	required
`user.languages`	`"en" \| "fr" \| "es" \| "pt" \| "it" \| "de" \| "nl" \| "pl" \| "ja" \| "ko" \| "sv" \| "da" \| "nb" \| "cs" \| "ro" \| "fi" \| "tr"[]`	required
`user.locale`	`string \| null`	required
`user.creditsPence`	`integer`	required
`user.earningsPence`	`integer`	required
`user.pendingPence`	`integer`	required
`user.providers`	`"apple" \| "google" \| "email"[]`	required
`user.createdAt`	`string`	required
`user.demo`	`boolean`
`user.captureAllowed`	`boolean`
`user.storeReview`	`boolean`

GET`/v1/connections/current`

The connection behind this key or token: its scopes, its caps and what it has spent today and this month.

API key or OAuth token.

Any key or token can read its own; no scope is needed. This is what MCP balance uses to show an agent its cap. 404 not_found for a first-party session, which has no connection.

Response (JSON)
Field	Type	Notes
`connection`	`object`	required
`connection.id`	`string`	required
`connection.kind`	`"oauth" \| "key" \| "app"`	required
`connection.clientId`	`string \| null`	required
`connection.clientName`	`string`	required
`connection.host`	`string \| null`	required
`connection.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`connection.capDailyPence`	`integer`	required
`connection.spentTodayPence`	`integer`	required
`connection.spentMonthPence`	`integer`	required
`connection.protocolVersion`	`string \| null`	required
`connection.validatesIss`	`boolean \| null`	required
`connection.createdAt`	`string`	required
`connection.lastUsedAt`	`string \| null`	required
`connection.capMonthlyPence`	`integer \| null`
`connection.capQuestionPence`	`integer \| null`
`connection.teamId`	`string \| null`

POST`/v1/connections/calls`

Report tool calls made on this connection, for the usage and logs on the Developers page.

API key or OAuth token.

Used by the MCP server. Never send question text; calls are kept 90 days. 400 no_connection when the caller has no connection.

Request body (JSON)
Field	Type	Notes
`calls`	`object[]`	required up to 100 items
`calls[].tool`	`string`	required up to 64 characters
`calls[].questionId`	`string \| null`
`calls[].taskId`	`string \| null`
`calls[].outcome`	`"ok" \| "error"`	required
`calls[].code`	`string \| null`
`calls[].latencyMs`	`integer`	required 0–3600000
`calls[].traceId`	`string`	required up to 64 characters
`calls[].region`	`string \| null`
`calls[].credits`	`integer`	≥ 0
`calls[].cacheHit`	`boolean`
`host`	`string`	up to 100 characters
`protocolVersion`	`string`	up to 20 characters
`validatesIss`	`boolean`

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Support

Open a ticket from a script or an agent. Replies come by email and in the portal.

POST`/v1/support/tickets`

Open a support ticket.

API key or OAuth token.

Signed in (key, OAuth or session), the reply goes to the account's email. Without a token, send email. 10 tickets an hour.

Request body (JSON)
Field	Type	Notes
`subject`	`string`	required up to 140 characters, at least 3 characters
`body`	`string`	required up to 5000 characters, at least 10 characters
`appVersion`	`string`	up to 40 characters
`category`	`"payout" \| "payout_failed" \| "account" \| "account_frozen" \| "verification" \| "question" \| "billing" \| "api" \| "security" \| "privacy" \| "press" \| "legal" \| "support" \| "other"`
`email`	`string (email)`	pattern ^(?:[A-Za-z0-9_'+\-]+\.)[A-Za-z0-9_'+\-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
`locale`	`string`	up to 10 characters
`website`	`string`	up to 2000 characters
`openedAt`	`integer`	≥ 0

Response (JSON)
Field	Type	Notes
`ticketId`	`string`	required

Webhook endpoints

Get an HTTPS POST when something happens, instead of polling. Manage endpoints in the portal under Developers, or with a key or OAuth grant that has webhooks:read (list) and webhooks:write (change). Keys made before scopes cannot manage webhooks.

GET`/v1/webhooks/schemas`

The JSON Schema of every event's data, and the payload versions.

No authentication.

Payloads are additive inside a version: new optional fields may appear; existing fields never change meaning or disappear.

Response (JSON)
Field	Type	Notes
`apiVersions`	`"2026-10-10"[]`	required
`latest`	`"2026-10-10"`	required
`events`	`object`	required
`events.question.reserved`	`map of object`	required
`events.question.completed`	`map of object`	required
`events.question.underfilled`	`map of object`	required
`events.question.canceled`	`map of object`	required
`events.question.refused`	`map of object`	required
`events.credits.purchased`	`map of object`	required
`events.credits.low`	`map of object`	required
`events.credits.expiring`	`map of object`	required
`events.dispute.resolved`	`map of object`	required
`events.connection.cap_warning`	`map of object`	required
`events.webhook.test`	`map of object`	required
`events.member.provisioned`	`map of object`	required
`events.member.deprovisioned`	`map of object`	required
`events.policy.changed`	`map of object`	required
`events.approval.requested`	`map of object`	required
`events.approval.decided`	`map of object`	required
`events.approval.expired`	`map of object`	required
`events.approval.refused`	`map of object`	required
`events.workspace.created`	`map of object`	required
`events.workspace.moved`	`map of object`	required
`events.workspace.closed`	`map of object`	required

GET`/v1/webhooks/events`

The latest events of one type in this account, newest first, as deliveries carry them.

API key or OAuth token with webhooks:read.

Each event is the exact body a delivery sends (id, type, createdAt, apiVersion, data), so a receiver can use one as sample data or poll with it and drop ids it has seen. Events are kept whether or not an endpoint listens, for 90 days. A personal account lists the person's events, including their asks in a team; a team lists the team's. A key acts for its own account (personal or team); a session acts for the account in the account header. Team members who can ask can read; the owner and admins can change.

Query parameters
Field	Type	Notes
`type`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "webhook.test" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"`	required
`limit`	`integer`	1–25, default 3

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].type`	`string`	required
`events[].createdAt`	`string`	required
`events[].apiVersion`	`"2026-10-10"`
`events[].data`	`map of object`	required

GET`/v1/webhooks/endpoints`

The endpoints in this account (yours, or the team's). Secrets are masked.

API key or OAuth token with webhooks:read.

A key acts for its own account (personal or team); a session acts for the account in the account header. Team members who can ask can read; the owner and admins can change.

Response (JSON)
Field	Type	Notes
`endpoints`	`object[]`	required
`endpoints[].id`	`string`	required
`endpoints[].url`	`string (URL)`	required
`endpoints[].events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`	required
`endpoints[].secret`	`string`	required
`endpoints[].createdAt`	`string`	required
`endpoints[].lastDeliveryAt`	`string \| null`	required
`endpoints[].lastStatus`	`integer \| null`	required
`endpoints[].description`	`string \| null`
`endpoints[].enabled`	`boolean`
`endpoints[].disabledReason`	`string \| null`
`endpoints[].disabledAt`	`string \| null`
`endpoints[].lastSuccessAt`	`string \| null`
`endpoints[].teamId`	`string \| null`
`endpoints[].apiVersion`	`"2026-10-10"`
`endpoints[].filter`	`object \| null`
`endpoints[].filter.projectIds`	`string[]`	up to 20 items
`endpoints[].filter.labels`	`string[]`	up to 20 items
`endpoints[].previousSecret`	`object \| null`
`endpoints[].previousSecret.secret`	`string`	required
`endpoints[].previousSecret.expiresAt`	`string`	required

POST`/v1/webhooks/endpoints`

Add an endpoint. The signing secret is in the response, once.

API key or OAuth token with webhooks:write.

https only, public hosts only. Up to 10 endpoints on a personal account and 100 on a team. In a team, only the owner or an admin can add one. apiVersion defaults to the latest. An endpoint made with a key or OAuth grant is deleted when that key or grant is revoked. Zapier's REST hooks count against its connection (up to 50 each), not the account's limit.

Request body (JSON)
Field	Type	Notes
`url`	`string (URL)`	required up to 500 characters
`events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`	required
`description`	`string`	up to 100 characters
`filter`	`object`
`filter.projectIds`	`string[]`	up to 20 items
`filter.labels`	`string[]`	up to 20 items
`apiVersion`	`"2026-10-10"`

Response (JSON)
Field	Type	Notes
`endpoint`	`object`	required
`endpoint.id`	`string`	required
`endpoint.url`	`string (URL)`	required
`endpoint.events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`	required
`endpoint.secret`	`string`	required
`endpoint.createdAt`	`string`	required
`endpoint.lastDeliveryAt`	`string \| null`	required
`endpoint.lastStatus`	`integer \| null`	required
`endpoint.description`	`string \| null`
`endpoint.enabled`	`boolean`
`endpoint.disabledReason`	`string \| null`
`endpoint.disabledAt`	`string \| null`
`endpoint.lastSuccessAt`	`string \| null`
`endpoint.teamId`	`string \| null`
`endpoint.apiVersion`	`"2026-10-10"`
`endpoint.filter`	`object \| null`
`endpoint.filter.projectIds`	`string[]`	up to 20 items
`endpoint.filter.labels`	`string[]`	up to 20 items
`endpoint.previousSecret`	`object \| null`
`endpoint.previousSecret.secret`	`string`	required
`endpoint.previousSecret.expiresAt`	`string`	required

PATCH`/v1/webhooks/endpoints/{endpointId}`

Change an endpoint's address, events, description or filter, or pause and resume it.

API key or OAuth token with webhooks:write.

filter: null clears the filter. enabled: true resumes an endpoint that was switched off after failures.

Request body (JSON)
Field	Type	Notes
`url`	`string (URL)`	up to 500 characters
`events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`
`description`	`string \| null`
`enabled`	`boolean`
`filter`	`object \| null`
`filter.projectIds`	`string[]`	up to 20 items
`filter.labels`	`string[]`	up to 20 items

Response (JSON)
Field	Type	Notes
`endpoint`	`object`	required
`endpoint.id`	`string`	required
`endpoint.url`	`string (URL)`	required
`endpoint.events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`	required
`endpoint.secret`	`string`	required
`endpoint.createdAt`	`string`	required
`endpoint.lastDeliveryAt`	`string \| null`	required
`endpoint.lastStatus`	`integer \| null`	required
`endpoint.description`	`string \| null`
`endpoint.enabled`	`boolean`
`endpoint.disabledReason`	`string \| null`
`endpoint.disabledAt`	`string \| null`
`endpoint.lastSuccessAt`	`string \| null`
`endpoint.teamId`	`string \| null`
`endpoint.apiVersion`	`"2026-10-10"`
`endpoint.filter`	`object \| null`
`endpoint.filter.projectIds`	`string[]`	up to 20 items
`endpoint.filter.labels`	`string[]`	up to 20 items
`endpoint.previousSecret`	`object \| null`
`endpoint.previousSecret.secret`	`string`	required
`endpoint.previousSecret.expiresAt`	`string`	required

DELETE`/v1/webhooks/endpoints/{endpointId}`

Delete an endpoint. Nothing more is sent to it.

API key or OAuth token with webhooks:write.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

POST`/v1/webhooks/endpoints/{endpointId}/rotate-secret`

A new signing secret, shown once. The old one keeps signing for the overlap.

API key or OAuth token with webhooks:write.

overlapHours defaults to 24 (0 to 168). During the overlap every delivery carries a signature from each secret; previousSecret.expiresAt says when the old one stops. 0 cuts over at once.

Request body (JSON)
Field	Type	Notes
`overlapHours`	`integer`	0–168, default 24

Response (JSON)
Field	Type	Notes
`endpoint`	`object`	required
`endpoint.id`	`string`	required
`endpoint.url`	`string (URL)`	required
`endpoint.events`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed"[]`	required
`endpoint.secret`	`string`	required
`endpoint.createdAt`	`string`	required
`endpoint.lastDeliveryAt`	`string \| null`	required
`endpoint.lastStatus`	`integer \| null`	required
`endpoint.description`	`string \| null`
`endpoint.enabled`	`boolean`
`endpoint.disabledReason`	`string \| null`
`endpoint.disabledAt`	`string \| null`
`endpoint.lastSuccessAt`	`string \| null`
`endpoint.teamId`	`string \| null`
`endpoint.apiVersion`	`"2026-10-10"`
`endpoint.filter`	`object \| null`
`endpoint.filter.projectIds`	`string[]`	up to 20 items
`endpoint.filter.labels`	`string[]`	up to 20 items
`endpoint.previousSecret`	`object \| null`
`endpoint.previousSecret.secret`	`string`	required
`endpoint.previousSecret.expiresAt`	`string`	required

POST`/v1/webhooks/endpoints/{endpointId}/test`

Send a signed webhook.test event to this endpoint now.

API key or OAuth token with webhooks:write.

Signed and logged like any other delivery, and retried the same way if it fails.

Response (JSON)
Field	Type	Notes
`outcome`	`"succeeded" \| "retrying" \| "failed" \| "skipped"`	required
`delivery`	`object`	required
`delivery.id`	`string`	required
`delivery.endpointId`	`string`	required
`delivery.event`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed" \| "webhook.test"`	required
`delivery.status`	`integer \| null`	required
`delivery.attempts`	`integer`	required
`delivery.nextAttemptAt`	`string \| null`	required
`delivery.createdAt`	`string`	required
`delivery.eventId`	`string`
`delivery.state`	`"pending" \| "delivering" \| "succeeded" \| "failed"`
`delivery.lastError`	`string \| null`
`delivery.deliveredAt`	`string \| null`
`delivery.replayOf`	`string \| null`

GET`/v1/webhooks/deliveries`

The latest 100 deliveries, newest first.

API key or OAuth token with webhooks:read.

Query parameters
Field	Type	Notes
`endpointId`	`string`
`state`	`"pending" \| "delivering" \| "succeeded" \| "failed"`

Response (JSON)
Field	Type	Notes
`deliveries`	`object[]`	required
`deliveries[].id`	`string`	required
`deliveries[].endpointId`	`string`	required
`deliveries[].event`	`"question.reserved" \| "question.completed" \| "question.underfilled" \| "question.canceled" \| "question.refused" \| "credits.purchased" \| "credits.low" \| "credits.expiring" \| "dispute.resolved" \| "connection.cap_warning" \| "member.provisioned" \| "member.deprovisioned" \| "policy.changed" \| "approval.requested" \| "approval.decided" \| "approval.expired" \| "approval.refused" \| "workspace.created" \| "workspace.moved" \| "workspace.closed" \| "webhook.test"`	required
`deliveries[].status`	`integer \| null`	required
`deliveries[].attempts`	`integer`	required
`deliveries[].nextAttemptAt`	`string \| null`	required
`deliveries[].createdAt`	`string`	required
`deliveries[].eventId`	`string`
`deliveries[].state`	`"pending" \| "delivering" \| "succeeded" \| "failed"`
`deliveries[].lastError`	`string \| null`
`deliveries[].deliveredAt`	`string \| null`
`deliveries[].replayOf`	`string \| null`

GET`/v1/webhooks/deliveries/{deliveryId}/attempts`

Each attempt at one delivery: status, error and time taken.

API key or OAuth token with webhooks:read.

Response (JSON)
Field	Type	Notes
`attempts`	`object[]`	required
`attempts[].attempt`	`integer`	required
`attempts[].status`	`integer \| null`	required
`attempts[].error`	`string \| null`	required
`attempts[].durationMs`	`integer`	required
`attempts[].at`	`string`	required

POST`/v1/webhooks/deliveries/{deliveryId}/replay`

Send a delivery's event again, as a new delivery.

API key or OAuth token with webhooks:write.

The body and webhook-id are the original event's, so a receiver that keeps event ids ignores a duplicate. Signed with the endpoint's current secrets.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required
`deliveryId`	`string`	required

A2A push notifications

The Agent2Agent (A2A) server at https://mcp.50heads.com/a2a stores the push notification configs its peers set on a task here, and you can manage them with a key too. A task id is the question id. Each config gets a POST for every change of state, signed with its token. Reads need webhooks:read, changes webhooks:write, and both questions:read. Being introduced: 404 `not_found` until A2A is on for your account.

GET`/v1/a2a/status`

Whether the A2A server is on for anyone.

No authentication.

The agent card is at https://mcp.50heads.com/.well-known/agent-card.json while this is true.

Response (JSON)
Field	Type	Notes
`enabled`	`boolean`	required

GET`/v1/a2a/access`

Whether the A2A server is on for the caller.

API key or OAuth token.

Response (JSON)
Field	Type	Notes
`enabled`	`boolean`	required

GET`/v1/a2a/tasks/{taskId}/push-configs`

Your push notification configs on a task.

API key or OAuth token with webhooks:read.

Also needs questions:read. A task in another account is 404 not_found.

Response (JSON)
Field	Type	Notes
`configs`	`object[]`	required
`configs[].id`	`string`	required
`configs[].taskId`	`string`	required
`configs[].contextId`	`string`	required
`configs[].url`	`string`	required
`configs[].token`	`string`	required
`configs[].authentication`	`object \| null`	required
`configs[].authentication.scheme`	`string`	required
`configs[].protocolVersion`	`"1.0" \| "0.3"`	required
`configs[].createdAt`	`string`	required

POST`/v1/a2a/tasks/{taskId}/push-configs`

Send a task's changes of state to a URL.

API key or OAuth token with webhooks:write.

Also needs questions:read. https on a public host. Up to 5 configs on a task; the same id again replaces yours. Each push carries Authorization: <scheme> <credentials> when you set authentication, X-A2A-Notification-Token: <token>, and Standard Webhooks headers signed with the secret whsec_ + base64(token), so you verify it with the token alone. protocolVersion 1.0 sends a StreamResponse with a statusUpdate (application/a2a+json); 0.3 sends the Task. Call GetTask (or GET /v2/questions/{id}/result) for the results.

Request body (JSON)
Field	Type	Notes
`id`	`string`	pattern ^[A-Za-z0-9._:-]{1,64}$
`url`	`string`	required up to 2000 characters
`token`	`string`	up to 512 characters, at least 16 characters
`authentication`	`object`
`authentication.scheme`	`string`	required up to 40 characters, pattern ^[A-Za-z][A-Za-z0-9!#$%&'+.^_`\|~-]$
`authentication.credentials`	`string`	up to 4096 characters
`protocolVersion`	`"1.0" \| "0.3"`	default "1.0"

Response (JSON)
Field	Type	Notes
`config`	`object`	required
`config.id`	`string`	required
`config.taskId`	`string`	required
`config.contextId`	`string`	required
`config.url`	`string`	required
`config.token`	`string`	required
`config.authentication`	`object \| null`	required
`config.authentication.scheme`	`string`	required
`config.protocolVersion`	`"1.0" \| "0.3"`	required
`config.createdAt`	`string`	required

GET`/v1/a2a/tasks/{taskId}/push-configs/{configId}`

One of your push notification configs on a task.

API key or OAuth token with webhooks:read.

Also needs questions:read. Credentials are never returned; the token is.

Response (JSON)
Field	Type	Notes
`config`	`object`	required
`config.id`	`string`	required
`config.taskId`	`string`	required
`config.contextId`	`string`	required
`config.url`	`string`	required
`config.token`	`string`	required
`config.authentication`	`object \| null`	required
`config.authentication.scheme`	`string`	required
`config.protocolVersion`	`"1.0" \| "0.3"`	required
`config.createdAt`	`string`	required

DELETE`/v1/a2a/tasks/{taskId}/push-configs/{configId}`

Stop a push notification config. Nothing more is sent to it.

API key or OAuth token with webhooks:write.

Also needs questions:read. Deleting one that is already gone answers ok.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Workspace apps

Ask from Slack, Microsoft Teams, Jira, Linear or Zapier. Install 50heads into a Slack workspace, a Jira site or a Linear workspace from the portal under Settings, Integrations; asks from it spend this account's credits up to a daily cap. In Jira and Linear, a comment that starts with `/50heads ask` asks from the issue, and the results come back to the issue as a comment. Zapier connects with OAuth like any other app and is listed beside the Slack installs. List apps with apps:read; change the cap or remove one with apps:write.

GET`/v1/apps`

The workspace apps installed in this account (yours, or the team's), and its Zapier connections, with today's spend.

API key or OAuth token with apps:read.

Keys made before scopes cannot list apps. In a team, any role that can ask may list them. zapier lists live Zapier connections with their daily cap, today's spend and live REST hooks; removing one in the portal revokes the connection and deletes its hooks.

Response (JSON)
Field	Type	Notes
`apps`	`object[]`	required
`apps[].id`	`string`	required
`apps[].provider`	`"slack" \| "teams" \| "jira" \| "linear"`	required
`apps[].workspaceId`	`string`	required
`apps[].workspaceName`	`string`	required
`apps[].defaultChannelName`	`string \| null`	required
`apps[].capDailyPence`	`integer`	required
`apps[].spentTodayPence`	`integer`	required
`apps[].installedAt`	`string`	required
`apps[].installedBy`	`object`	required
`apps[].installedBy.name`	`string \| null`	required
`apps[].installedBy.email`	`string \| null`	required
`apps[].status`	`"active" \| "revoked"`	required
`zapier`	`object[]`	required default []
`zapier[].connectionId`	`string`	required
`zapier[].connectedAt`	`string`	required
`zapier[].lastUsedAt`	`string \| null`	required
`zapier[].capDailyPence`	`integer`	required
`zapier[].spentTodayPence`	`integer`	required
`zapier[].hooks`	`integer`	required
`zapier[].connectedBy`	`object`	required
`zapier[].connectedBy.name`	`string \| null`	required
`zapier[].connectedBy.email`	`string \| null`	required
`teamsAvailable`	`boolean`	required default false
`jiraAvailable`	`boolean`	required default false
`linearAvailable`	`boolean`	required default false

GET`/v1/apps/slack/install`

Slack's authorize page, with a signed state that works once, for 10 minutes.

Portal session only.

Portal session only; in a team, the owner or an admin. Slack sends the person back to the portal's Integrations page with installed=slack, or error= denied, expired, already_installed or failed. 503 slack_not_configured when Slack is not set up.

Response (JSON)
Field	Type	Notes
`url`	`string`	required

GET`/v1/apps/jira/install`

Atlassian's authorize page for the 50heads Jira app, with a signed state that works once, for 10 minutes.

Portal session only.

Portal session only; in a team, the owner or an admin. Atlassian sends the person back to the portal's Integrations page with installed=jira, or error= denied, expired, already_installed or failed. One Jira site per install. 503 jira_not_configured when the Atlassian app is not set up; 404 while the Jira app is off on this server.

Response (JSON)
Field	Type	Notes
`url`	`string`	required

GET`/v1/apps/linear/install`

Linear's authorize page for the 50heads Linear app, with a signed state that works once, for 10 minutes.

Portal session only.

Portal session only; in a team, the owner or an admin. Linear sends the person back to the portal's Integrations page with installed=linear, or error= denied, expired, already_installed or failed. 503 linear_not_configured when the Linear app is not set up; 404 while the Linear app is off on this server.

Response (JSON)
Field	Type	Notes
`url`	`string`	required

PATCH`/v1/apps/{appId}`

Change an app's daily cap, in credits.

API key or OAuth token with apps:write.

In a team, the owner or an admin. Asks over the cap are refused with spend_cap_reached.

Request body (JSON)
Field	Type	Notes
`capDailyPence`	`integer`	100–10000000

Response (JSON)
Field	Type	Notes
`app`	`object`	required
`app.id`	`string`	required
`app.provider`	`"slack" \| "teams" \| "jira" \| "linear"`	required
`app.workspaceId`	`string`	required
`app.workspaceName`	`string`	required
`app.defaultChannelName`	`string \| null`	required
`app.capDailyPence`	`integer`	required
`app.spentTodayPence`	`integer`	required
`app.installedAt`	`string`	required
`app.installedBy`	`object`	required
`app.installedBy.name`	`string \| null`	required
`app.installedBy.email`	`string \| null`	required
`app.status`	`"active" \| "revoked"`	required

DELETE`/v1/apps/{appId}`

Uninstall: revokes the workspace's token and the app's connection.

API key or OAuth token with apps:write.

Questions already asked keep running and are refunded as usual if they underfill; their results cards are not posted.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Event stream and warehouse export

Every event webhooks deliver, as a stream you page through: oldest first by `updatedAt`, with a cursor that never skips or repeats an event, so a scheduled job or an ELT tool (Airbyte, Fivetran, Hevo) reads only what is new. Read the account's stream with events:read; an organization admin reads every workspace's at /v1/organizations/current/events. Organizations can also have it, and their audit trail, written to their own S3, R2 or Google Cloud Storage bucket as JSON lines on a schedule, with a manifest per run (Organization settings, Warehouse export). Being introduced: 404 `not_found` until it is on for your account.

GET`/v1/events`

The account's events, oldest first by updatedAt, paged by a stable cursor.

API key or OAuth token with events:read.

A key acts for its own account; a session for the account in the account header. A personal account reads its own events (not its teams'); a team reads the team's. Keys made before scopes cannot read it (403 insufficient_scope). The page is oldest first by updatedAt, then sequence. nextCursor is always set: pass it back for the next page, or keep it and poll; an empty page still moves it on, so the next call reads only new events. Events are the webhook catalog's, with the same data; they are kept 90 days. Load by id to drop the rare repeat. Behind the warehouseExport flag: 404 not_found until it is on for your account.

Query parameters
Field	Type	Notes
`cursor`	`string`	up to 40 characters
`since`	`string`	up to 40 characters
`type`	`string`	up to 60 characters, pattern ^[a-z_]+(\.[a-z_]+)?$
`limit`	`integer`	1–500

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].type`	`string`	required
`events[].sequence`	`integer`	required
`events[].createdAt`	`string`	required
`events[].updatedAt`	`string`	required
`events[].workspaceId`	`string \| null`	required
`events[].data`	`map of object`	required
`nextCursor`	`string`	required
`hasMore`	`boolean`	required

GET`/v1/organizations/current/events`

Every workspace's events in the organization, oldest first by updatedAt, paged by a stable cursor.

API key or OAuth token with events:read.

Organization admins only (403 organization_admin_required); API keys, connected apps and service accounts with events:read where the organization has machine identities (otherwise 403 session_required). The page is oldest first by updatedAt, then sequence. nextCursor is always set: pass it back for the next page, or keep it and poll; an empty page still moves it on, so the next call reads only new events. Events are the webhook catalog's, with the same data; they are kept 90 days. Load by id to drop the rare repeat. Behind the warehouseExport flag: 404 not_found until it is on for your account.

Query parameters
Field	Type	Notes
`cursor`	`string`	up to 40 characters
`since`	`string`	up to 40 characters
`type`	`string`	up to 60 characters, pattern ^[a-z_]+(\.[a-z_]+)?$
`limit`	`integer`	1–500

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].type`	`string`	required
`events[].sequence`	`integer`	required
`events[].createdAt`	`string`	required
`events[].updatedAt`	`string`	required
`events[].workspaceId`	`string \| null`	required
`events[].data`	`map of object`	required
`nextCursor`	`string`	required
`hasMore`	`boolean`	required

GET`/v1/organizations/current/warehouse/destinations`

The organization's warehouse export destinations: buckets, schedules, state and how far each data set has been written.

API key or OAuth token with organization:read.

Organization admins, or a key, connected app or service account with organization:read. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Response (JSON)
Field	Type	Notes
`destinations`	`object[]`	required
`destinations[].id`	`string`	required
`destinations[].name`	`string`	required
`destinations[].provider`	`"s3" \| "r2" \| "gcs"`	required
`destinations[].bucket`	`string`	required
`destinations[].region`	`string \| null`	required
`destinations[].accountId`	`string \| null`	required
`destinations[].jurisdiction`	`"default" \| "eu" \| "fedramp" \| null`	required
`destinations[].prefix`	`string`	required
`destinations[].accessKeyHint`	`string`	required
`destinations[].datasets`	`"events" \| "audit"[]`	required
`destinations[].intervalMinutes`	`integer`	required
`destinations[].state`	`"active" \| "paused" \| "failing"`	required
`destinations[].consecutiveFailures`	`integer`	required
`destinations[].lastError`	`string \| null`	required
`destinations[].lastRunAt`	`string \| null`	required
`destinations[].lastSuccessAt`	`string \| null`	required
`destinations[].nextRunAt`	`string \| null`	required
`destinations[].exportedThrough`	`object`	required
`destinations[].exportedThrough.events`	`string \| null`	required
`destinations[].exportedThrough.audit`	`string \| null`	required
`destinations[].createdAt`	`string`	required
`destinations[].createdBy`	`object`	required
`destinations[].createdBy.id`	`string`	required
`destinations[].createdBy.name`	`string \| null`	required

GET`/v1/organizations/current/warehouse/destinations/{id}`

One destination.

API key or OAuth token with organization:read.

As the list. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Response (JSON)
Field	Type	Notes
`destination`	`object`	required
`destination.id`	`string`	required
`destination.name`	`string`	required
`destination.provider`	`"s3" \| "r2" \| "gcs"`	required
`destination.bucket`	`string`	required
`destination.region`	`string \| null`	required
`destination.accountId`	`string \| null`	required
`destination.jurisdiction`	`"default" \| "eu" \| "fedramp" \| null`	required
`destination.prefix`	`string`	required
`destination.accessKeyHint`	`string`	required
`destination.datasets`	`"events" \| "audit"[]`	required
`destination.intervalMinutes`	`integer`	required
`destination.state`	`"active" \| "paused" \| "failing"`	required
`destination.consecutiveFailures`	`integer`	required
`destination.lastError`	`string \| null`	required
`destination.lastRunAt`	`string \| null`	required
`destination.lastSuccessAt`	`string \| null`	required
`destination.nextRunAt`	`string \| null`	required
`destination.exportedThrough`	`object`	required
`destination.exportedThrough.events`	`string \| null`	required
`destination.exportedThrough.audit`	`string \| null`	required
`destination.createdAt`	`string`	required
`destination.createdBy`	`object`	required
`destination.createdBy.id`	`string`	required
`destination.createdBy.name`	`string \| null`	required

GET`/v1/organizations/current/warehouse/destinations/{id}/runs`

The destination's last 50 runs, newest first: rows and files written, the manifest, and the error of a run that failed.

API key or OAuth token with organization:read.

As the list. Runs are kept 90 days. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Response (JSON)
Field	Type	Notes
`runs`	`object[]`	required
`runs[].id`	`string`	required
`runs[].destinationId`	`string`	required
`runs[].trigger`	`"schedule" \| "manual"`	required
`runs[].status`	`"running" \| "succeeded" \| "failed"`	required
`runs[].startedAt`	`string`	required
`runs[].finishedAt`	`string \| null`	required
`runs[].rows`	`object`	required
`runs[].rows.events`	`integer`	required
`runs[].rows.audit`	`integer`	required
`runs[].bytes`	`integer`	required
`runs[].files`	`integer`	required
`runs[].manifestKey`	`string \| null`	required
`runs[].more`	`boolean`	required
`runs[].error`	`string \| null`	required

POST`/v1/organizations/current/warehouse/destinations`

Add a bucket: AWS S3 (with its region), Cloudflare R2 (with the account ID) or Google Cloud Storage (HMAC keys).

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. Saving writes a small test file under the prefix first; if the bucket refuses it nothing is saved (422 destination_unreachable, with the test in details.test). The keys need permission to put objects under the prefix and nothing else. The first run is within five minutes. Up to 5 destinations (409 too_many_destinations). Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 60 characters
`provider`	`"s3" \| "r2" \| "gcs"`	required
`bucket`	`string`	required pattern ^[a-z0-9][a-z0-9._-]{1,61}[a-z0-9]$
`region`	`string`	pattern ^[a-z]{2}(-[a-z]+)+-\d{1,2}$
`accountId`	`string`	pattern ^[a-f0-9]{32}$
`jurisdiction`	`"default" \| "eu" \| "fedramp"`
`prefix`	`string`	up to 200 characters, pattern ^(?:[A-Za-z0-9!_.*'()=-]+\/){0,8}$, default "50heads/"
`datasets`	`"events" \| "audit"[]`	up to 2 items, default ["events"]
`intervalMinutes`	`60 \| 360 \| 1440`	default 60
`accessKeyId`	`string`	required up to 128 characters, at least 4 characters, pattern ^[\x21-\x7e]+$
`secretAccessKey`	`string`	required up to 256 characters, at least 8 characters, pattern ^[\x21-\x7e]+$

Response (JSON)
Field	Type	Notes
`destination`	`object`	required
`destination.id`	`string`	required
`destination.name`	`string`	required
`destination.provider`	`"s3" \| "r2" \| "gcs"`	required
`destination.bucket`	`string`	required
`destination.region`	`string \| null`	required
`destination.accountId`	`string \| null`	required
`destination.jurisdiction`	`"default" \| "eu" \| "fedramp" \| null`	required
`destination.prefix`	`string`	required
`destination.accessKeyHint`	`string`	required
`destination.datasets`	`"events" \| "audit"[]`	required
`destination.intervalMinutes`	`integer`	required
`destination.state`	`"active" \| "paused" \| "failing"`	required
`destination.consecutiveFailures`	`integer`	required
`destination.lastError`	`string \| null`	required
`destination.lastRunAt`	`string \| null`	required
`destination.lastSuccessAt`	`string \| null`	required
`destination.nextRunAt`	`string \| null`	required
`destination.exportedThrough`	`object`	required
`destination.exportedThrough.events`	`string \| null`	required
`destination.exportedThrough.audit`	`string \| null`	required
`destination.createdAt`	`string`	required
`destination.createdBy`	`object`	required
`destination.createdBy.id`	`string`	required
`destination.createdBy.name`	`string \| null`	required
`test`	`object`	required
`test.ok`	`boolean`	required
`test.status`	`integer \| null`	required
`test.code`	`"access_denied" \| "no_such_bucket" \| "invalid_credentials" \| "wrong_region" \| "unreachable" \| "bucket_error" \| null`	required
`test.message`	`string`	required
`test.key`	`string`	required

PATCH`/v1/organizations/current/warehouse/destinations/{id}`

Rename, change the prefix, data sets or schedule, pause or resume, or replace the keys.

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. New keys or a new prefix are tested with a write first (422 destination_unreachable). Resuming a failing destination runs it within five minutes. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Request body (JSON)
Field	Type	Notes
`name`	`string`	up to 60 characters
`prefix`	`string`	up to 200 characters, pattern ^(?:[A-Za-z0-9!_.*'()=-]+\/){0,8}$
`datasets`	`"events" \| "audit"[]`	up to 2 items
`intervalMinutes`	`60 \| 360 \| 1440`
`paused`	`boolean`
`credentials`	`object`
`credentials.accessKeyId`	`string`	required up to 128 characters, at least 4 characters, pattern ^[\x21-\x7e]+$
`credentials.secretAccessKey`	`string`	required up to 256 characters, at least 8 characters, pattern ^[\x21-\x7e]+$

Response (JSON)
Field	Type	Notes
`destination`	`object`	required
`destination.id`	`string`	required
`destination.name`	`string`	required
`destination.provider`	`"s3" \| "r2" \| "gcs"`	required
`destination.bucket`	`string`	required
`destination.region`	`string \| null`	required
`destination.accountId`	`string \| null`	required
`destination.jurisdiction`	`"default" \| "eu" \| "fedramp" \| null`	required
`destination.prefix`	`string`	required
`destination.accessKeyHint`	`string`	required
`destination.datasets`	`"events" \| "audit"[]`	required
`destination.intervalMinutes`	`integer`	required
`destination.state`	`"active" \| "paused" \| "failing"`	required
`destination.consecutiveFailures`	`integer`	required
`destination.lastError`	`string \| null`	required
`destination.lastRunAt`	`string \| null`	required
`destination.lastSuccessAt`	`string \| null`	required
`destination.nextRunAt`	`string \| null`	required
`destination.exportedThrough`	`object`	required
`destination.exportedThrough.events`	`string \| null`	required
`destination.exportedThrough.audit`	`string \| null`	required
`destination.createdAt`	`string`	required
`destination.createdBy`	`object`	required
`destination.createdBy.id`	`string`	required
`destination.createdBy.name`	`string \| null`	required

DELETE`/v1/organizations/current/warehouse/destinations/{id}`

Stop exporting to a bucket and delete its keys. Files already written stay in the bucket.

Portal session only.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

POST`/v1/organizations/current/warehouse/destinations/{id}/test`

Test the connection: write a small file with the stored keys.

Portal session only.

Organization admins, signed in. Answers 200 whether or not the write worked; test.ok says which, with the bucket's error code. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Response (JSON)
Field	Type	Notes
`test`	`object`	required
`test.ok`	`boolean`	required
`test.status`	`integer \| null`	required
`test.code`	`"access_denied" \| "no_such_bucket" \| "invalid_credentials" \| "wrong_region" \| "unreachable" \| "bucket_error" \| null`	required
`test.message`	`string`	required
`test.key`	`string`	required

POST`/v1/organizations/current/warehouse/destinations/{id}/run`

Run an export now (within five minutes) instead of waiting for the schedule.

Portal session only.

Organization admins, signed in. A paused destination answers 409 destination_paused. Behind the warehouseExport flag (and the organizations flag): 404 not_found until it is on for your organization. Each run writes JSON lines under <prefix><dataset>/dt=<date>/<run>-<n>.jsonl and then a manifest at <prefix>manifests/<time>-<run>.json listing the files, their rows and SHA-256; load the files a manifest lists (a file with no manifest is from a run that failed and is written again). Parquet is not written. Keys are stored encrypted and never returned.

Response (JSON)
Field	Type	Notes
`destination`	`object`	required
`destination.id`	`string`	required
`destination.name`	`string`	required
`destination.provider`	`"s3" \| "r2" \| "gcs"`	required
`destination.bucket`	`string`	required
`destination.region`	`string \| null`	required
`destination.accountId`	`string \| null`	required
`destination.jurisdiction`	`"default" \| "eu" \| "fedramp" \| null`	required
`destination.prefix`	`string`	required
`destination.accessKeyHint`	`string`	required
`destination.datasets`	`"events" \| "audit"[]`	required
`destination.intervalMinutes`	`integer`	required
`destination.state`	`"active" \| "paused" \| "failing"`	required
`destination.consecutiveFailures`	`integer`	required
`destination.lastError`	`string \| null`	required
`destination.lastRunAt`	`string \| null`	required
`destination.lastSuccessAt`	`string \| null`	required
`destination.nextRunAt`	`string \| null`	required
`destination.exportedThrough`	`object`	required
`destination.exportedThrough.events`	`string \| null`	required
`destination.exportedThrough.audit`	`string \| null`	required
`destination.createdAt`	`string`	required
`destination.createdBy`	`object`	required
`destination.createdBy.id`	`string`	required
`destination.createdBy.name`	`string \| null`	required

Spend approvals

An organization can ask that some asks wait for a person: over an amount per ask, day or month, at a tier, with images, or always. An ask a policy holds comes back as 202 `approval_required` with its credits held and nothing sent to heads; an approver decides in the 50heads app or at 50heads.com, and the agent reads the outcome here (or waits on the question). Being introduced: 404 `not_found` until it is on for your organization.

GET`/v1/approvals`

Approvals for the signed-in person: waiting for them (`inbox`), decided (`history`) or the whole workspace's (`workspace`, for owners, admins and billing).

Portal session only.

A person, in the app or at 50heads.com. pendingForYou is the badge on the Answer tab. An empty list while approvals are off.

Query parameters
Field	Type	Notes
`view`	`"inbox" \| "history" \| "workspace"`
`state`	`"pending" \| "approved" \| "denied" \| "expired" \| "canceled"`
`limit`	`integer`	1–100
`cursor`	`string`

Response (JSON)
Field	Type	Notes
`approvals`	`object[]`	required
`approvals[].id`	`string`	required
`approvals[].state`	`"pending" \| "approved" \| "denied" \| "expired" \| "canceled"`	required
`approvals[].organizationId`	`string`	required
`approvals[].organizationName`	`string`	required
`approvals[].workspaceId`	`string`	required
`approvals[].workspaceName`	`string`	required
`approvals[].questionId`	`string`	required
`approvals[].question`	`object`	required
`approvals[].question.text`	`string`	required
`approvals[].question.type`	`string`	required
`approvals[].question.options`	`object[]`	required
`approvals[].question.context`	`string \| null`	required
`approvals[].amountPence`	`integer`	required
`approvals[].heads`	`integer`	required
`approvals[].tier`	`integer`	required
`approvals[].etaMinutes`	`integer \| null`	required
`approvals[].reasons`	`"per_ask" \| "per_day" \| "per_month" \| "tier" \| "images" \| "always"[]`	required
`approvals[].requester`	`object`	required
`approvals[].requester.kind`	`"key" \| "app" \| "service_account" \| "person"`	required
`approvals[].requester.name`	`string`	required
`approvals[].requester.keyTail`	`string \| null`	required
`approvals[].projectId`	`string \| null`	required
`approvals[].projectName`	`string \| null`	required
`approvals[].quorum`	`1 \| 2`	required
`approvals[].approvedCount`	`integer`	required
`approvals[].approverRoles`	`"owner" \| "admin" \| "billing"[]`	required
`approvals[].approverCount`	`integer`	required
`approvals[].votes`	`object[]`	required
`approvals[].votes[].userId`	`string \| null`	required
`approvals[].votes[].name`	`string \| null`	required
`approvals[].votes[].role`	`string`	required
`approvals[].votes[].decision`	`"approve" \| "deny"`	required
`approvals[].votes[].reason`	`string \| null`	required
`approvals[].votes[].channel`	`"app" \| "web"`	required
`approvals[].votes[].at`	`string`	required
`approvals[].expiresAt`	`string`	required
`approvals[].createdAt`	`string`	required
`approvals[].decidedAt`	`string \| null`	required
`approvals[].canDecide`	`boolean`	required
`approvals[].blocked`	`"own_ask" \| "not_approver" \| "already_voted" \| "decided" \| "expired" \| null`	required
`approvals[].heldPence`	`integer`	required
`approvals[].confirmRequired`	`boolean`	required
`approvals[].approveUrl`	`string`	required
`pendingForYou`	`integer`	required
`nextCursor`	`string \| null`	required
`stats`	`object \| null`
`stats.decided`	`integer`	required
`stats.approved`	`integer`	required
`stats.denied`	`integer`	required
`stats.expired`	`integer`	required
`stats.approvedPence`	`integer`	required
`stats.releasedPence`	`integer`	required
`stats.medianMinutes`	`number \| null`	required
`stats.slowestMinutes`	`number \| null`	required
`stats.monthlyLimitPence`	`integer \| null`	required
`enabled`	`boolean`

GET`/v1/approvals/{id}`

What an agent can read about its own approval: the state and, once decided, the approver's role and typed reason.

API key or OAuth token with questions:read.

Poll this (the 202 says how often), or wait on the question. Denied: code: refused_by_policy with the approver's reason and role (owner, admin or billing), never their name. Nobody decided in time: code: approval_expired. Only the account that asked, or a person who can see the approval, can read it; anyone else gets 404.

Response (JSON)
Field	Type	Notes
`approvalId`	`string`	required
`questionId`	`string`	required
`status`	`"pending" \| "approved" \| "denied" \| "expired" \| "canceled"`	required
`amountPence`	`integer`	required
`approveUrl`	`string`	required
`expiresAt`	`string`	required
`quorum`	`1 \| 2`	required
`approvedCount`	`integer`	required
`code`	`"refused_by_policy" \| "approval_expired" \| null`	required
`decision`	`object \| null`	required
`decision.outcome`	`"approved" \| "denied" \| "expired" \| "canceled"`	required
`decision.reason`	`string \| null`	required
`decision.decidedByRole`	`string \| null`	required
`decision.decidedAt`	`string`	required

GET`/v1/approvals/{id}/review`

The approver's view of one approval: the question, the amount, who asked, who has decided. Opening it is written to the audit trail.

Portal session only.

A person who can see the approval; anyone else gets 404.

Response (JSON)
Field	Type	Notes
`approval`	`object`	required
`approval.id`	`string`	required
`approval.state`	`"pending" \| "approved" \| "denied" \| "expired" \| "canceled"`	required
`approval.organizationId`	`string`	required
`approval.organizationName`	`string`	required
`approval.workspaceId`	`string`	required
`approval.workspaceName`	`string`	required
`approval.questionId`	`string`	required
`approval.question`	`object`	required
`approval.question.text`	`string`	required
`approval.question.type`	`string`	required
`approval.question.options`	`object[]`	required
`approval.question.context`	`string \| null`	required
`approval.amountPence`	`integer`	required
`approval.heads`	`integer`	required
`approval.tier`	`integer`	required
`approval.etaMinutes`	`integer \| null`	required
`approval.reasons`	`"per_ask" \| "per_day" \| "per_month" \| "tier" \| "images" \| "always"[]`	required
`approval.requester`	`object`	required
`approval.requester.kind`	`"key" \| "app" \| "service_account" \| "person"`	required
`approval.requester.name`	`string`	required
`approval.requester.keyTail`	`string \| null`	required
`approval.projectId`	`string \| null`	required
`approval.projectName`	`string \| null`	required
`approval.quorum`	`1 \| 2`	required
`approval.approvedCount`	`integer`	required
`approval.approverRoles`	`"owner" \| "admin" \| "billing"[]`	required
`approval.approverCount`	`integer`	required
`approval.votes`	`object[]`	required
`approval.votes[].userId`	`string \| null`	required
`approval.votes[].name`	`string \| null`	required
`approval.votes[].role`	`string`	required
`approval.votes[].decision`	`"approve" \| "deny"`	required
`approval.votes[].reason`	`string \| null`	required
`approval.votes[].channel`	`"app" \| "web"`	required
`approval.votes[].at`	`string`	required
`approval.expiresAt`	`string`	required
`approval.createdAt`	`string`	required
`approval.decidedAt`	`string \| null`	required
`approval.canDecide`	`boolean`	required
`approval.blocked`	`"own_ask" \| "not_approver" \| "already_voted" \| "decided" \| "expired" \| null`	required
`approval.heldPence`	`integer`	required
`approval.confirmRequired`	`boolean`	required
`approval.approveUrl`	`string`	required

POST`/v1/approvals/{id}/confirm`

The app: Face ID or the passcode succeeded on the phone. Returns a one-use confirmation and opens a five-minute window.

Portal session only.

App sessions only. Every decision over £100.00 needs its own confirmation (confirmationId); smaller ones are covered by a confirm in the last five minutes.

Request body (JSON)
Field	Type	Notes
`method`	`"biometric" \| "passcode"`	required

Response (JSON)
Field	Type	Notes
`confirmationId`	`string`	required
`expiresAt`	`string`	required
`windowEndsAt`	`string`	required

POST`/v1/approvals/{id}/decision`

Approve or deny. Needs a person: never an API key, a connected app or a service account.

Portal session only.

An approver on a browser session with a fresh proof in x-50h-reauth (spent by the decision), or in the app with a confirmationId. The typed reason goes to the agent and the audit trail. 403 separation_of_duties when the approver's own key made the ask (unless the policy allows it under an amount), 403 not_an_approver, 403 confirm_required (the app has not confirmed it is them, or the confirmation was used or is too old), 409 approval_decided or approval_expired. Approving the last approval a policy needs makes the question live; denying releases the held credits.

Request body (JSON)
Field	Type	Notes
`decision`	`"approve" \| "deny"`	required
`reason`	`string`	up to 200 characters
`confirmationId`	`string`	up to 100 characters

Response (JSON)
Field	Type	Notes
`approval`	`object`	required
`approval.id`	`string`	required
`approval.state`	`"pending" \| "approved" \| "denied" \| "expired" \| "canceled"`	required
`approval.organizationId`	`string`	required
`approval.organizationName`	`string`	required
`approval.workspaceId`	`string`	required
`approval.workspaceName`	`string`	required
`approval.questionId`	`string`	required
`approval.question`	`object`	required
`approval.question.text`	`string`	required
`approval.question.type`	`string`	required
`approval.question.options`	`object[]`	required
`approval.question.context`	`string \| null`	required
`approval.amountPence`	`integer`	required
`approval.heads`	`integer`	required
`approval.tier`	`integer`	required
`approval.etaMinutes`	`integer \| null`	required
`approval.reasons`	`"per_ask" \| "per_day" \| "per_month" \| "tier" \| "images" \| "always"[]`	required
`approval.requester`	`object`	required
`approval.requester.kind`	`"key" \| "app" \| "service_account" \| "person"`	required
`approval.requester.name`	`string`	required
`approval.requester.keyTail`	`string \| null`	required
`approval.projectId`	`string \| null`	required
`approval.projectName`	`string \| null`	required
`approval.quorum`	`1 \| 2`	required
`approval.approvedCount`	`integer`	required
`approval.approverRoles`	`"owner" \| "admin" \| "billing"[]`	required
`approval.approverCount`	`integer`	required
`approval.votes`	`object[]`	required
`approval.votes[].userId`	`string \| null`	required
`approval.votes[].name`	`string \| null`	required
`approval.votes[].role`	`string`	required
`approval.votes[].decision`	`"approve" \| "deny"`	required
`approval.votes[].reason`	`string \| null`	required
`approval.votes[].channel`	`"app" \| "web"`	required
`approval.votes[].at`	`string`	required
`approval.expiresAt`	`string`	required
`approval.createdAt`	`string`	required
`approval.decidedAt`	`string \| null`	required
`approval.canDecide`	`boolean`	required
`approval.blocked`	`"own_ask" \| "not_approver" \| "already_voted" \| "decided" \| "expired" \| null`	required
`approval.heldPence`	`integer`	required
`approval.confirmRequired`	`boolean`	required
`approval.approveUrl`	`string`	required
`outcome`	`"approved" \| "denied" \| "recorded"`	required

GET`/v1/approvals/notifications`

The person's own push, email, quiet hours and daily digest settings for approvals.

Portal session only.

Response (JSON)
Field	Type	Notes
`settings`	`object`	required
`settings.push`	`boolean`	required
`settings.email`	`boolean`	required
`settings.quietFrom`	`integer \| null`	required
`settings.quietTo`	`integer \| null`	required
`settings.digest`	`boolean`	required
`settings.digestHour`	`integer`	required 0–23
`settings.timezone`	`string \| null`	required

PUT`/v1/approvals/notifications`

Change them. Quiet hours are both set or both null.

Portal session only.

Request body (JSON)
Field	Type	Notes
`push`	`boolean`
`email`	`boolean`
`quietFrom`	`integer \| null`
`quietTo`	`integer \| null`
`digest`	`boolean`
`digestHour`	`integer`	0–23
`timezone`	`string \| null`

Response (JSON)
Field	Type	Notes
`settings`	`object`	required
`settings.push`	`boolean`	required
`settings.email`	`boolean`	required
`settings.quietFrom`	`integer \| null`	required
`settings.quietTo`	`integer \| null`	required
`settings.digest`	`boolean`	required
`settings.digestHour`	`integer`	required 0–23
`settings.timezone`	`string \| null`	required

GET`/v1/approvals/policies`

The organization's approval policies, and the workspaces, projects, keys and people they can name.

Portal session only.

Organization admins only (403 organization_admin_required).

Response (JSON)
Field	Type	Notes
`policies`	`object[]`	required
`policies[].id`	`string`	required
`policies[].organizationId`	`string`	required
`policies[].scope`	`"organization" \| "workspace" \| "project" \| "key"`	required
`policies[].scopeId`	`string \| null`	required
`policies[].scopeName`	`string \| null`	required
`policies[].enabled`	`boolean`	required
`policies[].always`	`boolean`	required
`policies[].perAskPence`	`integer \| null`	required
`policies[].perDayPence`	`integer \| null`	required
`policies[].perMonthPence`	`integer \| null`	required
`policies[].requireForTiers`	`integer[]`	required
`policies[].requireForImages`	`boolean`	required
`policies[].approvers`	`object`	required
`policies[].approvers.roles`	`"owner" \| "admin" \| "billing"[]`	required
`policies[].approvers.people`	`object[]`	required
`policies[].quorum`	`1 \| 2`	required
`policies[].expiresInMinutes`	`integer`	required
`policies[].onExpiry`	`"deny"`	required
`policies[].allowSelfApprovalUnderPence`	`integer \| null`	required
`policies[].notify`	`"app" \| "email"[]`	required
`policies[].createdAt`	`string`	required
`policies[].updatedAt`	`string \| null`	required
`targets`	`object`	required
`targets.workspaces`	`object[]`	required
`targets.workspaces[].id`	`string`	required
`targets.workspaces[].name`	`string`	required
`targets.projects`	`object[]`	required
`targets.projects[].id`	`string`	required
`targets.projects[].name`	`string`	required
`targets.projects[].workspaceId`	`string \| null`	required
`targets.keys`	`object[]`	required
`targets.keys[].id`	`string`	required
`targets.keys[].name`	`string`	required
`targets.keys[].workspaceId`	`string \| null`	required
`targets.people`	`object[]`	required
`targets.people[].userId`	`string`	required
`targets.people[].name`	`string \| null`	required
`targets.people[].email`	`string \| null`	required

POST`/v1/approvals/policies`

Make a policy for the organization, a workspace, a project or a key. One per scope; the narrowest wins.

Portal session only.

Request body (JSON)
Field	Type	Notes
`enabled`	`boolean`	default true
`always`	`boolean`	default false
`perAskPence`	`integer \| null`	default null
`perDayPence`	`integer \| null`	default null
`perMonthPence`	`integer \| null`	default null
`requireForTiers`	`integer[]`	up to 3 items, default []
`requireForImages`	`boolean`	default false
`approvers`	`object`	default {"roles":["owner","admin"],"people":[]}
`approvers.roles`	`"owner" \| "admin" \| "billing"[]`	up to 3 items, default ["owner","admin"]
`approvers.people`	`string[]`	up to 25 items, default []
`quorum`	`1 \| 2`	default 1
`expiresInMinutes`	`integer`	5–1440, default 60
`onExpiry`	`"deny"`	default "deny"
`allowSelfApprovalUnderPence`	`integer \| null`	default null
`notify`	`"app" \| "email"[]`	up to 2 items, default ["app","email"]
`scope`	`"organization" \| "workspace" \| "project" \| "key"`	required
`scopeId`	`string \| null`	default null

Response (JSON)
Field	Type	Notes
`policy`	`object`	required
`policy.id`	`string`	required
`policy.organizationId`	`string`	required
`policy.scope`	`"organization" \| "workspace" \| "project" \| "key"`	required
`policy.scopeId`	`string \| null`	required
`policy.scopeName`	`string \| null`	required
`policy.enabled`	`boolean`	required
`policy.always`	`boolean`	required
`policy.perAskPence`	`integer \| null`	required
`policy.perDayPence`	`integer \| null`	required
`policy.perMonthPence`	`integer \| null`	required
`policy.requireForTiers`	`integer[]`	required
`policy.requireForImages`	`boolean`	required
`policy.approvers`	`object`	required
`policy.approvers.roles`	`"owner" \| "admin" \| "billing"[]`	required
`policy.approvers.people`	`object[]`	required
`policy.quorum`	`1 \| 2`	required
`policy.expiresInMinutes`	`integer`	required
`policy.onExpiry`	`"deny"`	required
`policy.allowSelfApprovalUnderPence`	`integer \| null`	required
`policy.notify`	`"app" \| "email"[]`	required
`policy.createdAt`	`string`	required
`policy.updatedAt`	`string \| null`	required

PATCH`/v1/approvals/policies/{id}`

Change a policy. Only what you send changes; asks already waiting keep the approvers and quorum they were held with.

Portal session only.

Request body (JSON)
Field	Type	Notes
`enabled`	`boolean`
`always`	`boolean`
`perAskPence`	`integer \| null`
`perDayPence`	`integer \| null`
`perMonthPence`	`integer \| null`
`requireForTiers`	`integer[]`	up to 3 items
`requireForImages`	`boolean`
`approvers`	`object`
`approvers.roles`	`"owner" \| "admin" \| "billing"[]`	up to 3 items
`approvers.people`	`string[]`	up to 25 items
`quorum`	`1 \| 2`
`expiresInMinutes`	`integer`	5–1440
`allowSelfApprovalUnderPence`	`integer \| null`
`notify`	`"app" \| "email"[]`	up to 2 items

Response (JSON)
Field	Type	Notes
`policy`	`object`	required
`policy.id`	`string`	required
`policy.organizationId`	`string`	required
`policy.scope`	`"organization" \| "workspace" \| "project" \| "key"`	required
`policy.scopeId`	`string \| null`	required
`policy.scopeName`	`string \| null`	required
`policy.enabled`	`boolean`	required
`policy.always`	`boolean`	required
`policy.perAskPence`	`integer \| null`	required
`policy.perDayPence`	`integer \| null`	required
`policy.perMonthPence`	`integer \| null`	required
`policy.requireForTiers`	`integer[]`	required
`policy.requireForImages`	`boolean`	required
`policy.approvers`	`object`	required
`policy.approvers.roles`	`"owner" \| "admin" \| "billing"[]`	required
`policy.approvers.people`	`object[]`	required
`policy.quorum`	`1 \| 2`	required
`policy.expiresInMinutes`	`integer`	required
`policy.onExpiry`	`"deny"`	required
`policy.allowSelfApprovalUnderPence`	`integer \| null`	required
`policy.notify`	`"app" \| "email"[]`	required
`policy.createdAt`	`string`	required
`policy.updatedAt`	`string \| null`	required

DELETE`/v1/approvals/policies/{id}`

Delete a policy. Asks already waiting are decided as before.

Portal session only.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

Organizations

Being introduced for teams that ask for it. An organization holds a team's workspaces, proves the email domains it owns with a DNS record, and sets rules for people on those domains. Signed in at 50heads.com, changes need an organization admin (an owner or admin of one of its workspaces) who has just confirmed it is them. Where the organization has machine identities, API keys and connected apps of an organization admin, and the organization's service accounts, can use the routes marked with a scope (organization:read, organization:write, members:read, members:write, audit:read); the rest stay with a person.

GET`/v1/organizations/current`

The organization of the team account in use, with your role in it.

API key or OAuth token with organization:read.

The organization of the team named in the account header. A personal account has none: 404 not_in_organization. Any member of its workspaces can read this; role says whether you are an admin.

Response (JSON)
Field	Type	Notes
`organization`	`object`	required
`organization.id`	`string`	required
`organization.name`	`string`	required
`organization.createdAt`	`string`	required
`organization.role`	`"admin" \| "member"`	required
`organization.defaultWorkspaceId`	`string \| null`	required
`organization.workspaces`	`object[]`	required
`organization.workspaces[].id`	`string`	required
`organization.workspaces[].name`	`string`	required
`organization.workspaces[].costCenter`	`string \| null`
`organization.workspaces[].closed`	`boolean`
`organization.flags`	`map of object`	required
`organization.policies`	`object`	required
`organization.policies.autoJoin`	`boolean`	required
`organization.policies.claimWithNotice`	`boolean`	required
`organization.policies.restrictPersonalSignup`	`boolean`	required
`organization.policies.noticeDays`	`integer`	required 7–90
`organization.verifiedDomains`	`string[]`	required
`organization.sso`	`object \| null`
`organization.sso.state`	`"draft" \| "tested" \| "enabled"`	required
`organization.sso.enforce`	`boolean`	required
`organization.scim`	`object`
`organization.scim.active`	`boolean`	required
`organization.securityPolicies`	`object`
`organization.securityPolicies.requireTwoStep`	`boolean`	required
`organization.securityPolicies.maxSessionAgeMinutes`	`integer \| null`	required
`organization.securityPolicies.idleTimeoutMinutes`	`integer \| null`	required
`organization.securityPolicies.reauthWindowMinutes`	`integer \| null`	required
`organization.machineIdentities`	`boolean`
`organization.warehouseExport`	`boolean`

PATCH`/v1/organizations/current`

Rename the organization. Its workspaces keep their names.

API key or OAuth token with organization:write.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 80 characters

Response (JSON)
Field	Type	Notes
`organization`	`object`	required
`organization.id`	`string`	required
`organization.name`	`string`	required
`organization.createdAt`	`string`	required
`organization.role`	`"admin" \| "member"`	required
`organization.defaultWorkspaceId`	`string \| null`	required
`organization.workspaces`	`object[]`	required
`organization.workspaces[].id`	`string`	required
`organization.workspaces[].name`	`string`	required
`organization.workspaces[].costCenter`	`string \| null`
`organization.workspaces[].closed`	`boolean`
`organization.flags`	`map of object`	required
`organization.policies`	`object`	required
`organization.policies.autoJoin`	`boolean`	required
`organization.policies.claimWithNotice`	`boolean`	required
`organization.policies.restrictPersonalSignup`	`boolean`	required
`organization.policies.noticeDays`	`integer`	required 7–90
`organization.verifiedDomains`	`string[]`	required
`organization.sso`	`object \| null`
`organization.sso.state`	`"draft" \| "tested" \| "enabled"`	required
`organization.sso.enforce`	`boolean`	required
`organization.scim`	`object`
`organization.scim.active`	`boolean`	required
`organization.securityPolicies`	`object`
`organization.securityPolicies.requireTwoStep`	`boolean`	required
`organization.securityPolicies.maxSessionAgeMinutes`	`integer \| null`	required
`organization.securityPolicies.idleTimeoutMinutes`	`integer \| null`	required
`organization.securityPolicies.reauthWindowMinutes`	`integer \| null`	required
`organization.machineIdentities`	`boolean`
`organization.warehouseExport`	`boolean`

GET`/v1/organizations/current/domains`

The organization's domains, each with the TXT record that proves it.

API key or OAuth token with organization:read.

Organization admins only. Removed domains are not listed.

Response (JSON)
Field	Type	Notes
`domains`	`object[]`	required
`domains[].id`	`string`	required
`domains[].domain`	`string`	required
`domains[].state`	`"pending" \| "verified" \| "warning" \| "failed" \| "revoked"`	required
`domains[].challenge`	`object`	required
`domains[].challenge.recordName`	`string`	required
`domains[].challenge.recordType`	`"TXT"`	required
`domains[].challenge.value`	`string`	required
`domains[].createdAt`	`string`	required
`domains[].verifiedAt`	`string \| null`	required
`domains[].checkedAt`	`string \| null`	required
`domains[].lastError`	`string \| null`	required
`domains[].warningSince`	`string \| null`	required
`domains[].graceEndsAt`	`string \| null`	required

POST`/v1/organizations/current/domains`

Add a domain to prove. It starts as pending, with its TXT record.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). The exact domain only: example.com covers addresses @example.com, not @mail.example.com and never @evil-example.com. Public suffixes (co.uk), free email providers and disposable email domains are refused with domain_not_allowed. Up to 20 domains.

Request body (JSON)
Field	Type	Notes
`domain`	`string`	required up to 253 characters, at least 3 characters

Response (JSON)
Field	Type	Notes
`domain`	`object`	required
`domain.id`	`string`	required
`domain.domain`	`string`	required
`domain.state`	`"pending" \| "verified" \| "warning" \| "failed" \| "revoked"`	required
`domain.challenge`	`object`	required
`domain.challenge.recordName`	`string`	required
`domain.challenge.recordType`	`"TXT"`	required
`domain.challenge.value`	`string`	required
`domain.createdAt`	`string`	required
`domain.verifiedAt`	`string \| null`	required
`domain.checkedAt`	`string \| null`	required
`domain.lastError`	`string \| null`	required
`domain.warningSince`	`string \| null`	required
`domain.graceEndsAt`	`string \| null`	required

POST`/v1/organizations/current/domains/{domainId}/verify`

Look the TXT record up now and verify the domain if it is there.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). outcome says what the lookup found: verified, already_verified, record_missing, value_mismatch, lookup_failed (try again later) or held_elsewhere (another organization has verified it). Only one organization can hold a domain. Verified domains are checked again daily; a missing record moves the domain to warning and emails the admins, and after 7 days to failed, when its policies stop applying.

Response (JSON)
Field	Type	Notes
`outcome`	`"verified" \| "already_verified" \| "record_missing" \| "value_mismatch" \| "lookup_failed" \| "held_elsewhere"`	required
`domain`	`object`	required
`domain.id`	`string`	required
`domain.domain`	`string`	required
`domain.state`	`"pending" \| "verified" \| "warning" \| "failed" \| "revoked"`	required
`domain.challenge`	`object`	required
`domain.challenge.recordName`	`string`	required
`domain.challenge.recordType`	`"TXT"`	required
`domain.challenge.value`	`string`	required
`domain.createdAt`	`string`	required
`domain.verifiedAt`	`string \| null`	required
`domain.checkedAt`	`string \| null`	required
`domain.lastError`	`string \| null`	required
`domain.warningSince`	`string \| null`	required
`domain.graceEndsAt`	`string \| null`	required

DELETE`/v1/organizations/current/domains/{domainId}`

Remove a domain. Its policies stop applying at once.

API key or OAuth token with organization:write.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

GET`/v1/organizations/current/policies`

The rules for people on the organization's verified domains. All off by default.

API key or OAuth token with organization:read.

Organization admins only.

Response (JSON)
Field	Type	Notes
`policies`	`object`	required
`policies.autoJoin`	`boolean`	required
`policies.claimWithNotice`	`boolean`	required
`policies.restrictPersonalSignup`	`boolean`	required
`policies.noticeDays`	`integer`	required 7–90

PATCH`/v1/organizations/current/policies`

Turn a policy on or off.

API key or OAuth token with organization:write.

Request body (JSON)
Field	Type	Notes
`autoJoin`	`boolean`
`claimWithNotice`	`boolean`
`restrictPersonalSignup`	`boolean`
`noticeDays`	`integer`	7–90

Response (JSON)
Field	Type	Notes
`policies`	`object`	required
`policies.autoJoin`	`boolean`	required
`policies.claimWithNotice`	`boolean`	required
`policies.restrictPersonalSignup`	`boolean`	required
`policies.noticeDays`	`integer`	required 7–90

GET`/v1/organizations/current/audit`

Who did what in the organization, newest first.

API key or OAuth token with audit:read.

Organization admins only. Read-only: entries cannot be changed or deleted. 50 a page.

Query parameters
Field	Type	Notes
`cursor`	`string`

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].at`	`string`	required
`events[].actor`	`object`	required
`events[].actor.id`	`string \| null`	required
`events[].actor.name`	`string \| null`	required
`events[].action`	"organization.created" \| "organization.renamed" \| "domain.added" \| "domain.removed" \| "domain.verified" \| "domain.check_failed" \| "domain.warning" \| "domain.restored" \| "domain.failed" \| "policy.changed" \| "member.joined" \| "sso.configured" \| "sso.updated" \| "sso.test_started" \| "sso.tested" \| "sso.enabled" \| "sso.disabled" \| "sso.enforced" \| "sso.unenforced" \| "sso.enforcement_suspended" \| "sso.linked" \| "sso.unlinked" \| "break_glass.added" \| "break_glass.removed" \| "break_glass.used" \| "scim.token_created" \| "scim.token_rotated" \| "scim.token_revoked" \| "scim.settings_changed" \| "scim.mapping_created" \| "scim.mapping_changed" \| "scim.mapping_removed" \| "group.created" \| "group.renamed" \| "group.members_changed" \| "group.deleted" \| "member.provisioned" \| "member.linked" \| "member.updated" \| "member.role_changed" \| "member.removed" \| "member.deprovisioned" \| "member.reactivated" \| "member.deleted" \| "member.sessions_revoked" \| "member.credentials_revoked" \| "member.webhooks_stopped" \| "deprovision.failing" \| "workspace.owner_changed" \| "sso.sessions_ended" \| "service_account.created" \| "service_account.updated" \| "service_account.disabled" \| "service_account.enabled" \| "service_account.deleted" \| "service_account.secret_rotated" \| "service_account.secret_revoked" \| "service_account.keys_changed" \| "approval.requested" \| "approval.viewed" \| "approval.reauthenticated" \| "approval.decided" \| "approval.refused" \| "approval.expired" \| "approval.canceled" \| "approval.policy_changed" \| "workspace.created" \| "workspace.renamed" \| "workspace.cost_center_changed" \| "workspace.closed" \| "workspace.move_requested" \| "workspace.move_canceled" \| "workspace.move_declined" \| "workspace.moved_in" \| "workspace.moved_out" \| "organization.default_workspace_changed" \| "organization.closed" \| "invitation.resent" \| "invitation.revoked" \| "warehouse.destination_created" \| "warehouse.destination_updated" \| "warehouse.destination_deleted" \| "warehouse.export_failing" \| "warehouse.export_recovered"	required
`events[].subject`	`string`	required
`events[].data`	`map of object`	required
`nextCursor`	`string \| null`	required

GET`/v1/organizations/current/audit/events`

Every audit event of the organization and its workspaces, newest first, with filters.

API key or OAuth token with audit:read.

Organization admins only (403 organization_admin_required). API keys, connected apps and service accounts with audit:read can read and export where the organization has machine identities (otherwise 403 session_required); retention and legal holds change only with a person. Events come from the organization's log and its workspaces' logs and never hold secrets, codes or anything that identifies a head. Being introduced: 404 not_found until it is on for your organization. Ordered by at, then id; page with nextCursor (no gaps or repeats when events are written between pages).

Query parameters
Field	Type	Notes
`cursor`	`string`	up to 200 characters
`from`	`string`	up to 40 characters
`to`	`string`	up to 40 characters
`actor`	`string`	up to 100 characters
`action`	`string`	up to 60 characters
`workspace`	`string`	up to 64 characters
`limit`	`integer`	1–200

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].at`	`string`	required
`events[].organizationId`	`string`	required
`events[].workspaceId`	`string \| null`	required
`events[].source`	`"organization" \| "workspace"`	required
`events[].actor`	`object`	required
`events[].actor.type`	`"person" \| "system" \| "api_key" \| "oauth" \| "scim" \| "service_account"`	required
`events[].actor.id`	`string \| null`	required
`events[].actor.name`	`string \| null`	required
`events[].action`	"organization.created" \| "organization.renamed" \| "domain.added" \| "domain.removed" \| "domain.verified" \| "domain.check_failed" \| "domain.warning" \| "domain.restored" \| "domain.failed" \| "policy.changed" \| "member.joined" \| "sso.configured" \| "sso.updated" \| "sso.test_started" \| "sso.tested" \| "sso.enabled" \| "sso.disabled" \| "sso.enforced" \| "sso.unenforced" \| "sso.enforcement_suspended" \| "sso.linked" \| "sso.unlinked" \| "break_glass.added" \| "break_glass.removed" \| "break_glass.used" \| "scim.token_created" \| "scim.token_rotated" \| "scim.token_revoked" \| "scim.settings_changed" \| "scim.mapping_created" \| "scim.mapping_changed" \| "scim.mapping_removed" \| "group.created" \| "group.renamed" \| "group.members_changed" \| "group.deleted" \| "member.provisioned" \| "member.linked" \| "member.updated" \| "member.role_changed" \| "member.removed" \| "member.deprovisioned" \| "member.reactivated" \| "member.deleted" \| "member.sessions_revoked" \| "member.credentials_revoked" \| "member.webhooks_stopped" \| "deprovision.failing" \| "workspace.owner_changed" \| "sso.sessions_ended" \| "service_account.created" \| "service_account.updated" \| "service_account.disabled" \| "service_account.enabled" \| "service_account.deleted" \| "service_account.secret_rotated" \| "service_account.secret_revoked" \| "service_account.keys_changed" \| "approval.requested" \| "approval.viewed" \| "approval.reauthenticated" \| "approval.decided" \| "approval.refused" \| "approval.expired" \| "approval.canceled" \| "approval.policy_changed" \| "workspace.created" \| "workspace.renamed" \| "workspace.cost_center_changed" \| "workspace.closed" \| "workspace.move_requested" \| "workspace.move_canceled" \| "workspace.move_declined" \| "workspace.moved_in" \| "workspace.moved_out" \| "organization.default_workspace_changed" \| "organization.closed" \| "invitation.resent" \| "invitation.revoked" \| "warehouse.destination_created" \| "warehouse.destination_updated" \| "warehouse.destination_deleted" \| "warehouse.export_failing" \| "warehouse.export_recovered" \| "question.asked" \| "question.canceled" \| "credits.purchased" \| "key.created" \| "key.revoked" \| "key.updated" \| "member.invited" \| "member.cap_changed" \| "connection.created" \| "connection.revoked" \| "connection.cap_changed" \| "team.created" \| "team.moved" \| "team.closed" \| "team.cost_center_changed" \| "project.cost_center_changed" \| "member.invite_resent" \| "member.invite_revoked" \| "member.invite_declined" \| "credits.refunded" \| "credits.adjusted" \| "credits.invoice_terms_changed" \| "audit.retention_changed" \| "audit.retention_applied" \| "audit.hold_created" \| "audit.hold_released" \| "audit.exported"	required
`events[].subject`	`string`	required
`events[].data`	`map of object`	required
`events[].ip`	`string \| null`	required
`nextCursor`	`string \| null`	required

GET`/v1/organizations/current/audit/export.jsonl`

The audit trail as JSON lines (application/x-ndjson), oldest first, streamed.

API key or OAuth token with audit:read.

Organization admins only (403 organization_admin_required). API keys, connected apps and service accounts with audit:read can read and export where the organization has machine identities (otherwise 403 session_required); retention and legal holds change only with a person. Events come from the organization's log and its workspaces' logs and never hold secrets, codes or anything that identifies a head. Being introduced: 404 not_found until it is on for your organization. One AuditEvent per line, newline-terminated. Events written after the export starts are left for the next one. Up to 1,000,000 events per request: to resume, pass cursor as the last line's <at>|<id>. Each export is itself recorded (audit.exported).

Query parameters
Field	Type	Notes
`cursor`	`string`	up to 200 characters
`from`	`string`	up to 40 characters
`to`	`string`	up to 40 characters
`actor`	`string`	up to 100 characters
`action`	`string`	up to 60 characters
`workspace`	`string`	up to 64 characters

GET`/v1/organizations/current/audit/export.csv`

The audit trail as CSV, oldest first, streamed.

API key or OAuth token with audit:read.

Organization admins only (403 organization_admin_required). API keys, connected apps and service accounts with audit:read can read and export where the organization has machine identities (otherwise 403 session_required); retention and legal holds change only with a person. Events come from the organization's log and its workspaces' logs and never hold secrets, codes or anything that identifies a head. Being introduced: 404 not_found until it is on for your organization. Columns: id, at, organization_id, workspace_id, source, actor_type, actor_id, actor_name, action, subject, data (JSON), ip. RFC 4180 with CRLF; a cell starting with =, +, - or @ is prefixed with a single quote so spreadsheets do not run it. Same limits and resuming as the JSONL export.

Query parameters
Field	Type	Notes
`cursor`	`string`	up to 200 characters
`from`	`string`	up to 40 characters
`to`	`string`	up to 40 characters
`actor`	`string`	up to 100 characters
`action`	`string`	up to 60 characters
`workspace`	`string`	up to 64 characters

GET`/v1/organizations/current/audit/retention`

How long the organization's audit events are kept.

API key or OAuth token with audit:read.

Organization admins only (403 organization_admin_required). API keys, connected apps and service accounts with audit:read can read and export where the organization has machine identities (otherwise 403 session_required); retention and legal holds change only with a person. Events come from the organization's log and its workspaces' logs and never hold secrets, codes or anything that identifies a head. Being introduced: 404 not_found until it is on for your organization. Six years until an admin sets a period; never less than one year.

Response (JSON)
Field	Type	Notes
`retention`	`object`	required
`retention.days`	`integer`	required
`retention.isDefault`	`boolean`	required
`retention.floorDays`	`integer`	required
`retention.defaultDays`	`integer`	required
`retention.maxDays`	`integer`	required
`retention.setBy`	`object \| null`	required
`retention.setBy.id`	`string`	required
`retention.setBy.name`	`string \| null`	required
`retention.setAt`	`string \| null`	required

PUT`/v1/organizations/current/audit/retention`

Set how long audit events are kept (365 to 3,650 days).

Portal session only.

Request body (JSON)
Field	Type	Notes
`days`	`integer`	required 365–3650

Response (JSON)
Field	Type	Notes
`retention`	`object`	required
`retention.days`	`integer`	required
`retention.isDefault`	`boolean`	required
`retention.floorDays`	`integer`	required
`retention.defaultDays`	`integer`	required
`retention.maxDays`	`integer`	required
`retention.setBy`	`object \| null`	required
`retention.setBy.id`	`string`	required
`retention.setBy.name`	`string \| null`	required
`retention.setAt`	`string \| null`	required

GET`/v1/organizations/current/audit/holds`

Legal holds: open ones first, then released ones.

API key or OAuth token with audit:read.

Response (JSON)
Field	Type	Notes
`holds`	`object[]`	required
`holds[].id`	`string`	required
`holds[].scope`	`object`	required
`holds[].scope.all`	`boolean`	required
`holds[].scope.workspaceIds`	`string[]`	required
`holds[].scope.actorIds`	`string[]`	required
`holds[].reason`	`string`	required
`holds[].active`	`boolean`	required
`holds[].createdBy`	`object`	required
`holds[].createdBy.id`	`string`	required
`holds[].createdBy.name`	`string \| null`	required
`holds[].createdAt`	`string`	required
`holds[].releasedBy`	`object \| null`	required
`holds[].releasedBy.id`	`string`	required
`holds[].releasedBy.name`	`string \| null`	required
`holds[].releasedAt`	`string \| null`	required

POST`/v1/organizations/current/audit/holds`

Stop audit events being deleted: everything, or named workspaces or people.

Portal session only.

Request body (JSON)
Field	Type	Notes
`reason`	`string`	required up to 500 characters
`scope`	`object`	required
`scope.all`	`boolean`	default false
`scope.workspaceIds`	`string[]`	up to 50 items, default []
`scope.actorIds`	`string[]`	up to 50 items, default []

Response (JSON)
Field	Type	Notes
`hold`	`object`	required
`hold.id`	`string`	required
`hold.scope`	`object`	required
`hold.scope.all`	`boolean`	required
`hold.scope.workspaceIds`	`string[]`	required
`hold.scope.actorIds`	`string[]`	required
`hold.reason`	`string`	required
`hold.active`	`boolean`	required
`hold.createdBy`	`object`	required
`hold.createdBy.id`	`string`	required
`hold.createdBy.name`	`string \| null`	required
`hold.createdAt`	`string`	required
`hold.releasedBy`	`object \| null`	required
`hold.releasedBy.id`	`string`	required
`hold.releasedBy.name`	`string \| null`	required
`hold.releasedAt`	`string \| null`	required

POST`/v1/organizations/current/audit/holds/{holdId}/release`

Release a legal hold. Deletion under the retention period resumes at the next daily run.

Portal session only.

Response (JSON)
Field	Type	Notes
`hold`	`object`	required
`hold.id`	`string`	required
`hold.scope`	`object`	required
`hold.scope.all`	`boolean`	required
`hold.scope.workspaceIds`	`string[]`	required
`hold.scope.actorIds`	`string[]`	required
`hold.reason`	`string`	required
`hold.active`	`boolean`	required
`hold.createdBy`	`object`	required
`hold.createdBy.id`	`string`	required
`hold.createdBy.name`	`string \| null`	required
`hold.createdAt`	`string`	required
`hold.releasedBy`	`object \| null`	required
`hold.releasedBy.id`	`string`	required
`hold.releasedBy.name`	`string \| null`	required
`hold.releasedAt`	`string \| null`	required

GET`/v1/organizations/joinable`

Organizations you may join because your verified email is on one of their domains.

Portal session only.

Only organizations with auto-join on, and only for an email address a sign-in has proved.

Response (JSON)
Field	Type	Notes
`organizations`	`object[]`	required
`organizations[].id`	`string`	required
`organizations[].name`	`string`	required
`organizations[].domain`	`string`	required
`organizations[].workspaceId`	`string`	required
`organizations[].workspaceName`	`string`	required
`organizations[].role`	`"viewer"`	required

POST`/v1/organizations/join`

Join an organization's default workspace as a viewer.

Portal session only.

Your personal account and its credits stay as they are. 403 not_joinable when the organization does not list you.

Request body (JSON)
Field	Type	Notes
`organizationId`	`string`	required up to 64 characters

Response (JSON)
Field	Type	Notes
`organizationId`	`string`	required
`workspaceId`	`string`	required
`role`	`"viewer"`	required

GET`/v1/organizations/current/security-policies`

Sign-in rules for everyone in the organization's workspaces. All off by default.

API key or OAuth token with organization:read.

Organization admins only.

Response (JSON)
Field	Type	Notes
`policies`	`object`	required
`policies.requireTwoStep`	`boolean`	required
`policies.maxSessionAgeMinutes`	`integer \| null`	required
`policies.idleTimeoutMinutes`	`integer \| null`	required
`policies.reauthWindowMinutes`	`integer \| null`	required

PATCH`/v1/organizations/current/security-policies`

Require two-step sign-in, limit session age and idle time, shorten the re-authentication window.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). Policies apply to new and existing sessions: a session older than a new maximum ends on its next request (401 session_ended), and an OAuth refresh older than it answers invalid_grant. With two-step required, sensitive actions answer 403 two_step_required until the person adds two-step sign-in or a passkey; adding one is never blocked. Sends a policy.changed event.

Request body (JSON)
Field	Type	Notes
`requireTwoStep`	`boolean`
`maxSessionAgeMinutes`	`integer \| null`
`idleTimeoutMinutes`	`integer \| null`
`reauthWindowMinutes`	`integer \| null`

Response (JSON)
Field	Type	Notes
`policies`	`object`	required
`policies.requireTwoStep`	`boolean`	required
`policies.maxSessionAgeMinutes`	`integer \| null`	required
`policies.idleTimeoutMinutes`	`integer \| null`	required
`policies.reauthWindowMinutes`	`integer \| null`	required

GET`/v1/organizations/requirements`

What your organizations ask of you: two-step sign-in, session limits.

Portal session only.

Read after sign-in. With twoStep.required and not enrolled, set up two-step sign-in or a passkey first.

Response (JSON)
Field	Type	Notes
`requirements`	`object`	required
`requirements.twoStep`	`object`	required
`requirements.twoStep.required`	`boolean`	required
`requirements.twoStep.enrolled`	`boolean`	required
`requirements.twoStep.organizationIds`	`string[]`	required
`requirements.maxSessionAgeMinutes`	`integer \| null`	required
`requirements.idleTimeoutMinutes`	`integer \| null`	required
`requirements.reauthWindowMinutes`	`integer \| null`	required

GET`/v1/organizations/current/people`

Everyone in the organization, across every team.

Portal session only.

Organization admins only (403 organization_admin_required). Active members of any of its teams, and people its identity provider provisioned (still listed when SCIM turned them off). Each with their teams and roles, SCIM or not, single sign-on linked or not, last sign-in and live sessions; no IP addresses. Ordered by email; q matches part of a name or address; page with nextCursor.

Query parameters
Field	Type	Notes
`q`	`string`	up to 100 characters
`cursor`	`string`	up to 400 characters
`limit`	`integer`	1–200

Response (JSON)
Field	Type	Notes
`people`	`object[]`	required
`people[].userId`	`string`	required
`people[].name`	`string \| null`	required
`people[].email`	`string`	required
`people[].teams`	`object[]`	required
`people[].teams[].workspaceId`	`string`	required
`people[].teams[].workspaceName`	`string`	required
`people[].teams[].role`	`"owner" \| "admin" \| "member" \| "viewer" \| "billing"`	required
`people[].teams[].scimManaged`	`boolean`	required
`people[].scim`	`object \| null`	required
`people[].scim.active`	`boolean`	required
`people[].ssoLinked`	`boolean`	required
`people[].lastSignInAt`	`string \| null`	required
`people[].activeSessions`	`integer`	required
`nextCursor`	`string \| null`	required

GET`/v1/organizations/current/members/{userId}/sessions`

A member's live sessions, on the web and in the app.

API key or OAuth token with members:read.

Organization admins only. No IP addresses. 404 for someone not in the organization.

Response (JSON)
Field	Type	Notes
`userId`	`string`	required
`sessions`	`object[]`	required
`sessions[].id`	`string`	required
`sessions[].kind`	`"web" \| "app"`	required
`sessions[].label`	`string`	required
`sessions[].country`	`string \| null`	required
`sessions[].authMethod`	`"email" \| "apple" \| "google" \| "passkey" \| "sso" \| "break_glass" \| null`	required
`sessions[].createdAt`	`string`	required
`sessions[].lastSeenAt`	`string \| null`	required

DELETE`/v1/organizations/current/members/{userId}/sessions`

Sign a member out everywhere.

API key or OAuth token with members:write.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required
`revoked`	`integer`	required

POST`/v1/organizations/current/workspaces/{workspaceId}/owner`

Hand a workspace to another of its members.

Portal session only.

Request body (JSON)
Field	Type	Notes
`userId`	`string`	required up to 64 characters

Response (JSON)
Field	Type	Notes
`workspaceId`	`string`	required
`ownerId`	`string`	required
`previousOwnerId`	`string`	required

GET`/v1/organizations`

The organizations you are in, with the workspaces you are in and your role.

API key or OAuth token with organization:read.

Signed in: every organization the flag serves where you are an active member of a workspace; role is admin when you own or administer one of its open workspaces. With an API key, a connected app or a service account: only the organization of the workspace it works in.

Response (JSON)
Field	Type	Notes
`organizations`	`object[]`	required
`organizations[].id`	`string`	required
`organizations[].name`	`string`	required
`organizations[].role`	`"admin" \| "member"`	required
`organizations[].defaultWorkspaceId`	`string \| null`	required
`organizations[].workspaces`	`object[]`	required
`organizations[].workspaces[].id`	`string`	required
`organizations[].workspaces[].name`	`string`	required
`organizations[].workspaces[].role`	`"owner" \| "admin" \| "member" \| "viewer" \| "billing"`	required
`organizations[].workspaces[].closed`	`boolean`	required

GET`/v1/organizations/current/workspaces`

Every workspace of the organization: owner, members, pending invitations, cost center.

API key or OAuth token with organization:read.

Organization admins only. Closed workspaces are listed last, with closedAt; they are read-only.

Response (JSON)
Field	Type	Notes
`workspaces`	`object[]`	required
`workspaces[].id`	`string`	required
`workspaces[].name`	`string`	required
`workspaces[].ownerId`	`string`	required
`workspaces[].ownerName`	`string \| null`	required
`workspaces[].ownerEmail`	`string \| null`	required
`workspaces[].members`	`integer`	required
`workspaces[].pendingInvitations`	`integer`	required
`workspaces[].costCenter`	`string \| null`	required
`workspaces[].isDefault`	`boolean`	required
`workspaces[].createdAt`	`string`	required
`workspaces[].closedAt`	`string \| null`	required

POST`/v1/organizations/current/workspaces`

Make a workspace in the organization.

Portal session only.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 80 characters
`ownerId`	`string`	up to 64 characters
`costCenter`	`string \| null`

Response (JSON)
Field	Type	Notes
`workspace`	`object`	required
`workspace.id`	`string`	required
`workspace.name`	`string`	required
`workspace.ownerId`	`string`	required
`workspace.ownerName`	`string \| null`	required
`workspace.ownerEmail`	`string \| null`	required
`workspace.members`	`integer`	required
`workspace.pendingInvitations`	`integer`	required
`workspace.costCenter`	`string \| null`	required
`workspace.isDefault`	`boolean`	required
`workspace.createdAt`	`string`	required
`workspace.closedAt`	`string \| null`	required

PATCH`/v1/organizations/current/workspaces/{workspaceId}`

Rename a workspace, or set its cost center label.

Portal session only.

Request body (JSON)
Field	Type	Notes
`name`	`string`	up to 80 characters
`costCenter`	`string \| null`

Response (JSON)
Field	Type	Notes
`workspace`	`object`	required
`workspace.id`	`string`	required
`workspace.name`	`string`	required
`workspace.ownerId`	`string`	required
`workspace.ownerName`	`string \| null`	required
`workspace.ownerEmail`	`string \| null`	required
`workspace.members`	`integer`	required
`workspace.pendingInvitations`	`integer`	required
`workspace.costCenter`	`string \| null`	required
`workspace.isDefault`	`boolean`	required
`workspace.createdAt`	`string`	required
`workspace.closedAt`	`string \| null`	required

PUT`/v1/organizations/current/default-workspace`

Choose the organization's main workspace.

Portal session only.

Request body (JSON)
Field	Type	Notes
`workspaceId`	`string`	required up to 64 characters

Response (JSON)
Field	Type	Notes
`defaultWorkspaceId`	`string`	required

GET`/v1/organizations/current/moves`

Requests to move teams into the organization.

API key or OAuth token with organization:read.

Organization admins only. Newest first. A pending request past expiresAt reads as expired.

Response (JSON)
Field	Type	Notes
`moves`	`object[]`	required
`moves[].id`	`string`	required
`moves[].workspaceId`	`string`	required
`moves[].workspaceName`	`string`	required
`moves[].fromOrganizationId`	`string`	required
`moves[].toOrganizationId`	`string`	required
`moves[].toOrganizationName`	`string`	required
`moves[].requestedBy`	`object`	required
`moves[].requestedBy.id`	`string`	required
`moves[].requestedBy.name`	`string \| null`	required
`moves[].status`	`"pending" \| "accepted" \| "declined" \| "canceled" \| "expired"`	required
`moves[].createdAt`	`string`	required
`moves[].expiresAt`	`string`	required
`moves[].decidedAt`	`string \| null`	required

POST`/v1/organizations/current/moves`

Ask a team's owner to move the team into the organization.

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. The team's owner reads its id on their Team page. Refused when the team's organization has other open workspaces (409 source_has_other_workspaces), holds a verified domain, single sign-on or SCIM (409 source_has_identity), when its owner already owns a workspace here (409 owns_workspace_in_organization), when asks wait for a spend approval (409 pending_approvals), or a request is already open (409 move_exists). The owner is emailed and has 14 days to accept, with a fresh re-authentication, on their Team page. When they do, the team keeps its members, credits, questions and history, and its old organization is closed with its audit kept.

Request body (JSON)
Field	Type	Notes
`workspaceId`	`string`	required up to 64 characters

Response (JSON)
Field	Type	Notes
`move`	`object`	required
`move.id`	`string`	required
`move.workspaceId`	`string`	required
`move.workspaceName`	`string`	required
`move.fromOrganizationId`	`string`	required
`move.toOrganizationId`	`string`	required
`move.toOrganizationName`	`string`	required
`move.requestedBy`	`object`	required
`move.requestedBy.id`	`string`	required
`move.requestedBy.name`	`string \| null`	required
`move.status`	`"pending" \| "accepted" \| "declined" \| "canceled" \| "expired"`	required
`move.createdAt`	`string`	required
`move.expiresAt`	`string`	required
`move.decidedAt`	`string \| null`	required

DELETE`/v1/organizations/current/moves/{id}`

Withdraw a request to move a team in.

Portal session only.

Response (JSON)
Field	Type	Notes
`move`	`object`	required
`move.id`	`string`	required
`move.workspaceId`	`string`	required
`move.workspaceName`	`string`	required
`move.fromOrganizationId`	`string`	required
`move.toOrganizationId`	`string`	required
`move.toOrganizationName`	`string`	required
`move.requestedBy`	`object`	required
`move.requestedBy.id`	`string`	required
`move.requestedBy.name`	`string \| null`	required
`move.status`	`"pending" \| "accepted" \| "declined" \| "canceled" \| "expired"`	required
`move.createdAt`	`string`	required
`move.expiresAt`	`string`	required
`move.decidedAt`	`string \| null`	required

GET`/v1/organizations/current/invitations`

Invitations not yet accepted, in every workspace of the organization.

API key or OAuth token with members:read.

Organization admins only. Newest first; expired invitations stay listed until they are resent or revoked.

Response (JSON)
Field	Type	Notes
`invitations`	`object[]`	required
`invitations[].id`	`string`	required
`invitations[].email`	`string`	required
`invitations[].role`	`"owner" \| "admin" \| "member" \| "viewer" \| "billing"`	required
`invitations[].workspaceId`	`string`	required
`invitations[].workspaceName`	`string`	required
`invitations[].invitedBy`	`object \| null`	required
`invitations[].invitedBy.id`	`string`	required
`invitations[].invitedBy.name`	`string \| null`	required
`invitations[].invitedAt`	`string`	required
`invitations[].expiresAt`	`string \| null`	required
`invitations[].expired`	`boolean`	required

POST`/v1/organizations/current/invitations/{id}/resend`

Send an invitation again, with a new link and seven more days.

Portal session only.

Response (JSON)
Field	Type	Notes
`invitation`	`object`	required
`invitation.id`	`string`	required
`invitation.email`	`string`	required
`invitation.role`	`"owner" \| "admin" \| "member" \| "viewer" \| "billing"`	required
`invitation.workspaceId`	`string`	required
`invitation.workspaceName`	`string`	required
`invitation.invitedBy`	`object \| null`	required
`invitation.invitedBy.id`	`string`	required
`invitation.invitedBy.name`	`string \| null`	required
`invitation.invitedAt`	`string`	required
`invitation.expiresAt`	`string \| null`	required
`invitation.expired`	`boolean`	required

DELETE`/v1/organizations/current/invitations/{id}`

Revoke an invitation.

Portal session only.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

DELETE`/v1/organizations/current/people/{userId}`

Take someone out of every workspace of the organization.

Portal session only.

Response (JSON)
Field	Type	Notes
`userId`	`string`	required
`workspacesLeft`	`string[]`	required

PUT`/v1/organizations/current/people/{userId}/role`

Change someone's role in one workspace of the organization.

Portal session only.

Request body (JSON)
Field	Type	Notes
`workspaceId`	`string`	required up to 64 characters
`role`	`"admin" \| "member" \| "viewer" \| "billing"`	required

Response (JSON)
Field	Type	Notes
`userId`	`string`	required
`workspaceId`	`string`	required
`role`	`string`	required

GET`/v1/organizations/current/spend`

Spend by cost center for a month.

API key or OAuth token with organization:read.

Organization admins only. Credits the workspaces' questions took in the month (UTC), less what came back, by workspace and cost center: a project's label wins over its workspace's; questions with neither have costCenter null.

Query parameters
Field	Type	Notes
`month`	`string`	pattern ^\d{4}-(0[1-9]\|1[0-2])$

Response (JSON)
Field	Type	Notes
`month`	`string`	required
`totalSpentPence`	`integer`	required
`totalQuestions`	`integer`	required
`rows`	`object[]`	required
`rows[].costCenter`	`string \| null`	required
`rows[].workspaceId`	`string`	required
`rows[].workspaceName`	`string`	required
`rows[].questions`	`integer`	required
`rows[].spentPence`	`integer`	required

GET`/v1/organizations/current/spend.csv`

Spend by cost center as CSV.

API key or OAuth token with organization:read.

Organization admins only. Columns: month, cost_center, workspace_id, workspace_name, questions, spent_credits. RFC 4180 with CRLF; formula cells are quoted.

Query parameters
Field	Type	Notes
`month`	`string`	pattern ^\d{4}-(0[1-9]\|1[0-2])$

GET`/v1/organizations/current/scim`

SCIM provisioning: the base URL, the default role and counts.

API key or OAuth token with organization:read.

Organization admins only. Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Response (JSON)
Field	Type	Notes
`settings`	`object`	required
`settings.baseUrl`	`string`	required
`settings.defaultRole`	`"admin" \| "member" \| "viewer" \| "billing"`	required
`settings.defaultWorkspaceId`	`string \| null`	required
`settings.provisionedUsers`	`integer`	required
`settings.activeUsers`	`integer`	required
`settings.groups`	`integer`	required

PATCH`/v1/organizations/current/scim`

Set the role a provisioned person gets when none of their groups is mapped.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Request body (JSON)
Field	Type	Notes
`defaultRole`	`"admin" \| "member" \| "viewer" \| "billing"`	required

Response (JSON)
Field	Type	Notes
`defaultRole`	`"admin" \| "member" \| "viewer" \| "billing"`	required

GET`/v1/organizations/current/scim/tokens`

The SCIM tokens that work now (never the tokens themselves).

API key or OAuth token with organization:read.

Response (JSON)
Field	Type	Notes
`tokens`	`object[]`	required
`tokens[].id`	`string`	required
`tokens[].label`	`string`	required
`tokens[].prefix`	`string`	required
`tokens[].createdAt`	`string`	required
`tokens[].createdBy`	`string \| null`	required
`tokens[].expiresAt`	`string \| null`	required
`tokens[].lastUsedAt`	`string \| null`	required

POST`/v1/organizations/current/scim/tokens`

Make a SCIM token for the identity provider. It is shown once.

Portal session only.

Request body (JSON)
Field	Type	Notes
`label`	`string`	up to 60 characters, default "Identity provider"

Response (JSON)
Field	Type	Notes
`token`	`object`	required
`token.id`	`string`	required
`token.label`	`string`	required
`token.prefix`	`string`	required
`token.createdAt`	`string`	required
`token.createdBy`	`string \| null`	required
`token.expiresAt`	`string \| null`	required
`token.lastUsedAt`	`string \| null`	required
`secret`	`string`	required
`baseUrl`	`string`	required

POST`/v1/organizations/current/scim/tokens/{tokenId}/rotate`

Replace a SCIM token; the old one keeps working for the overlap.

Portal session only.

Request body (JSON)
Field	Type	Notes
`overlapHours`	`integer`	0–168, default 24

Response (JSON)
Field	Type	Notes
`token`	`object`	required
`token.id`	`string`	required
`token.label`	`string`	required
`token.prefix`	`string`	required
`token.createdAt`	`string`	required
`token.createdBy`	`string \| null`	required
`token.expiresAt`	`string \| null`	required
`token.lastUsedAt`	`string \| null`	required
`secret`	`string`	required
`baseUrl`	`string`	required

DELETE`/v1/organizations/current/scim/tokens/{tokenId}`

End a SCIM token at once.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

GET`/v1/organizations/current/scim/groups`

The groups the identity provider has pushed.

API key or OAuth token with organization:read.

Response (JSON)
Field	Type	Notes
`groups`	`object[]`	required
`groups[].id`	`string`	required
`groups[].displayName`	`string`	required
`groups[].externalId`	`string \| null`	required
`groups[].members`	`integer`	required
`groups[].createdAt`	`string`	required
`groups[].updatedAt`	`string`	required

GET`/v1/organizations/current/scim/mappings`

Which group gives which role in which workspace.

API key or OAuth token with organization:read.

Organization admins only. A person in several mapped groups gets the highest role in each workspace (admin, member, billing, viewer); a person in no mapped group gets the default role in the default workspace. Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Response (JSON)
Field	Type	Notes
`mappings`	`object[]`	required
`mappings[].id`	`string`	required
`mappings[].groupId`	`string`	required
`mappings[].groupName`	`string`	required
`mappings[].workspaceId`	`string`	required
`mappings[].workspaceName`	`string`	required
`mappings[].role`	`"admin" \| "member" \| "viewer" \| "billing"`	required
`mappings[].createdAt`	`string`	required
`mappings[].updatedAt`	`string`	required

POST`/v1/organizations/current/scim/mappings`

Give a group's members a role in a workspace.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). The group's members get the role at once. 409 mapping_exists. Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Request body (JSON)
Field	Type	Notes
`groupId`	`string`	required up to 64 characters
`workspaceId`	`string`	required up to 64 characters
`role`	`"admin" \| "member" \| "viewer" \| "billing"`	required

Response (JSON)
Field	Type	Notes
`mapping`	`object`	required
`mapping.id`	`string`	required
`mapping.groupId`	`string`	required
`mapping.groupName`	`string`	required
`mapping.workspaceId`	`string`	required
`mapping.workspaceName`	`string`	required
`mapping.role`	`"admin" \| "member" \| "viewer" \| "billing"`	required
`mapping.createdAt`	`string`	required
`mapping.updatedAt`	`string`	required

PATCH`/v1/organizations/current/scim/mappings/{mappingId}`

Change the role a group gives.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Request body (JSON)
Field	Type	Notes
`role`	`"admin" \| "member" \| "viewer" \| "billing"`	required

Response (JSON)
Field	Type	Notes
`mapping`	`object`	required
`mapping.id`	`string`	required
`mapping.groupId`	`string`	required
`mapping.groupName`	`string`	required
`mapping.workspaceId`	`string`	required
`mapping.workspaceName`	`string`	required
`mapping.role`	`"admin" \| "member" \| "viewer" \| "billing"`	required
`mapping.createdAt`	`string`	required
`mapping.updatedAt`	`string`	required

DELETE`/v1/organizations/current/scim/mappings/{mappingId}`

Stop a group giving a role. Its members lose the role at once.

API key or OAuth token with organization:write.

Organization admins only (403 organization_admin_required). Signed in, with a fresh proof in the x-50h-reauth header (401 reauth_required); with an API key, a connected app or a service account, with the scope named here and no proof, where the organization has machine identities (otherwise 403 session_required). The key's or app's person must be an organization admin. Every change is written to the organization's audit, with who made it (a person, a key, an app or a service account). Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

GET`/v1/organizations/current/scim/log`

The last SCIM requests and what came of each.

API key or OAuth token with organization:read.

Organization admins only. No request bodies and no tokens. Kept 90 days. Behind the scim sub-flag: 404 not_found while it is off. The SCIM protocol itself is at /scim/v2 for the identity provider (Okta, Microsoft Entra ID), with the token as its bearer; see the SCIM setup guide.

Query parameters
Field	Type	Notes
`limit`	`integer`	1–500

Response (JSON)
Field	Type	Notes
`entries`	`object[]`	required
`entries[].id`	`string`	required
`entries[].at`	`string`	required
`entries[].method`	`string`	required
`entries[].path`	`string`	required
`entries[].status`	`integer`	required
`entries[].outcome`	`string`	required
`entries[].scimType`	`string \| null`	required
`entries[].resourceId`	`string \| null`	required
`entries[].tokenId`	`string \| null`	required

GET`/v1/organizations/current/sso`

The organization's single sign-on connection, the OIDC redirect URI, and the SAML values (entity ID, ACS URL, metadata URL) to give your identity provider.

API key or OAuth token with organization:read.

Organization admins only. connection is null until one is saved. The client secret is never returned. connection.protocol is oidc or saml; for SAML, connection.saml has the identity provider's entity ID, single sign-on URL, metadata URL and certificates (fingerprints and expiry, never the certificate itself). saml is this organization's service provider values whatever the protocol in use.

Response (JSON)
Field	Type	Notes
`connection`	`object \| null`	required
`connection.id`	`string`	required
`connection.protocol`	`"oidc" \| "saml"`	required
`connection.issuer`	`string`	required
`connection.clientId`	`string`	required
`connection.clientSecretSet`	`boolean`	required
`connection.clientSecretHint`	`string \| null`	required
`connection.tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post"`	required
`connection.defaultWorkspaceId`	`string \| null`	required
`connection.defaultRole`	`"admin" \| "member" \| "viewer"`	required
`connection.state`	`"draft" \| "tested" \| "enabled"`	required
`connection.enforce`	`boolean`	required
`connection.enforceEnabledAt`	`string \| null`	required
`connection.configChangedAt`	`string`	required
`connection.lastTest`	`object \| null`	required
`connection.lastTest.at`	`string`	required
`connection.lastTest.by`	`object`	required
`connection.lastTest.result`	`string`	required
`connection.lastTest.matchedTester`	`boolean`	required
`connection.lastTest.current`	`boolean`	required
`connection.lastSignInAt`	`string \| null`	required
`connection.createdAt`	`string`	required
`connection.updatedAt`	`string \| null`	required
`connection.saml`	`object \| null`	required
`connection.saml.idpEntityId`	`string`	required
`connection.saml.ssoUrl`	`string`	required
`connection.saml.metadataUrl`	`string \| null`	required
`connection.saml.certificates`	`object[]`	required
`connection.saml.allowIdpInitiated`	`boolean`	required
`redirectUri`	`string`	required
`scopes`	`string[]`	required
`saml`	`object`	required
`saml.entityId`	`string`	required
`saml.acsUrl`	`string`	required
`saml.metadataUrl`	`string`	required
`saml.nameIdFormat`	`string`	required

PUT`/v1/organizations/current/sso`

Save the connection: OpenID Connect (issuer, client id and secret, token method) or SAML 2.0 (the identity provider's metadata), and where new people join.

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. 201 the first time. OIDC (protocol left out or oidc): the issuer's discovery document is read before saving (400 sso_discovery_failed); the secret is required the first time and kept when left out. SAML (protocol: "saml"): metadataUrl (read now, https on a public host, 6-second timeout, no redirects) or metadataXml, one of them; metadata that cannot be read, wants signed requests or has no HTTP-Redirect single sign-on URL is 400 saml_metadata_invalid; allowIdpInitiated (default false) accepts sign-ins started at the identity provider. A provider change (OIDC issuer, client id, secret or token method; SAML entity ID, single sign-on URL or certificates replaced; or a switch of protocol) needs a new test before people can sign in, and is refused while enforcement is on (409 sso_enforced). defaultRole is admin, member or viewer, never owner.

Response (JSON)
Field	Type	Notes
`connection`	`object \| null`	required
`connection.id`	`string`	required
`connection.protocol`	`"oidc" \| "saml"`	required
`connection.issuer`	`string`	required
`connection.clientId`	`string`	required
`connection.clientSecretSet`	`boolean`	required
`connection.clientSecretHint`	`string \| null`	required
`connection.tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post"`	required
`connection.defaultWorkspaceId`	`string \| null`	required
`connection.defaultRole`	`"admin" \| "member" \| "viewer"`	required
`connection.state`	`"draft" \| "tested" \| "enabled"`	required
`connection.enforce`	`boolean`	required
`connection.enforceEnabledAt`	`string \| null`	required
`connection.configChangedAt`	`string`	required
`connection.lastTest`	`object \| null`	required
`connection.lastTest.at`	`string`	required
`connection.lastTest.by`	`object`	required
`connection.lastTest.result`	`string`	required
`connection.lastTest.matchedTester`	`boolean`	required
`connection.lastTest.current`	`boolean`	required
`connection.lastSignInAt`	`string \| null`	required
`connection.createdAt`	`string`	required
`connection.updatedAt`	`string \| null`	required
`connection.saml`	`object \| null`	required
`connection.saml.idpEntityId`	`string`	required
`connection.saml.ssoUrl`	`string`	required
`connection.saml.metadataUrl`	`string \| null`	required
`connection.saml.certificates`	`object[]`	required
`connection.saml.allowIdpInitiated`	`boolean`	required
`redirectUri`	`string`	required
`scopes`	`string[]`	required
`saml`	`object`	required
`saml.entityId`	`string`	required
`saml.acsUrl`	`string`	required
`saml.metadataUrl`	`string`	required
`saml.nameIdFormat`	`string`	required

PATCH`/v1/organizations/current/sso`

Change part of the connection, or turn single sign-on on or off with `enabled`.

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. Turning it on needs a successful test sign-in since the last provider change (409 sso_test_required) and a verified domain. Turning it off is refused while enforcement is on. OIDC fields on a SAML connection, or SAML fields on an OIDC one, are 400 protocol_mismatch. SAML certificate rotation: new metadata with keepPreviousCertificate: true keeps the certificate in use beside the new one (at most two, 409 too_many_certificates), and removeCertificate (a fingerprint) drops one later (409 last_certificate for the only one); neither needs a new test or turning enforcement off.

Request body (JSON)
Field	Type	Notes
`issuer`	`string`	up to 300 characters, at least 8 characters
`clientId`	`string`	up to 300 characters
`clientSecret`	`string`	up to 1000 characters
`tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post"`
`defaultWorkspaceId`	`string \| null`
`defaultRole`	`"admin" \| "member" \| "viewer"`
`enabled`	`boolean`
`metadataUrl`	`string`	up to 1000 characters, at least 8 characters
`metadataXml`	`string`	up to 200000 characters, at least 20 characters
`keepPreviousCertificate`	`boolean`
`removeCertificate`	`string`	pattern ^[0-9a-f]{64}$
`allowIdpInitiated`	`boolean`

Response (JSON)
Field	Type	Notes
`connection`	`object \| null`	required
`connection.id`	`string`	required
`connection.protocol`	`"oidc" \| "saml"`	required
`connection.issuer`	`string`	required
`connection.clientId`	`string`	required
`connection.clientSecretSet`	`boolean`	required
`connection.clientSecretHint`	`string \| null`	required
`connection.tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post"`	required
`connection.defaultWorkspaceId`	`string \| null`	required
`connection.defaultRole`	`"admin" \| "member" \| "viewer"`	required
`connection.state`	`"draft" \| "tested" \| "enabled"`	required
`connection.enforce`	`boolean`	required
`connection.enforceEnabledAt`	`string \| null`	required
`connection.configChangedAt`	`string`	required
`connection.lastTest`	`object \| null`	required
`connection.lastTest.at`	`string`	required
`connection.lastTest.by`	`object`	required
`connection.lastTest.result`	`string`	required
`connection.lastTest.matchedTester`	`boolean`	required
`connection.lastTest.current`	`boolean`	required
`connection.lastSignInAt`	`string \| null`	required
`connection.createdAt`	`string`	required
`connection.updatedAt`	`string \| null`	required
`connection.saml`	`object \| null`	required
`connection.saml.idpEntityId`	`string`	required
`connection.saml.ssoUrl`	`string`	required
`connection.saml.metadataUrl`	`string \| null`	required
`connection.saml.certificates`	`object[]`	required
`connection.saml.allowIdpInitiated`	`boolean`	required
`redirectUri`	`string`	required
`scopes`	`string[]`	required
`saml`	`object`	required
`saml.entityId`	`string`	required
`saml.acsUrl`	`string`	required
`saml.metadataUrl`	`string`	required
`saml.nameIdFormat`	`string`	required

POST`/v1/organizations/current/sso/test`

Start your own test sign-in: open `url`, sign in at your identity provider, and come back to organization settings.

Portal session only.

Response (JSON)
Field	Type	Notes
`url`	`string`	required
`expiresAt`	`string`	required

GET`/v1/organizations/current/sso/events`

The single sign-on log: tests, failed sign-ins and account links, newest first.

API key or OAuth token with organization:read.

Organization admins only. Codes and plain messages only: no token is ever kept.

Query parameters
Field	Type	Notes
`cursor`	`string`

Response (JSON)
Field	Type	Notes
`events`	`object[]`	required
`events[].id`	`string`	required
`events[].at`	`string`	required
`events[].kind`	`"sign_in" \| "test" \| "link"`	required
`events[].outcome`	`"ok" \| "error"`	required
`events[].code`	`string \| null`	required
`events[].message`	`string \| null`	required
`events[].email`	`string \| null`	required
`nextCursor`	`string \| null`	required

PATCH`/v1/organizations/current/sso/enforce`

Require single sign-on for addresses on the verified domains, or stop requiring it.

Portal session only.

Request body (JSON)
Field	Type	Notes
`enforce`	`boolean`	required

Response (JSON)
Field	Type	Notes
`connection`	`object \| null`	required
`connection.id`	`string`	required
`connection.protocol`	`"oidc" \| "saml"`	required
`connection.issuer`	`string`	required
`connection.clientId`	`string`	required
`connection.clientSecretSet`	`boolean`	required
`connection.clientSecretHint`	`string \| null`	required
`connection.tokenAuthMethod`	`"client_secret_basic" \| "client_secret_post"`	required
`connection.defaultWorkspaceId`	`string \| null`	required
`connection.defaultRole`	`"admin" \| "member" \| "viewer"`	required
`connection.state`	`"draft" \| "tested" \| "enabled"`	required
`connection.enforce`	`boolean`	required
`connection.enforceEnabledAt`	`string \| null`	required
`connection.configChangedAt`	`string`	required
`connection.lastTest`	`object \| null`	required
`connection.lastTest.at`	`string`	required
`connection.lastTest.by`	`object`	required
`connection.lastTest.result`	`string`	required
`connection.lastTest.matchedTester`	`boolean`	required
`connection.lastTest.current`	`boolean`	required
`connection.lastSignInAt`	`string \| null`	required
`connection.createdAt`	`string`	required
`connection.updatedAt`	`string \| null`	required
`connection.saml`	`object \| null`	required
`connection.saml.idpEntityId`	`string`	required
`connection.saml.ssoUrl`	`string`	required
`connection.saml.metadataUrl`	`string \| null`	required
`connection.saml.certificates`	`object[]`	required
`connection.saml.allowIdpInitiated`	`boolean`	required
`redirectUri`	`string`	required
`scopes`	`string[]`	required
`saml`	`object`	required
`saml.entityId`	`string`	required
`saml.acsUrl`	`string`	required
`saml.metadataUrl`	`string`	required
`saml.nameIdFormat`	`string`	required

GET`/v1/organizations/current/sso/break-glass`

Owners who keep passkey sign-in while single sign-on is required.

API key or OAuth token with organization:read.

Organization admins only. Every use is written to the audit and emailed to every admin.

Response (JSON)
Field	Type	Notes
`members`	`object[]`	required
`members[].userId`	`string`	required
`members[].email`	`string`	required
`members[].name`	`string \| null`	required
`members[].addedAt`	`string`	required
`members[].hasPasskey`	`boolean`	required
`max`	`integer`	required

POST`/v1/organizations/current/sso/break-glass`

Give an owner break-glass access (up to two).

Portal session only.

Request body (JSON)
Field	Type	Notes
`userId`	`string`	required up to 64 characters

Response (JSON)
Field	Type	Notes
`members`	`object[]`	required
`members[].userId`	`string`	required
`members[].email`	`string`	required
`members[].name`	`string \| null`	required
`members[].addedAt`	`string`	required
`members[].hasPasskey`	`boolean`	required
`max`	`integer`	required

DELETE`/v1/organizations/current/sso/break-glass/{userId}`

Remove an owner's break-glass access.

Portal session only.

Response (JSON)
Field	Type	Notes
`members`	`object[]`	required
`members[].userId`	`string`	required
`members[].email`	`string`	required
`members[].name`	`string \| null`	required
`members[].addedAt`	`string`	required
`members[].hasPasskey`	`boolean`	required
`max`	`integer`	required

GET`/v1/organizations/current/service-accounts`

The organization's service accounts: machine identities it owns, each with its scopes, caps, workspace and client secrets (never the secrets themselves).

API key or OAuth token with organization:read.

Organization admins, or a key, connected app or service account with organization:read. Behind the machineIdentities sub-flag: 404 not_found while it is off. A service account gets tokens from https://auth.50heads.com/token with grant_type=client_credentials and its client id and secret (HTTP Basic or the body) or a private_key_jwt assertion; no refresh token, ask again when it expires.

Response (JSON)
Field	Type	Notes
`serviceAccounts`	`object[]`	required
`serviceAccounts[].id`	`string`	required
`serviceAccounts[].name`	`string`	required
`serviceAccounts[].organizationId`	`string`	required
`serviceAccounts[].workspaceId`	`string`	required
`serviceAccounts[].workspaceName`	`string`	required
`serviceAccounts[].status`	`"active" \| "disabled"`	required
`serviceAccounts[].scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccounts[].capDailyPence`	`integer`	required
`serviceAccounts[].capPerQuestionPence`	`integer \| null`	required
`serviceAccounts[].spentTodayPence`	`integer`	required
`serviceAccounts[].clientId`	`string`	required
`serviceAccounts[].authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccounts[].secrets`	`object[]`	required
`serviceAccounts[].secrets[].id`	`string`	required
`serviceAccounts[].secrets[].hint`	`string`	required
`serviceAccounts[].secrets[].createdAt`	`string`	required
`serviceAccounts[].secrets[].expiresAt`	`string \| null`	required
`serviceAccounts[].secrets[].lastUsedAt`	`string \| null`	required
`serviceAccounts[].jwks`	`object \| null`	required
`serviceAccounts[].jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccounts[].createdAt`	`string`	required
`serviceAccounts[].createdBy`	`object \| null`	required
`serviceAccounts[].createdBy.id`	`string`	required
`serviceAccounts[].createdBy.name`	`string \| null`	required
`serviceAccounts[].lastUsedAt`	`string \| null`	required
`serviceAccounts[].disabledAt`	`string \| null`	required

GET`/v1/organizations/current/service-accounts/{id}`

One service account.

API key or OAuth token with organization:read.

As the list. Behind the machineIdentities sub-flag: 404 not_found while it is off. A service account gets tokens from https://auth.50heads.com/token with grant_type=client_credentials and its client id and secret (HTTP Basic or the body) or a private_key_jwt assertion; no refresh token, ask again when it expires.

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

POST`/v1/organizations/current/service-accounts`

Make a service account. Its client secret is in this response only.

Portal session only.

Organization admins only (403 organization_admin_required), on a browser session with a fresh proof in the x-50h-reauth header (401 reauth_required). It needs a person: API keys, connected apps and service accounts get 403 session_required. Every change is written to the organization's audit. It acts in the workspace you choose (the organization's main workspace by default) with the admin role there, limited by its scopes, and spends up to its daily and per-question caps. Up to 50 (409 too_many_service_accounts). With authMethod: private_key_jwt, send your public keys in jwks and no secret is made. Behind the machineIdentities sub-flag: 404 not_found while it is off. A service account gets tokens from https://auth.50heads.com/token with grant_type=client_credentials and its client id and secret (HTTP Basic or the body) or a private_key_jwt assertion; no refresh token, ask again when it expires.

Request body (JSON)
Field	Type	Notes
`name`	`string`	required up to 60 characters
`scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`capDailyPence`	`integer`	required 100–10000000
`capPerQuestionPence`	`integer \| null`
`workspaceId`	`string`	up to 64 characters
`authMethod`	`"client_secret" \| "private_key_jwt"`	default "client_secret"
`jwks`	`object`
`jwks.keys`	`map of object[]`	required up to 5 items
`jwks.keys[].kty`	`"EC" \| "RSA"`	required
`jwks.keys[].kid`	`string`	up to 200 characters
`jwks.keys[].alg`	`"ES256" \| "RS256"`
`jwks.keys[].use`	`"sig"`
`jwks.keys[].crv`	`string`	up to 20 characters
`jwks.keys[].x`	`string`	up to 2000 characters
`jwks.keys[].y`	`string`	up to 2000 characters
`jwks.keys[].n`	`string`	up to 2000 characters
`jwks.keys[].e`	`string`	up to 20 characters

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required
`clientSecret`	`string \| null`	required
`tokenEndpoint`	`string`	required

PATCH`/v1/organizations/current/service-accounts/{id}`

Rename a service account, or change its scopes, caps or workspace.

Portal session only.

Request body (JSON)
Field	Type	Notes
`name`	`string`	up to 60 characters
`scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`
`capDailyPence`	`integer`	100–10000000
`capPerQuestionPence`	`integer \| null`
`workspaceId`	`string`	up to 64 characters

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

POST`/v1/organizations/current/service-accounts/{id}/disable`

Turn a service account off: its tokens fail on their next request and it gets no new ones.

Portal session only.

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

POST`/v1/organizations/current/service-accounts/{id}/enable`

Turn a service account back on.

Portal session only.

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

DELETE`/v1/organizations/current/service-accounts/{id}`

Delete a service account. Its tokens, secrets and the webhook endpoints it made stop; the questions it asked stay with the workspace.

Portal session only.

Response (JSON)
Field	Type	Notes
`ok`	`true`	required

POST`/v1/organizations/current/service-accounts/{id}/secrets`

A new client secret, shown once. The old one keeps working for `overlapHours` (24 by default, 0 ends it now, up to 168).

Portal session only.

Request body (JSON)
Field	Type	Notes
`overlapHours`	`integer`	0–168, default 24

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required
`clientSecret`	`string \| null`	required
`tokenEndpoint`	`string`	required

DELETE`/v1/organizations/current/service-accounts/{id}/secrets/{secretId}`

End one client secret now.

Portal session only.

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

PUT`/v1/organizations/current/service-accounts/{id}/jwks`

Use private_key_jwt with these public keys (ES256 or RS256, up to 5). Every client secret stops working.

Portal session only.

Request body (JSON)
Field	Type	Notes
`jwks`	`object`	required
`jwks.keys`	`map of object[]`	required up to 5 items
`jwks.keys[].kty`	`"EC" \| "RSA"`	required
`jwks.keys[].kid`	`string`	up to 200 characters
`jwks.keys[].alg`	`"ES256" \| "RS256"`
`jwks.keys[].use`	`"sig"`
`jwks.keys[].crv`	`string`	up to 20 characters
`jwks.keys[].x`	`string`	up to 2000 characters
`jwks.keys[].y`	`string`	up to 2000 characters
`jwks.keys[].n`	`string`	up to 2000 characters
`jwks.keys[].e`	`string`	up to 20 characters

Response (JSON)
Field	Type	Notes
`serviceAccount`	`object`	required
`serviceAccount.id`	`string`	required
`serviceAccount.name`	`string`	required
`serviceAccount.organizationId`	`string`	required
`serviceAccount.workspaceId`	`string`	required
`serviceAccount.workspaceName`	`string`	required
`serviceAccount.status`	`"active" \| "disabled"`	required
`serviceAccount.scopes`	`"questions:read" \| "questions:write" \| "templates:read" \| "account:read" \| "webhooks:read" \| "webhooks:write" \| "apps:read" \| "apps:write" \| "organization:read" \| "organization:write" \| "members:read" \| "members:write" \| "audit:read" \| "events:read"[]`	required
`serviceAccount.capDailyPence`	`integer`	required
`serviceAccount.capPerQuestionPence`	`integer \| null`	required
`serviceAccount.spentTodayPence`	`integer`	required
`serviceAccount.clientId`	`string`	required
`serviceAccount.authMethod`	`"client_secret" \| "private_key_jwt"`	required
`serviceAccount.secrets`	`object[]`	required
`serviceAccount.secrets[].id`	`string`	required
`serviceAccount.secrets[].hint`	`string`	required
`serviceAccount.secrets[].createdAt`	`string`	required
`serviceAccount.secrets[].expiresAt`	`string \| null`	required
`serviceAccount.secrets[].lastUsedAt`	`string \| null`	required
`serviceAccount.jwks`	`object \| null`	required
`serviceAccount.jwks.keys`	`map of object[]`	required up to 5 items
`serviceAccount.createdAt`	`string`	required
`serviceAccount.createdBy`	`object \| null`	required
`serviceAccount.createdBy.id`	`string`	required
`serviceAccount.createdBy.name`	`string \| null`	required
`serviceAccount.lastUsedAt`	`string \| null`	required
`serviceAccount.disabledAt`	`string \| null`	required

JSON lines exports

GET /v2/questions/{id}/export.jsonl and GET /v2/sets/{id}/export.jsonl return every answer as JSON lines (application/x-ndjson): one JSON object per answer, each on its own line, for scripts and model training. They carry the same fields as the CSV export, plus choice and cohortHash, and nothing that identifies a head. The question export takes the same filters as the CSV; an empty body means no answers match.

curl -s https://api.50heads.com/v2/questions/q_8f2k1x/export.jsonl \
  -H "Authorization: Bearer $FIFTYHEADS_API_KEY" > answers.jsonl

One line:

{"questionId":"q_8f2k1x","type":"ranking","question":"Rank these names for a bakery","options":["Crumb","Loafers","Proof"],"cohortHash":"ch1_3f9a0c2e71b4d856","answeredAt":"2026-10-10T09:41:12.000Z","answer":"Crumb > Proof > Loafers","choice":{"order":[0,2,1]},"text":null,"translatedText":null,"reason":"Short and warm","translatedReason":null,"tier":1,"attestationRef":"att_5d0e7a91c2b4f3e86a17"}

The choice field

choice is the answer as indexes into options, counted from 0, so you never parse a label. It is null for free text and for a click test, whose taps are in taps. The same field is on each answer in the result (answers[].choice) and the answers pages.

Key	When
`index`	One pick: single choice, yes or no, A or B, a reaction. A 1 to 5 rating reads 0 to 4.
`indexes`	Pick several (multi choice), in option order.
`order`	Ranking, best first.
`pair`	Pairwise with three or more options: the two options shown; `index` is the one picked.
`ratings`	Rate each: one rating from 1 to 5 per statement, in option order.

The cohort hash

Cohort hash: the same value means the same kind of audience was asked (who, how many, which tier and targeting). It never identifies anyone. It is ch1_ and 16 hex characters, on every line and on the result as cohortHash. It also covers the question type, the language, an interest audience and its minimum grade, but never the words asked: two questions put to the same audience share it, so you can group their answers. Change who is asked and it changes. For a shared link, tier and targeting do not apply.

API reference

Pricing and config

POST/v1/billing/estimate

GET/v1/config

POST/v1/estimate

GET/v1/config/platform

GET/v1/templates

GET/v1/public/countries

GET/v1/tags

GET/v1/public/stats

GET/v1/public/subprocessors

Status, identity and limits

GET/v1/status

GET/v1/whoami

GET/v1/limits

Questions

POST/v2/questions

GET/v2/questions

GET/v2/questions/{id}

PATCH/v2/questions/{id}

GET/v2/questions/labels

GET/v2/questions/{id}/result

GET/v2/questions/{id}/answers

GET/v2/questions/{id}/insights

POST/v2/questions/{id}/insights

GET/v2/questions/{id}/wait

POST/v2/questions/{id}/cancel

POST/v2/questions/{id}/rating

POST/v2/questions/{id}/share

GET/v2/questions/{id}/export.csv

GET/v2/questions/{id}/export.jsonl

GET/v2/questions/{id}/link/qr.svg

GET/v2/questions/{id}/link/qr.png

GET/v2/questions/{id}/export.pdf

GET/v2/questions/{id}/export.png

POST/v2/questions/{id}/exports

POST/v2/questions/{id}/heads

POST/v2/questions/{id}/answers/{ref}/flag

POST/v2/questions/{id}/answers/{ref}/pin

GET/v2/questions/{id}/share-links

POST/v2/questions/{id}/share-links

DELETE/v2/questions/{id}/share-links/{linkId}

GET/v1/public/link/{code}

POST/v1/public/link/{code}/answers

POST/v1/public/link/{code}/started

GET/v1/public/shared/{token}

GET/v2/questions/{id}/heatmap.png

POST/v2/questions/{id}/dispute

GET/v1/public/results/{code}

Sets

POST/v2/sets

GET/v2/sets

GET/v2/sets/{id}

POST/v2/sets/{id}/close

GET/v2/sets/{id}/export.csv

GET/v2/sets/{id}/export.jsonl

GET/v2/sets/{id}/link/qr.svg

GET/v2/sets/{id}/link/qr.png

Drafts and uploads

GET/v1/drafts

POST/v1/drafts

PUT/v1/drafts/{id}

DELETE/v1/drafts/{id}

POST/v1/question-reviews

GET/v1/question-reviews/{hash}

POST/v1/uploads

POST/v1/uploads/import

POST/v1/mockups

Projects

GET/v1/projects

POST/v1/projects

PATCH/v1/projects/{id}

DELETE/v1/projects/{id}

Audiences

GET/v1/interest-audiences

GET/v1/interest-audiences/{slug}

Saved audiences

GET/v1/audiences

POST/v1/audiences

PUT/v1/audiences/{id}

POST`/v1/billing/estimate`

GET`/v1/config`

POST`/v1/estimate`

GET`/v1/config/platform`

GET`/v1/templates`

GET`/v1/public/countries`

GET`/v1/tags`

GET`/v1/public/stats`

GET`/v1/public/subprocessors`

GET`/v1/status`

GET`/v1/whoami`

GET`/v1/limits`

POST`/v2/questions`

GET`/v2/questions`

GET`/v2/questions/{id}`

PATCH`/v2/questions/{id}`

GET`/v2/questions/labels`

GET`/v2/questions/{id}/result`

GET`/v2/questions/{id}/answers`

GET`/v2/questions/{id}/insights`

POST`/v2/questions/{id}/insights`

GET`/v2/questions/{id}/wait`

POST`/v2/questions/{id}/cancel`

POST`/v2/questions/{id}/rating`

POST`/v2/questions/{id}/share`

GET`/v2/questions/{id}/export.csv`

GET`/v2/questions/{id}/export.jsonl`

GET`/v2/questions/{id}/link/qr.svg`

GET`/v2/questions/{id}/link/qr.png`

GET`/v2/questions/{id}/export.pdf`

GET`/v2/questions/{id}/export.png`

POST`/v2/questions/{id}/exports`

POST`/v2/questions/{id}/heads`

POST`/v2/questions/{id}/answers/{ref}/flag`

POST`/v2/questions/{id}/answers/{ref}/pin`

GET`/v2/questions/{id}/share-links`

POST`/v2/questions/{id}/share-links`

DELETE`/v2/questions/{id}/share-links/{linkId}`

GET`/v1/public/link/{code}`

POST`/v1/public/link/{code}/answers`

POST`/v1/public/link/{code}/started`

GET`/v1/public/shared/{token}`

GET`/v2/questions/{id}/heatmap.png`

POST`/v2/questions/{id}/dispute`

GET`/v1/public/results/{code}`

POST`/v2/sets`

GET`/v2/sets`

GET`/v2/sets/{id}`

POST`/v2/sets/{id}/close`

GET`/v2/sets/{id}/export.csv`

GET`/v2/sets/{id}/export.jsonl`

GET`/v2/sets/{id}/link/qr.svg`

GET`/v2/sets/{id}/link/qr.png`

GET`/v1/drafts`

POST`/v1/drafts`

PUT`/v1/drafts/{id}`

DELETE`/v1/drafts/{id}`

POST`/v1/question-reviews`

GET`/v1/question-reviews/{hash}`

POST`/v1/uploads`

POST`/v1/uploads/import`

POST`/v1/mockups`

GET`/v1/projects`

POST`/v1/projects`

PATCH`/v1/projects/{id}`

DELETE`/v1/projects/{id}`

GET`/v1/interest-audiences`

GET`/v1/interest-audiences/{slug}`

GET`/v1/audiences`

POST`/v1/audiences`

PUT`/v1/audiences/{id}`

DELETE`/v1/audiences/{id}`

GET`/v1/billing/balance`

GET`/v1/billing/ledger`

POST`/v1/billing/checkout`

POST`/v1/billing/store-purchases/intent`

POST`/v1/billing/store-purchases`

GET`/v1/billing/store-purchases`

GET`/v1/billing/invoices`

GET`/v1/billing/invoices/{id}/pdf`