create_survey
Convert a confirmed survey plan into a live human annotation task with immediate credit reservation and dispatch.
Instructions
Create a survey from a plan generated by plan_survey.
⚠ Only call this after the user has explicitly confirmed the plan
summary and cost from plan_survey. This reserves credits immediately
and dispatches paid human annotation work — there is no draft or
staging state, and it cannot be undone.
Pass the plan dict as returned by plan_survey. You may edit it first if anything is off — this is a regular Python dict.
Supports both standalone plans and chain plans (with a top-level steps
array alongside datapoints). For chain plans, the backend dispatches
each step of each datapoint as a linked task; the full sequence is
served together, in order, to one annotator per response.
MEDIA VALIDATION: every media entry must use either:
a dp://media/… reference returned by
upload_media, ora public https:// URL the annotator's browser can reach.
Media lives at datapoints[*].media (shared across steps) OR
datapoints[*].media_per_step["0"], ["1"], ... (one entry per step
when steps need different media shapes). The two are mutually exclusive
per datapoint.
Local paths, file:// URLs, and private/auth-gated URLs will be rejected or served broken to annotators. If the plan came back with wrong refs (e.g. the planner invented a URL because the description didn't supply one), fix the refs before calling this:
# shared media
plan["datapoints"][0]["media"]["candidates"][0]["url"] = "dp://media/real.png"
# per-step media (chain)
plan["datapoints"][0]["media_per_step"]["1"]["subject"][0]["url"] = "dp://media/real.mp3"Args:
plan: The survey plan dict (typically from plan_survey). Contains
name, summary, datapoints, and either task_type + instruction
(standalone) or a steps array (chain).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| plan | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |