# API Guide Index

This is the canonical directory for public guide files served from
`/docs/api/guides/<filename>`. Links are grouped by the workflow they support so
developers and AI agents can choose the right starting point without guessing
file names.

## Recommended Paths

- New API integration:
  [Quickstart](./quickstart.md) -> [Async Polling](./async_job_polling.md) ->
  [Common Mistakes](./common_mistakes.md) -> [Workflow Diagram](./workflow_diagram.md)
- Recruitment and filtering:
  [Recruitment Filter Expansion](./recruitment_filter_expansion.md) ->
  [Filters Reference](./filters.md) ->
  [Research Group Requests](./research_group_requests.md)
- MCP / AI-agent usage:
  [MCP Adapter Quickstart](./mcp_quickstart.md) ->
  [Thesis Lab Wave 1](./thesis_lab_wave1.md) ->
  [Agent Industry Digests](./agent_industry_digests.md)
- Auth, billing, and operations:
  [Auth](./auth.md) ->
  [Pricing Tiers and Billable Events](./pricing_tiers_and_billable_events.md) ->
  [Stripe Billing Operations](./stripe_billing_operations.md)

## Core API Workflow

- [Quickstart](./quickstart.md): canonical implementation sequence for
  recruitment, study creation, question asking, polling, completion, and share
  enablement.
- [Examples](./examples.md): concrete request examples for common endpoint
  families.
- [Async Polling](./async_job_polling.md): status model and wait strategy for
  `GET /v1/jobs/{job_id}`.
- [Common Mistakes](./common_mistakes.md): frequent integration errors and the
  exact corrections.
- [Workflow Diagram](./workflow_diagram.md): branch map for study, direct
  question, curation, and media workflows.
- [Postman Collection](./postman_collection.json): runnable request collection
  for the primary flow and branch scenarios.
- [API Changelog](./changelog.md): dated externally visible documentation and
  contract updates.

## Recruitment and Filters

- [Recruitment Filter Expansion](./recruitment_filter_expansion.md): health
  profile, occupation synonym, occupation/industry metadata, value discovery,
  and MCP shortcut guidance.
- [Filters Reference](./filters.md): filter syntax, matching rules, aliases,
  exact-match behavior, and documented value sets.
- [Research Group Requests](./research_group_requests.md): natural-language
  group request workflow, status fields, clarification, refusal, and review.
- [Research Study Requests](./research_study_requests.md): natural-language
  end-to-end recruitment plus study creation workflow.

## MCP and Thesis Lab

- [MCP Adapter Quickstart](./mcp_quickstart.md): MCP server setup, tool map,
  tenant headers, and preferred AI-authored recruitment path.
- [Thesis Lab Wave 1](./thesis_lab_wave1.md): Thesis Lab API/MCP usage guide.
- [Agent Industry Digests](./agent_industry_digests.md): agent industry digest
  workflow guidance.

## Access, Billing, and Operations

- [Auth](./auth.md): API-key authentication guidance.
- [Claude Code Free-Tier OAuth](./claude_code_free_tier_oauth.md): free-tier
  OAuth flow notes for Claude Code usage.
- [Pricing Tiers and Billable Events](./pricing_tiers_and_billable_events.md):
  plan and usage-event behavior.
- [Stripe Billing Operations](./stripe_billing_operations.md): operational
  billing guidance.
- [Slack Request URL Marketplace Migration](./slack_request_urls_marketplace_migration.md):
  Slack marketplace Request URL migration.
- [Slack Request URL Cutover Checklist](./slack_request_url_cutover_checklist.md):
  step-by-step Slack Request URL cutover commands.
- [Slack Worker Observability](./slack_worker_observability.md): Slack worker
  runtime observability notes.