Raw schema
{
"type": "object",
"properties": {
"brief": {
"type": "string",
"minLength": 3,
"maxLength": 4000,
"description": "Free-text brief describing the population the group should represent. E.g. \"California high school students grades 9-12\", \"Berlin Späti customers\", \"Spanish lawyers\", \"management team of Coca Cola\". The server runs deep web research on this brief to find demographic / psychographic distributions from authoritative sources, then generates personas that proportionally reflect those distributions."
},
"text": {
"type": "string",
"minLength": 3,
"maxLength": 4000,
"description": "Legacy alias for `brief`. Accepted for back-compat."
},
"name": {
"type": "string",
"maxLength": 100,
"description": "Optional group name override. When omitted, the server names the group from the brief or the LLM detection result."
},
"links": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Optional URLs scraped server-side for additional context (e.g. an article describing the population)."
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Optional Exa web-search seeds added alongside the brief."
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "File name"
},
"url": {
"type": "string",
"description": "Public or signed URL of an already-uploaded file"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"maxItems": 10,
"description": "Optional already-uploaded research files. The server analyzes these through the same extended screener/questionnaire path as the in-app New Group uploader, including study roles, screening and quota rules, review distributions, and grounding provenance."
},
"includeWebSearch": {
"type": "boolean",
"default": true,
"description": "Set false to skip Exa web search and extraction completely. The group is then grounded only on the brief and supplied files, links, keywords, and structurally parsed respondent data."
},
"memberCount": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Exact number of Minds to create in the group. Pass this whenever the user states a size (\"exactly 50 per region\", \"genau 50 Minds je Zelle\") instead of relying on the server to parse the number out of the brief prose. When omitted, the size is inferred from the brief and, failing that, from the creation mode's evidence-based automatic sizing. Rejected with 403 PLAN_LIMIT when it exceeds the plan's per-group cap; the group is never created at a partial size."
},
"groupCreationMode": {
"type": "string",
"enum": [
"balanced",
"segment_coverage",
"benchmark_depth"
],
"description": "Group creation mode. \"balanced\" (default): compact, representative group for everyday research. \"segment_coverage\": two representatives per limiting grounded audience cell, with a 10-Mind evidence floor and 50-Mind mode ceiling. \"benchmark_depth\": repeated representation of limiting grounded audience cells for validation-ready benchmark / survey-style segmentation, with the paid allowance as its ceiling. The deeper modes require a Team (enterprise) plan — on other plans the server SILENTLY downgrades to \"balanced\" and echoes the effective mode in the response (structuredContent.group.groupCreationMode)."
},
"datasetSegmentation": {
"type": "object",
"properties": {
"fileName": {
"type": "string"
},
"sheetName": {
"type": "string"
},
"respondentCount": {
"type": "integer",
"minimum": 0,
"description": "Total respondent rows in the reviewed sheet, copied from the preview."
},
"recommendedMindCount": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Preview-recommended cohort size. Caps how many Minds the benchmark run creates."
},
"variables": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"distribution": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"string",
"null"
]
},
"respondentCount": {
"type": "integer",
"minimum": 0
},
"sharePct": {
"type": "number",
"minimum": 0
}
},
"required": [
"value",
"respondentCount",
"sharePct"
],
"additionalProperties": false
},
"maxItems": 30
},
"validRespondentCount": {
"type": "integer",
"minimum": 0
},
"otherRespondentCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"key",
"label",
"distribution"
],
"additionalProperties": false
},
"maxItems": 200,
"description": "Variable-level distributions from the preview (preferred over `columns` when present)."
},
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"distribution": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"string",
"null"
]
},
"respondentCount": {
"type": "integer",
"minimum": 0
},
"sharePct": {
"type": "number",
"minimum": 0
}
},
"required": [
"value",
"respondentCount",
"sharePct"
],
"additionalProperties": false
},
"maxItems": 30
},
"validRespondentCount": {
"type": "integer",
"minimum": 0
},
"otherRespondentCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"key",
"label",
"distribution"
],
"additionalProperties": false
},
"maxItems": 200,
"description": "Column-level distributions from the preview. Used when `variables` is absent."
},
"segmentationColumns": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 200,
"description": "Keys of the variables the user kept after review. These are the only ones that shape the cohort."
},
"combinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"respondentCount": {
"type": "integer",
"exclusiveMinimum": 0
},
"sharePct": {
"type": "number",
"minimum": 0
}
},
"required": [
"id",
"respondentCount",
"sharePct"
],
"additionalProperties": false
},
"maxItems": 5000,
"description": "Observed joint profiles as audit counts. Copy the ids and counts from the preview; per-cell values are not needed."
},
"retainedCombinationIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 5000
}
},
"required": [
"fileName",
"segmentationColumns",
"combinations"
],
"additionalProperties": false,
"description": "Reviewed variable roles, distributions, and privacy-safe pairwise relationships returned by preview_group_dataset_segmentation. Requires groupCreationMode=\"benchmark_depth\". Structural variables shape one generalizable representative cohort; outcomes remain held out and joint combinations remain audit evidence only. Copy `respondentCount` and `recommendedMindCount` through from the preview — they cap the cohort size."
},
"cohortAllocation": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"seed": {
"type": "string",
"maxLength": 200
},
"distributionNames": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 200
},
"maxDistributions": {
"type": "integer",
"minimum": 1,
"maximum": 200
},
"minSegmentCount": {
"type": "integer",
"minimum": 0,
"maximum": 20
},
"targetOverrides": {
"type": "array",
"items": {
"type": "object",
"properties": {
"distribution": {
"type": "string"
},
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"pct": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"label",
"pct"
],
"additionalProperties": false
},
"maxItems": 50
}
},
"required": [
"distribution",
"segments"
],
"additionalProperties": false
},
"maxItems": 200
},
"jointStrategy": {
"type": "string",
"enum": [
"independent",
"aligned",
"observed"
]
},
"includeProfilesInResponse": {
"type": "boolean"
}
},
"additionalProperties": false,
"description": "Deterministic allocation controls. Reviewed respondent datasets default to observed, which preserves the strongest privacy-safe structural relationships while keeping exact marginals; other sources default to independence. Use distributionNames/maxDistributions to choose axes, minSegmentCount for a feasible floor, and seed for reproducible external runs."
},
"isLinkSharingEnabled": {
"type": "boolean",
"default": false,
"description": "Set true ONLY when the user explicitly asked for a public/shareable link. Defaults to false: the group is private to its owner and no share URL is generated. Enabling this publishes the group — including its grounding, sources and personas — at a world-readable URL that needs no login. Do not enable it to \"be helpful\"."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}