# Examples

These examples lead with the request-first workflow for AI-authored
recruitment. Direct `POST /v1/research-groups/recruit` remains available as the
strict raw-filter escape hatch.

## Create a Group Request (Queued)

```json
{
  "request_id": "rgr_123",
  "job_id": "rq:job:group-123",
  "status_url": "https://api.example.com/v1/jobs/rq:job:group-123"
}
```

## Group Request Status (Completed)

```json
{
  "request_id": "rgr_123",
  "status": "completed",
  "phase": "completed",
  "progress_message": "Recruitment complete.",
  "group": {
    "id": 124,
    "uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "name": "Midwest Parents",
    "description": "Parents in the Midwest, ages 30-45",
    "agent_count": 2,
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0"
  },
  "recruited_agent_ids": [9012, 9013],
  "recruited_agents": [
    {
      "id": 9012,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9012"
    },
    {
      "id": 9013,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9013"
    }
  ],
  "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"
}
```

## Create a Study Request (Sync Completed)

```json
{
  "request_id": "rsr_456",
  "status": "completed",
  "phase": "completed",
  "research_group_uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
  "study_id": 812,
  "study_uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
  "study": {
    "id": 812,
    "uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
    "title": "Grocery Preferences 2026",
    "objective": "Understand grocery shopping priorities",
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/studies/aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa"
  },
  "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"
}
```

## Strict Raw-Filter Recruit (Response)

```json
{
  "group": {
    "id": 124,
    "uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "name": "Midwest Parents",
    "description": "Parents in the Midwest, ages 30-45",
    "agent_count": 2,
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0"
  },
  "filters": {
    "match": "all",
    "filters": {
      "state": {
        "any": ["IL", "IN", "MI", "OH"]
      },
      "age": {
        "min": 30,
        "max": 45
      },
      "is_parent": true
    }
  },
  "recruited_agent_ids": [9012, 9013],
  "recruited_agents": [
    {
      "id": 9012,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9012"
    },
    {
      "id": 9013,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9013"
    }
  ]
}
```

## Create a Study (Response)

```json
{
  "study": {
    "id": 812,
    "uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
    "title": "Grocery Preferences 2026",
    "objective": "Understand grocery shopping priorities",
    "shareable": false,
    "share_url": null,
    "share_link": null,
    "research_group_uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "research_group_url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "research_groups": [
      {
        "uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
        "name": "Grocery Shoppers",
        "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0"
      }
    ],
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/studies/aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa"
  }
}
```

## Find a Single Agent (Response)

```json
{
  "agent": {
    "id": 9012,
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9012",
    "uuid": "f2f4a9f1-9fd4-4e49-8d5f-266bc4c0f667",
    "name": "Morgan Reed",
    "age": 72,
    "occupation": "Retired teacher",
    "industry": "Education",
    "city": "Pittsburgh",
    "state": "PA",
    "country": "US",
    "sex": "male",
    "summary": "Long-time Pennsylvania resident and active community volunteer.",
    "annual_income_usd": 56000,
    "marital_status": "married",
    "num_children": 2
  },
  "count": 1,
  "total_count": 14
}
```

## List Studies (Response)

```json
{
  "studies": [
    {
      "id": 812,
      "uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
      "title": "Grocery Preferences 2026",
      "objective": "Understand grocery shopping priorities",
      "stage": "fielding",
      "shareable": false,
      "share_url": null,
      "share_link": null,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/studies/aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
      "participant_count": 20,
      "question_count": 3,
      "created_at": "2026-01-06T13:28:42Z",
      "updated_at": "2026-01-06T13:45:10Z"
    }
  ],
  "count": 1,
  "total": 1
}
```

## Get a Study (Response)

```json
{
  "study": {
    "id": 812,
    "uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
    "title": "Grocery Preferences 2026",
    "objective": "Understand grocery shopping priorities",
    "stage": "fielding",
    "shareable": false,
    "research_group_uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "research_group_url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "research_groups": [
      {
        "uuid": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
        "name": "Grocery Shoppers",
        "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0"
      },
      {
        "uuid": "02f81d1f-f23d-4a6a-a0d2-c5df90c7d681",
        "name": "Weekly Delivery Buyers",
        "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/02f81d1f-f23d-4a6a-a0d2-c5df90c7d681"
      }
    ],
    "share_url": null,
    "share_link": null,
    "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/studies/aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa",
    "participant_count": 20,
    "question_count": 3,
    "created_at": "2026-01-06T13:28:42Z",
    "updated_at": "2026-01-06T13:45:10Z"
  }
}
```

## Delete a Study (Response)

```json
{
  "ok": true,
  "deleted_id": 812,
  "deleted_uuid": "aa1d9b2f-9f0f-4b48-8e3a-0c2c7f5f23aa"
}
```

## Ask a Question (Queued)

```json
{
  "status": "queued",
  "job_ids": ["rq:job:9f8a1..."],
  "study_id": 812,
  "question_id": 4421,
  "agent_ids": [9012],
  "agents": [
    {
      "id": 9012,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9012"
    }
  ]
}
```

## List Questions with Answers

```json
{
  "study_id": 812,
  "study_title": "Grocery Preferences 2026",
  "count": 1,
  "questions": [
    {
      "id": 4421,
      "study_id": 812,
      "question": "What matters most when choosing a grocery store?",
      "optimized_question": "What matters most when choosing a grocery store?",
      "created_at": "2026-01-06T13:30:01Z",
      "updated_at": "2026-01-06T13:30:01Z",
      "answer_count": 1,
      "answers": [
        {
          "id": 9001,
          "study_id": 812,
          "question_id": 4421,
          "submitted_at": "2026-01-06T13:31:11Z",
          "response_text": "Convenience and price are the biggest drivers for me.",
          "agent_id": 9012,
          "agent_uuid": "agent_123abc",
          "agent_name": "Alex Parker",
          "agent_age": 35,
          "agent_city": "Chicago",
          "agent_state": "IL",
          "agent_country": "US",
          "agent_location": "Chicago, IL, US",
          "agent_occupation": "Account manager",
          "agent_summary": "Working parent who shops twice a week.",
          "agent_elevenlabs_voice_id": null,
          "agent_image": "/api/small_media/agent_123abc",
          "audio_file_id": null
        }
      ]
    }
  ]
}
```

## Complete a Study (Queued)

```json
{
  "job_ids": ["rq:job:1a2b3c...", "rq:job:4d5e6f..."],
  "queued_steps": [
    "study_correlations",
    "study_recommendations",
    "study_research_summary",
    "study_tldr"
  ]
}
```

## Completion Job (Finished)

```json
{
  "status": "finished",
  "result": {
    "overall_summary": "Price and convenience are the dominant decision drivers.",
    "key_segments": [
      {
        "segment": "Budget-focused households",
        "insight": "Promotions and predictable pricing drive choice."
      }
    ],
    "divergences": [
      {
        "topic": "Delivery fees",
        "split": "Some participants pay for convenience; others avoid all added fees."
      }
    ],
    "shared_mindsets": [
      {
        "value": "Time savings"
      }
    ],
    "next_questions": [
      "How much fee is acceptable for same-day delivery?"
    ],
    "stats": {
      "participant_count": 10,
      "answered_count": 10
    }
  },
  "error": null,
  "meta": {}
}
```

## Group Question Job (Finished, Sparse Result Example)

```json
{
  "status": "finished",
  "result": {
    "agent_id": null,
    "response_text": ""
  },
  "error": null,
  "meta": {}
}
```

In this case, use question-listing endpoints to retrieve persisted answer content.

## Share a Study

```json
{
  "enabled": true,
  "url": "https://app.example.com/share/abc123",
  "token": "abc123",
  "expires_at": null,
  "is_expired": false
}
```

The `url` is a public share link. Anyone with the link can view the generated report.

Optional UTM conventions:

- `?utm_source=ce` for cold/programmatic email links
- `?utm_source=blog` for blog/content links

## Error: Invalid Filters (`400`)

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid filters",
    "details": {
      "filters": {
        "ethnicity": ["unsupported value; use an exact documented value"]
      }
    }
  }
}
```

## Error: Missing Scope (`403`)

```json
{
  "error": {
    "code": "forbidden",
    "message": "Forbidden"
  }
}
```

## Error: Invalid Completion Step (`400`)

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Unknown step(s)",
    "details": {
      "steps": ["study_magic"]
    }
  }
}
```

## MCP: Remove Agents From a Group

```json
{
  "tool": "v1.research-groups.agents.remove",
  "arguments": {
    "group_id": "3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
    "agent_ids": [9012, 9013]
  }
}
```

```json
{
  "group_id": 124,
  "group_url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/research_group/3b9f2c0a-5c1c-4c5a-a2c1-8d59b2f1a6f0",
  "removed_agent_ids": [9012, 9013],
  "removed_agents": [
    {
      "id": 9012,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9012"
    },
    {
      "id": 9013,
      "url": "https://cat.fish.dog/organization/8b1a996a-0ce7-4e08-b8f4-264dbf2f8cf7/agent/9013"
    }
  ],
  "removed_count": 2
}
```