# Research Study Requests (Natural Language)

This guide explains how the natural-language Research Study Request pipeline
works and what to expect from sync create, async create, and status polling.

Related guides:
[All Guides](./index.md) |
[Research Group Requests](./research_group_requests.md) |
[Recruitment Filter Expansion](./recruitment_filter_expansion.md) |
[Quickstart](./quickstart.md)

## Endpoint Summary

- Create/resume: `POST /v1/research-study-requests`
- Status polling: `GET /v1/research-study-requests/{request_id}`

## When To Use This Path

Use Research Study Requests when the caller wants the system to handle:

- audience translation
- recruitment
- study creation
- question-plan generation

in one request-driven workflow.

For a more manual flow, use:

1. `POST /v1/research-group-requests`
2. `GET /v1/research-group-requests/{request_id}`
3. `POST /v1/research-studies`

## Create Modes

`POST /v1/research-study-requests` supports two response modes:

- `response_mode=async`
  - returns `202`
  - queues background orchestration
  - includes `request_id`, `job_id`, and `status_url`
- `response_mode=sync`
  - waits for the current request worker pass
  - may immediately return:
    - `201 completed`
    - `400 needs_clarification`
    - `422 refused`
    - `202 queued` when the request is still in progress

Only poll when the create call actually returned a non-terminal queued/running
request.

## High-Level Workflow

1. **Parse**: Interpret the natural-language request into recruitment and study
   intent.
2. **Recruit**: Run the shared recruitment Specialist / request execution path.
3. **Clarify or refuse when needed**: Pause for missing information or refuse
   structurally unworkable asks.
4. **Create study**: Persist the resulting study when recruitment succeeds.
5. **Return status**: Expose the current request state, embedded study snapshot,
   and compact Specialist runtime metadata.

## Status Fields

Status responses include:

- `status`: `queued`, `running`, `needs_clarification`, `refused`,
  `completed`, `failed`
- `phase`: current orchestration phase
- `job_id`: background job id when one exists
- `question_count`: requested/generated study question count
- `warnings`: non-fatal runtime warnings
- `clarifying_questions`, `missing_info`: clarification payload when present
- `research_group_uuid`: linked recruited group when one exists
- `study_id`, `study_uuid`, `study`: created study when one exists
- `source_surface`, `audience_brief_source`,
  `recruitment_translation_owner`: normalized provenance
- `refusal`, `refusal_reason`: structured refusal payload when the Specialist
  refuses the request
- `specialist_host_mode`, `requested_specialist_host_mode`,
  `specialist_host_status`, `specialist_host_message`: compact Specialist host
  runtime metadata
- `specialist_prompt_step_status`, `specialist_prompt_step_reason_code`,
  `specialist_prompt_step_message`: prompt-step execution status and operator
  detail
- `specialist_prompt_decision_action`,
  `specialist_prompt_decision_message`: prompt host decision details when one
  exists
- `specialist_prompt_applied_change_count`,
  `specialist_prompt_applied_change_keys`: compact summary of which request
  fields the Specialist prompt step actually rewrote before deterministic
  compile/preflight execution

In production environments with the bound Specialist host, skill row, and
provider credentials available, these fields will usually show
`specialist_host_mode=prompt_assisted` and
`specialist_host_status=auto_prompt_assisted`. `deterministic_only` remains the
fallback for bare or unconfigured runtimes.

## Example Sync Clarification Response

```json
{
  "error": "needs_clarification",
  "request_id": "rsr_123",
  "status": "needs_clarification",
  "phase": "parse",
  "clarifying_questions": [
    "Should I broaden the target geography?"
  ],
  "missing_info": [
    "fallback geography"
  ],
  "specialist_host_mode": "prompt_assisted",
  "requested_specialist_host_mode": "prompt_assisted",
  "specialist_host_status": "auto_prompt_assisted",
  "specialist_prompt_step_status": "completed",
  "specialist_prompt_step_reason_code": "prompt_assisted",
  "specialist_prompt_decision_action": "continue"
}
```

## Example Sync Completed Response

```json
{
  "request_id": "rsr_456",
  "status": "completed",
  "phase": "completed",
  "study_id": 321,
  "study_uuid": "study_321",
  "study": {
    "id": 321,
    "uuid": "study_321",
    "title": "Packaging Preference Study",
    "url": "https://api.example.com/organization/<org_uuid>/studies/study_321"
  }
}
```

## Clarification and Refusal

- `needs_clarification`: Returned when required information is missing or
  unsupported. Answer the clarifying questions, then resume with the same
  `request_id`.
- `refused`: Returned when the deterministic Specialist concludes the audience
  or constraint combination is not executable. Revise the request and retry
  instead of continuing to downstream study steps.

## Resume Contract

To resume an existing request, call `POST /v1/research-study-requests` with:

- `request_id`
- optional `additional_text`

If the resumed request is run with `response_mode=sync`, it can again return a
terminal sync outcome immediately.

## Notes

- Prefer `GET /v1/research-study-requests/{request_id}` over `GET /v1/jobs/{job_id}`
  when you already have a `request_id`.
- Use `GET /v1/jobs/{job_id}` only when you truly only have the explicit queued
  job id.
- This path is the default AI-authored route when the caller wants recruitment
  and study design handled together.