Create study

POST /v1/api/studies Requires studies:write

Brief Juno to create a research study from plain-language guidance: describe what the user wants to learn, and Juno designs the interview — objectives, screener questions, and the questions the interviewer will ask. Upload documents first and include their file_ids when they are part of the brief. Authoring runs in the background: this returns a job_id; poll Check authoring status until the study and its brief are ready. New studies start in test mode so the user can safely simulate the shape of the interview before choosing Go live. Test mode uses no credits, provides no analysis or exports, and is not intended for real participant research.

Request body application/json

guidance

string required

Plain-language instruction from the user: the research goal, intended participants, and what the user wants to learn — or, when updating, what to change. A sentence or two is enough.

file_ids

string[] · nullable

Optional file ids from POST /v1/api/files. Include them when documents are part of Create a study or Update a study.

Responses

202 Successful Response

job_id

string required

Authoring job handle. Poll GET /v1/api/studies/jobs/{job_id} until status is 'ready'.

thread_id

string <uuid> required

The authoring conversation thread the run executes in.

422 Validation Error

ValidationError[]

cURL

curl -X POST 'https://api.heyjuno.co/v1/api/studies' \
  -H 'Authorization: Bearer $JUNO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "guidance": "Interview 10 recent churned customers about why they cancelled.",
  "file_ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}'

Example response

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}