# Workflow Diagram

Use this map to choose the right execution path before integrating.

## Diagram (Image)

![FishDog API workflow branch map](../assets/workflow_branches.svg)

## Text Fallback (Accessible Branch Map)

1. Decision: do you need structured multi-question research?
2. If yes, follow the core 6-step flow:
   - Recruit a group (`POST /v1/research-groups/recruit`)
   - Create a study (`POST /v1/research-studies`)
   - Ask one question at a time (`POST /v1/research-studies/{study_id}/questions`)
   - Poll job to `finished` (`GET /v1/jobs/{job_id}`)
   - Complete study (`POST /v1/research-studies/{study_id}/complete`)
   - Enable sharing (`POST /v1/research-studies/{study_id}/share`)
3. If no, decide between direct ask modes:
   - Single participant: `POST /v1/research-agents/{agent_id}/questions`
   - Existing group: `POST /v1/research-groups/{group_id}/questions`
4. Over-recruit and curate branch:
   - Recruit larger group
   - Create study and ask screening question
   - Remove mismatched participants (`DELETE /v1/research-studies/{study_id}/agents`)
   - Continue remaining questions with curated cohort
5. Media attachment branch (applies to direct and study question paths):
   - Upload once (`POST /v1/media-assets`)
   - Reuse returned `media_asset_id` in attachments arrays

## Related Testing Assets

- Postman collection: `docs/api/guides/postman_collection.json`
- Canonical flow details: `docs/api/guides/quickstart.md`
- Polling behavior: `docs/api/guides/async_job_polling.md`