Draft, validate and create a forecast

Creating a forecast takes two steps: save a draft, which you can replace as often as you like, then create the forecast from it, once. Drafts only check the JSON shape; POST /beta/questions runs the real checks. This is beta only.

Create a draft

This first draft is deliberately incomplete. It has no clarifications, so there are no resolution criteria yet:

curl -X POST "https://api.mantic.com/beta/question-drafts" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "When will Acme publish its audited 2027 annual report?",
    "type": "date",
    "supplementary_information": "Use the first audited annual report published by Acme."
  }'

POST /beta/question-drafts returns 201 with the new draft ID:

{ "id": 418 }

type is date, numerical or categorical; the draft API does not accept event. Every draft has title and optional supplementary_information and clarifications. The other fields depend on the type:

Type	Fields
`categorical`	`categories`: the list of outcome labels (required).
`numerical`	`range_min` and `range_max`: the lowest and highest answer.
	`open_lower_bound` and `open_upper_bound`: whether the answer can fall below `range_min` or rise above `range_max` (default `false`).
	`unit`: the unit of the answer, such as `USD`.
	`kind`: `discrete` when only certain values can occur, such as a count, or `continuous` for a measurement.
	`reporting_quantum`: the step the answer is published in, greater than `0`, such as `1` for a count or `0.25` for a policy rate. Leave it out for an average or a calculated value.
`date`	No extra fields.

See a failed creation

Creating a forecast from this draft returns 422. The draft stays unused:

curl -X POST "https://api.mantic.com/beta/questions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "question_draft_id": 418 }'

{
  "detail": "Question draft 418 has no clarifications"
}

Creation also returns 422 when a numerical draft's range, kind and reporting_quantum don't fit together.

Replace the draft

PUT replaces the whole draft. Send every field you want to keep, not only the one that changed:

curl -X PUT "https://api.mantic.com/beta/question-drafts/418" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "When will Acme publish its audited 2027 annual report?",
    "type": "date",
    "supplementary_information": "Use the first audited annual report published by Acme.",
    "clarifications": "Resolve to the publication timestamp on Acme investor relations. Use the filing timestamp if the report appears there first."
  }'

PUT /beta/question-drafts/{question_draft_id} returns 204 with no body. Read the draft back with GET /beta/question-drafts/{question_draft_id} and check its fields before you create the forecast.

Create the forecast once

Send the reviewed draft ID to POST /beta/questions:

curl -X POST "https://api.mantic.com/beta/questions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "question_draft_id": 418 }'

{ "id": 9304 }

The response is 201, and the draft is now used. id is the new forecast's question_id. Other responses:

409: the draft has already created a forecast. Sending it again never creates a duplicate.
429: you've used your forecast-creation allowance; wait Retry-After seconds.

Wait for the first run

201 only schedules the first run. Until it completes, GET /questions/{question_id} returns 404 and GET /questions leaves the forecast out. See Read a forecast's latest run.