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`.

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"
  }'

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`.