Skip to main content
POST
Queue Customize Study Plan

Authorizations

Authorization
string
header
required

Authenticate with an API key (prefixed ui_sk_) or a JWT token from the dashboard.

Headers

Idempotency-Key
string | null
X-UI-Organization-ID
string | null

Platform admins only: choose an organization for scoped reads and writes. Required to change another organization's study or use its wallet.

Maximum string length: 128

Path Parameters

study_id
string
required

Body

application/json

One user turn for the stateful Customize Plan conversation.

message
string
required
Required string length: 1 - 20000
decisions
enum<string>
default:human

human relays required decisions; agent makes reviewable assumptions when possible.

Available options:
human,
agent
execution_policy
enum<string>
default:review_before_fieldwork

Caller workflow constraint, kept separate from participant-facing research content. This endpoint never launches recruitment.

Available options:
review_before_fieldwork,
draft_only
concept_image
PublicCustomizeConceptImage · object | null

Optional native concept-image attachment for this turn. The backend validates, stores, and makes it available to Customize Plan.

Response

Successful Response

job_id
string
required
status
enum<string>
required
Available options:
pending,
running,
succeeded,
failed
completed
boolean
required

True when work has finished successfully

result_url
string | null

Fetch the created resource after success

total_count
integer | null

Requested participant count for a batch

error
string | null

A safe failure summary; internal details are never returned

result
PublicCustomizeStudyResponse · object | null

The completed planning turn; null until the job succeeds