Audiences

Create a grounded audience from a brief

Create one Audience from a free-text brief. Attached research files use the same extended screener/questionnaire analysis as the in-app New Audience flow, including Study roles, screening and quota rules, review distributions, and grounding provenance. Public bearer-authenticated V1 requests return 202 Accepted; poll the returned status URL until the durable processor operation completes.

post/api/v1/audiences/from-brief

Request

  • Base URL: https://api.getminds.ai
  • URL: https://api.getminds.ai/api/v1/audiences/from-brief
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Retry-safety key, max 200 chars (also accepted as the idempotencyKey body field; the header wins). Creation can exceed typical client timeouts — retrying with the same key within 6 hours returns the audience the original request created (200, replayed: true) instead of creating a duplicate.

Prefer'respond-async'

Return 202 after durable admission and run the complete build on the processor.

Request body

textstring required

Free-text brief describing the audience or population to represent.

namestring

Optional audience name override. When omitted, the server names the audience from the brief or detected personas.

linksstring[]

URLs to scrape for additional context.

keywordsstring[]

Search keywords used as extra context and research seeds.

includeWebSearchboolean

When false, skips Exa search/extraction completely and grounds only on the supplied brief, files, links, keywords, and structurally parsed respondent data. A study report, questionnaire, screener or respondent dataset still grounds the Audience but is withheld from the members' own knowledge (see withheldFromMemberKnowledge), so it is not evidence they can answer from; when nothing survives that filter the request is refused with 400 rather than creating Minds with no evidence.

isLinkSharingEnabledboolean

Enable public link sharing for the created audience.

generateImagesboolean

Generate AI profile images and an audience cover asynchronously for members the approved persona-image catalog could not serve. Catalog portraits are assigned either way — that is asset selection, not generation — so false avoids every image-model call for this creation while members still receive real portraits wherever the catalog matches; only unmatched members keep the initials fallback.

trainMembersboolean

Deprecated; omit it. Every member of every Audience is individually trained in the background, including large reviewed-dataset cohorts (> 40 Minds), through the same per-member pipeline the in-app flow uses, keeping each Mind's deterministic cohort profile and the request locale. true is accepted as a no-op; false is rejected with 400 TRAIN_MEMBERS_OPT_OUT_REMOVED (it used to create untrained Minds with an empty system prompt that reported ready). Cost and time: each member consumes one Mind training (research, knowledge and prompt generation); a 100-Mind cohort typically finishes over tens of minutes to a few hours, staggered per Audience. The response returns as soon as the Audience exists; poll GET /api/v1/minds/{mindId}/training per member (or the Audience progress endpoint) and wait for every member to report readyToChat before running a Study — Study runs refuse Audiences with untrained members.

idempotencyKeystring

Retry-safety key (same semantics as the Idempotency-Key header, which wins when both are sent). Reusing the key within 6 hours replays the audience it created instead of duplicating it.

asyncboolean

Optional async hint for internal cookie-authenticated callers. Public bearer-authenticated V1 requests are always enqueued and return a pollable 202 operation.

draftPreviewboolean

Generate the same durable draft as the webapp: streamed research, distributions, and proposed Minds. Always returns a 202 operation; its completed result contains draft.id and draft.sha256. No Audience or Minds are materialized until acceptance.

reviewedDraftIdstring uuid

Owned draft.id returned by the native draft preview. Pass with reviewedDraftSha256 to rework or accept that roster.

reviewedDraftSha256string

Exact draft checksum from the latest review. Stale reviews fail before materialization.

draftReworkstring

Refinement instruction, with draftPreview:true and the reviewed draft pair. The original brief and earlier revisions remain in context. When the instruction cannot be placed on one of the draft's charts, the draft is returned unchanged with clarification: a question to ask the user before reworking again.

groundingPreviewboolean

Review the quota axes before any Mind exists. When true the request runs research grounding plus a deterministic allocation preview and returns the reviewed grounding, checksum, effective cohortAllocation audit, flags, and size without creating an Audience or Minds or consuming generation allowance. Fresh public previews always return a durable 202 operation, including when async is omitted or false. Saved-snapshot previews may return inline; send async: true or Prefer: respond-async to queue those too. Poll its status URL for the same preview result. Explicit allocation targets that cannot match the grounded axes are set aside and listed in cohortAllocation.audit.warnings (or as a target_unapplied notice on the grounding), never refused, just like creation. If research did not finish, the preview says so (research_unavailable) and creating from it researches the Audience in the background. Axes that measure the Study outcome itself are demoted to supplementary context and listed in flaggedDistributions.

reviewedGroundingJsonstring

Exact reviewed grounding snapshot returned by a prior preview. Send it unchanged with reviewedGroundingSha256 to re-preview revised exclusions/allocation options against the same evidence, or to create from the latest accepted preview without rerunning grounding research.

reviewedGroundingSha256string

SHA-256 returned with reviewedGroundingJson. Both fields are required together; creation fails before materialisation when the checksum does not match.

excludeDistributionsstring[]

Exact axis names whose composition quotas should be removed. Age remains as one eligibility range without within-range shares; explicit gender membership remains enforced. Include required eligibility axes in cohortAllocation.distributionNames. Original evidence stays in reviewDistributions.

memberCountinteger

Exact number of Minds to create. Wins over any count parsed from text and over grounding suggestions, while remaining subject to the effective plan and creation-mode caps.

audienceCreationMode'balanced' | 'segment_coverage' | 'benchmark_depth'

Deprecated alias for audienceCreationMode. If both fields are supplied, their values must match.

datasetSegmentationobject

Reviewed research-variable roles, distributions, privacy-safe pairwise relationships, and deterministic dependencies (recodes and questionnaire routing filters) returned by the segmentation-preview endpoint. Pass functionalDependencies and dependencyDiscovery through unchanged: the first are hard constraints, so a synthetic respondent never breaks a recode and a filtered question stays unanswered at the source rate; the second reports which discovery bounds applied and is echoed into cohortAllocation.audit.jointConsistency. Omitting it does not disable enforcement, but the audit will say the bounds are unknown. Requires Team plus benchmark_depth. Structural variables shape a representative cohort; outcomes remain held out and observed joint combinations remain audit evidence rather than respondent-like Minds.

Response

Either an idempotent replay (the supplied idempotency key already created an audience within the replay window; returns that audience with replayed: true, nothing new is created, no plan allowances are consumed, datasetSegmentation is not reconstructed) or a saved-snapshot/internal groundingPreview result containing reviewed grounding, checksum, effective cohortAllocation audit, flags, and size with no Audience or Minds created.

Changes

No recorded changes to this operation across all 1 revision of this API.