Create Report — Moevox API

Submit a research question and candidate options. Returns a request_id to poll.

Endpoint

POST /api/v1/reports

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer moe_sk_live_…`
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`question`	string	Yes	The research question you want validated. 1–2000 characters.
`options`	string[]	Yes	The candidate options to compare (2–20 items, each ≤200 characters, no duplicates). The pipeline optimizes the question and options before designing the questionnaire.
`sample_size`	integer	No	Number of respondents to sample. 50–1000, defaults to 100. One credit per respondent.
`audience_description`	string	No	Optional target audience, e.g. “SaaS product managers in the US” (≤2000 characters). When omitted, the audience is inferred from the question.
`language`	string	No	Report language: `en`, `es`, or `zh`. Defaults to `en`.
`no_open_text`	boolean	Defaults to `false`. When `true`, the questionnaire is generated without any open-text question, so sampling runs two calls per respondent instead of three and no open-text theme analysis is needed — a faster run. The report then returns an empty `open_text_themes` and no verbatim answers.
`fast_questionnaire`	boolean	Defaults to `false`. When `true`, the questionnaire keeps only the fixed core questions the report needs — `winner`, `driver`, and `risk_structured` — and sampling reuses stored respondent profiles without the extra AI enrichment call. This is the fastest mode. It also implies `no_open_text`, and the report has no support findings and no open-text themes.

Example

curl

curl -X POST https://api.moevox.com/api/v1/reports \
  -H "Authorization: Bearer moe_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which pricing plan should we launch first?",
    "options": ["Monthly $29", "Monthly $49", "Annual $299"],
    "sample_size": 100,
    "audience_description": "SaaS founders in the US",
    "language": "en",
    "no_open_text": false,
    "fast_questionnaire": false
  }'

Example — faster run without open-text questions

Sampling runs three AI calls per respondent by default. Set no_open_text to true to drop the open-text question, so each respondent needs two calls (and with an English report and a configured Jev key, no Gemini call at all). The questionnaire then has no open-text question and the report returns an empty open_text_themes with no verbatim answers.

curl

curl -X POST https://api.moevox.com/api/v1/reports   -H "Authorization: Bearer moe_sk_live_your_key_here"   -H "Content-Type: application/json"   -d '{
    "question": "Which pricing plan should we launch first?",
    "options": ["Monthly $29", "Monthly $49", "Annual $299"],
    "sample_size": 100,
    "no_open_text": true
  }'

Example — fastest run with the reduced questionnaire

Set fast_questionnaire to true when speed matters more than depth. The questionnaire is reduced to the three fixed core questions the report needs, and sampling skips the extra AI call that fills in missing respondent-profile attributes. The trade-off: the report has no support findings and no open-text themes.

curl

curl -X POST https://api.moevox.com/api/v1/reports   -H "Authorization: Bearer moe_sk_live_your_key_here"   -H "Content-Type: application/json"   -d '{
    "question": "Which pricing plan should we launch first?",
    "options": ["Monthly $29", "Monthly $49", "Annual $299"],
    "sample_size": 100,
    "fast_questionnaire": true
  }'

Response — 202 Accepted

Response body

{
  "request_id": "req_4f3a9c21e8b7d6c5",
  "status": "queued",
  "credits_estimated": 100,
  "credits_left": 875
}

Response fields

Field	Type	Description
`request_id`	string	Poll this ID with `GET /api/v1/reports/{request_id}`.
`status`	string	Always `queued` at submission.
`credits_estimated`	integer	The requested sample size. The exact usage is settled when the report completes.
`credits_left`	integer	Your balance at submission time.

Errors

Status	When
`401`	Missing, invalid, or revoked API key.
`402`	Insufficient credits. Response includes `credits_left`.
`400`	Validation failed: missing `question`, invalid `options` (count, length, or duplicates), out-of-range `sample_size`, or unsupported `language`.