REST API v1

Gather Synthetic API

Run synthetic brand, messaging, competitive, and pricing research programmatically. Integrate AI-moderated research studies into any product or workflow.

Base URLhttps://synthetic.gatherhq.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. Contact mayank@gatherhq.com to get an API key, or use your ADMIN_SECRET for internal Gather platform calls.

Header
Authorization: Bearer your_api_key_here
POST/studies

Run a study

Run a full synthetic research study. Returns structured findings when complete (30-90s).

Parameters
NameTypeRequiredDescription
topicstringyesResearch question. Be specific — 10+ characters.
study_typestringyesOne of: brand, product, concept, competitor, cx, pricing, messaging, winloss, churn, segmentation, custom
audiencestringyesb2b or b2c — determines default persona selection
persona_idsstring[]noSpecific persona IDs to interview. Max 4. See GET /personas.
n_per_personanumbernoInterviews per persona. 1-3, default 2. Total = personas × n_per_persona.
webhook_urlstringnoURL to POST study.completed event to when finished.
Request body
{
  "topic": "How do mid-market CFOs evaluate AI-powered FP&A tools?",
  "study_type": "competitor",
  "audience": "b2b",
  "persona_ids": ["p_cfo", "p_cto"],     // optional — defaults auto-selected
  "n_per_persona": 2,                     // optional — 1-3, default 2
  "webhook_url": "https://your.app/hook"  // optional — POST on completion
}
Response
{
  "id": "d80af9bb-797f-43d2-9cb3-8ac822c7d3e4",
  "status": "complete",
  "topic": "How do mid-market CFOs evaluate AI-powered FP&A tools?",
  "study_type": "competitor",
  "audience": "b2b",
  "slug": "mid-market-cfos-ai-fpa-tools-competitive-analysis",
  "report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
  "headline_finding": "CFOs trust vendors who lead with ROI proof...",
  "executive_summary": "...",
  "overall_confidence": 68,
  "avg_sentiment": 6.2,
  "key_findings": [
    {
      "finding": "...",
      "evidence": "...",
      "implication": "...",
      "strength": "strong"
    }
  ],
  "opportunity": "...",
  "risk": "...",
  "messaging_implications": ["...", "..."],
  "quant": { "projected_nps": 32, ... },
  "created_at": "2026-03-25T14:30:00Z"
}
GET/studies

List studies

List completed studies with pagination and filtering.

Parameters
NameTypeRequiredDescription
limitnumbernoResults per page. Default 20, max 100.
offsetnumbernoPagination offset. Default 0.
study_typestringnoFilter by study type.
audiencestringnoFilter by audience: b2b or b2c.
Response
{
  "studies": [
    {
      "id": "d80af9bb-...",
      "topic": "...",
      "study_type": "brand",
      "audience": "b2c",
      "slug": "starbucks-brand-perception-brand-study",
      "report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
      "headline_finding": "...",
      "overall_confidence": 68,
      "avg_sentiment": 6.5,
      "created_at": "2026-03-25T14:30:00Z"
    }
  ],
  "total": 48,
  "limit": 20,
  "offset": 0
}
GET/studies/:id

Get study

Retrieve full study results including synthesis, quant data, and all interview transcripts.

Parameters
NameTypeRequiredDescription
idstringyesStudy UUID
Response
{
  "id": "d80af9bb-...",
  "status": "complete",
  "topic": "...",
  "headline_finding": "...",
  "executive_summary": "...",
  "key_findings": [...],
  "consensus_themes": [...],
  "opportunity": "...",
  "risk": "...",
  "competitive_signals": [...],
  "decision_criteria": [...],
  "messaging_implications": [...],
  "research_agenda": [...],
  "quant": { ... },
  "interviews": [
    {
      "persona_id": "p_cfo",
      "persona_name": "James L.",
      "persona_role": "CFO",
      "transcript": [
        { "q": "...", "a": "..." }
      ],
      "analysis": {
        "sentiment": "mixed",
        "sentiment_score": 5.5,
        "key_themes": [...],
        "standout_quote": "...",
        ...
      }
    }
  ]
}
GET/personas

List personas

Get all available synthetic personas with demographics and traits.

Response
{
  "b2b": [
    {
      "id": "p_cmo",
      "name": "Priya S.",
      "age": 41,
      "role": "CMO",
      "company": "Enterprise Retail",
      "industry": "Enterprise",
      "income": "$240k",
      "location": "New York, NY",
      "traits": ["brand-conscious", "board pressure", "agency veteran"]
    },
    ...
  ],
  "b2c": [...],
  "defaults": {
    "b2b": ["p_cmo", "p_cto", "p_cfo", "p_vp_mktg"],
    "b2c": ["p_millennial_mom", "p_gen_z", "p_high_income", "p_budget"]
  }
}
GET/study-types

List study types

Get all available study types with descriptions.

Response
{
  "study_types": [
    {
      "id": "brand",
      "label": "Brand Perception",
      "description": "How audiences perceive a brand — affinity, trust, associations.",
      "default_audience": "b2c"
    },
    ...
  ]
}

Errors

All errors return a JSON body with error and message fields.

StatusError codeWhen
400invalid_topictopic is missing or under 10 characters
400invalid_study_typestudy_type is not a recognized value
400invalid_audienceaudience is not 'b2b' or 'b2c'
400invalid_jsonRequest body is not valid JSON
401unauthorizedMissing or malformed Authorization header
403invalid_keyAPI key is not recognized
404not_foundStudy ID does not exist
500research_failedStudy execution failed (timeout, model error)

Webhooks

Pass a webhook_url when creating a study. We'll POST to it when the study completes:

Webhook payload
{
  "event": "study.completed",
  "study_id": "d80af9bb-...",
  "report_url": "https://synthetic.gatherhq.com/report/d80af9bb-...",
  "topic": "...",
  "study_type": "brand",
  "audience": "b2c"
}

Rate limits & pricing

Studies take 30-90 seconds to complete. The API is synchronous — the response includes the full results.

Pricing: B2C interviews $0.50 each, B2B interviews $5.00 each. Default study = 4 personas × 2 interviews = 8 interviews. A B2B study costs ~$40, a B2C study costs ~$4.

Rate limit: 10 concurrent studies per API key. Contact us for higher limits.

Quick start

cURL
curl -X POST https://synthetic.gatherhq.com/api/v1/studies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "How do consumers perceive Starbucks after recent controversies?",
    "study_type": "brand",
    "audience": "b2c"
  }'
JavaScript / TypeScript
const res = await fetch("https://synthetic.gatherhq.com/api/v1/studies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    topic: "How do consumers perceive Starbucks after recent controversies?",
    study_type: "brand",
    audience: "b2c",
  }),
});

const study = await res.json();
console.log(study.headline_finding);
console.log(study.report_url);
Python
import requests

res = requests.post(
    "https://synthetic.gatherhq.com/api/v1/studies",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "topic": "How do consumers perceive Starbucks after recent controversies?",
        "study_type": "brand",
        "audience": "b2c",
    },
)

study = res.json()
print(study["headline_finding"])
print(study["report_url"])

Data disclaimer

Synthetic data: All research uses AI-generated synthetic respondents — not real humans. Findings are directional signal with ±15-20% margin of error. Treat as hypotheses to validate.

Brand independence: Studies mentioning brands are independent research, not affiliated with or endorsed by those brands.

Primary research: For real human respondents, use gatherhq.com.