Documentation

Drafts

A reviewable poll/quiz produced by AI Generation — edit it, then publish it as a real poll or quiz, or reject it.

A draft is never public and never collects responses on its own. Publishing creates a real Poll or Quiz (matching the type you requested when generating) from the draft's current questions/options — edit it first with PATCH if you want to change anything. Any option carrying a suggested_trait_key becomes a real trait mapping on the published option, exactly as if you'd mapped it yourself in the dashboard.

Method	Endpoint	Auth	Description
GET	`/drafts/{draft}`	API key	Get a draft with its questions/options
PATCH	`/drafts/{draft}`	API key	Edit a draft (PUT also accepted)
POST	`/drafts/{draft}/publish`	API key	Publish as a real poll or quiz
POST	`/drafts/{draft}/reject`	API key	Reject — it will never be published

GET /drafts/{draft} API key

Get a draft

REQUEST

curl -H "X-API-Key: qna_..." https://qnaapi.com/api/v1/drafts/7

200 OK

{
  "data": {
    "id": 7,
    "generation_job_id": 42,
    "site_id": null,
    "type": "quiz",
    "title": "How well do you know the playoff race?",
    "description": null,
    "status": "pending_review",
    "confidence": 0.92,
    "flagged_reason": null,
    "published_poll_id": null,
    "published_quiz_id": null,
    "questions": [
      {
        "id": 21,
        "prompt": "Which team clinched the division?",
        "explanation": "The article states they clinched with a win on Sunday.",
        "position": 0,
        "confidence": 0.92,
        "is_grounded": true,
        "options": [
          { "id": 51, "label": "Team A", "is_correct": true, "suggested_trait_key": "sports_fan", "suggested_trait_value": "true", "position": 0 },
          { "id": 52, "label": "Team B", "is_correct": false, "suggested_trait_key": null, "suggested_trait_value": null, "position": 1 }
        ]
      }
    ],
    "created_at": "2026-10-02T00:00:00.000000Z",
    "updated_at": "2026-10-02T00:00:00.000000Z"
  }
}

Status	Meaning
`pending_review`	Awaiting your decision — may or may not be flagged
`published`	Published — see `published_poll_id`/`published_quiz_id`
`rejected`	Rejected — cannot be edited or published

PATCH /drafts/{draft} API key

Edit a draft

Every field is optional — send only what you want to change. questions, when sent, fully replaces the existing questions (not a merge) — a draft never has responses, so there's nothing depending on a question or option keeping its id.

Field	Type	Rules
title	string	Optional, max 255
description	string	Optional, nullable
questions	array	Optional, at least 1 when sent
questions[].prompt	string	Required
questions[].explanation	string	Optional, nullable
questions[].options	array	Required, at least 2, labels must be unique within that question
questions[].options[].label	string	Required, max 255
questions[].options[].is_correct	boolean	Quiz drafts only — at least one option per question must be `true`. Ignored for poll drafts.
questions[].options[].suggested_trait_key	string	Optional, nullable, lowercase key matching `^[a-z][a-z0-9_]{1,63}$`
questions[].options[].suggested_trait_value	string	Required if `suggested_trait_key` is set

REQUEST

curl -X PATCH https://qnaapi.com/api/v1/drafts/7 \
  -H "X-API-Key: qna_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How well do you know the playoff race?",
    "questions": [
      {
        "prompt": "Which team clinched the division?",
        "options": [
          { "label": "Team A", "is_correct": true, "suggested_trait_key": "sports_fan", "suggested_trait_value": "true" },
          { "label": "Team B", "is_correct": false }
        ]
      }
    ]
  }'

A published draft returns 409 Conflict on any edit.

POST /drafts/{draft}/publish API key

Publish a draft

REQUEST

curl -X POST -H "X-API-Key: qna_..." https://qnaapi.com/api/v1/drafts/7/publish

Returns the newly created resource — a full Quiz or Poll object (201 Created), matching the draft's type.

A draft that's already published or rejected returns 409 Conflict. There's no "unpublish" — delete the resulting poll/quiz directly if you need to take it down.

POST /drafts/{draft}/reject API key

Reject a draft

REQUEST

curl -X POST -H "X-API-Key: qna_..." https://qnaapi.com/api/v1/drafts/7/reject

Returns the draft with status: "rejected". A rejected draft cannot be edited or published.