# Create an MCQ

> Create a multiple choice quiz question on Ur Next Door with the API: 2 to 5 options and a 0-based correct_option_index, now or on a schedule.

Source: https://docs.urnextdoor.com/guides/create-mcq/

An MCQ is a multiple choice quiz question with exactly one correct answer, which you mark when you create it.

**Endpoint:** `POST /api/v1/mcqs` · **Scope:** `content` · **Quota:** `mcq`

## Fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes | The quiz question (plain text). |
| `options` | array of string | Yes | The choices: 2 to 5 unique strings. 2 to 5 items. Items must be unique. |
| `correct_option_index` | integer | Yes | The 0-based position of the correct choice in options. From 0 to 4. |
| `body` | string | No | Optional context or explanation as HTML. |
| `tags` | array of string | No | Topic tags, without the leading #. Example: ["water", "home"]. |
| `community_id` | integer | No | Post inside this community. Use an id from GET /communities/postable. You must be an editor (or above) of it. |
| `community` | string | No | Alternative to community_id: the community slug. It is resolved to its id. |
| `featured_image` | string | No | A /storage/... path returned by POST /media (data.url), or any https:// image URL (linked, not copied). |
| `gallery` | array of string | No | Extra images. Each is a /storage/... path from POST /media or an https:// image URL. Up to 12 items. |
| `scheduled_at` | string (date-time) | No | Publish later instead of now. ISO 8601 with an offset or Z, at least 5 minutes and at most 180 days ahead. Stored in UTC. |

## Create an MCQ now

**cURL**

```bash
curl -X POST "https://urnextdoor.com/api/v1/mcqs" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Which planet has the shortest year?",
  "options": [
    "Venus",
    "Mercury",
    "Mars",
    "Earth"
  ],
  "correct_option_index": 1,
  "tags": [
    "science"
  ]
}'
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/mcqs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "Which planet has the shortest year?",
    options: ["Venus", "Mercury", "Mars", "Earth"],
    correct_option_index: 1,
    tags: ["science"],
  }),
});
console.log(res.status, await res.json());
```

**Python**

```python
import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.post(
    "https://urnextdoor.com/api/v1/mcqs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Which planet has the shortest year?",
        "options": ["Venus", "Mercury", "Mars", "Earth"],
        "correct_option_index": 1,
        "tags": ["science"],
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$payload = [
    'title' => 'Which planet has the shortest year?',
    'options' => ['Venus', 'Mercury', 'Mars', 'Earth'],
    'correct_option_index' => 1,
    'tags' => ['science'],
];

$ch = curl_init('https://urnextdoor.com/api/v1/mcqs');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `201 Created`

```json
{
  "ok": true,
  "id": 77,
  "slug": "which-planet-has-the-shortest-year",
  "url": "/mcqs/which-planet-has-the-shortest-year",
  "web_url": "https://urnextdoor.com/mcqs/which-planet-has-the-shortest-year",
  "item": {
    "id": 77,
    "type": "mcq",
    "slug": "which-planet-has-the-shortest-year"
  },
  "request_id": "9f8e7d6c5b4a3921"
}
```

## The correct answer is 0-based

`correct_option_index` counts from **0**. With these options:

| Position | Index | Option |
| --- | --- | --- |
| 1st | `0` | Venus |
| 2nd | `1` | Mercury |
| 3rd | `2` | Mars |
| 4th | `3` | Earth |

the correct answer Mercury is `1`, not `2`. An index outside the list answers `422 validation_failed`.

Use the optional `body` to explain the answer or give context.

## Publish a quiz set over a week

A common pattern is to schedule one MCQ a day. Send one request per question, each with its own `scheduled_at` and its own `Idempotency-Key`. The quota is counted on the day you schedule them, so 7 MCQs scheduled today use 7 of today's `mcq` quota.

**cURL**

```bash
curl -X POST "https://urnextdoor.com/api/v1/mcqs" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Which planet has the shortest year?",
  "options": [
    "Venus",
    "Mercury",
    "Mars",
    "Earth"
  ],
  "correct_option_index": 1,
  "scheduled_at": "2026-10-20T09:30:00Z"
}'
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/mcqs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "Which planet has the shortest year?",
    options: ["Venus", "Mercury", "Mars", "Earth"],
    correct_option_index: 1,
    scheduled_at: "2026-10-20T09:30:00Z",
  }),
});
console.log(res.status, await res.json());
```

**Python**

```python
import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.post(
    "https://urnextdoor.com/api/v1/mcqs",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Which planet has the shortest year?",
        "options": ["Venus", "Mercury", "Mars", "Earth"],
        "correct_option_index": 1,
        "scheduled_at": "2026-10-20T09:30:00Z",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$payload = [
    'title' => 'Which planet has the shortest year?',
    'options' => ['Venus', 'Mercury', 'Mars', 'Earth'],
    'correct_option_index' => 1,
    'scheduled_at' => '2026-10-20T09:30:00Z',
];

$ch = curl_init('https://urnextdoor.com/api/v1/mcqs');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `201 Created`

```json
{
  "ok": true,
  "id": 77,
  "slug": "which-planet-has-the-shortest-year",
  "url": "/mcqs/which-planet-has-the-shortest-year",
  "web_url": "https://urnextdoor.com/mcqs/which-planet-has-the-shortest-year",
  "status": "scheduled",
  "scheduled_at": "2026-10-20T09:30:00Z",
  "item": {
    "id": 77,
    "type": "mcq",
    "slug": "which-planet-has-the-shortest-year"
  },
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Common errors

| Status and code | Cause | Fix |
| --- | --- | --- |
| `422 validation_failed` | Missing `title`, wrong number of options, duplicates, or an index outside the options | Fix the field named in `errors` |
| `403 forbidden` | You are not an editor of that community | Post without a community |
| `429 quota_exceeded` | Today's MCQ quota is used up | Wait until 00:00 UTC |

## Next steps

- [Prompt recipes](https://docs.urnextdoor.com/ai/prompt-recipes.md) include a quiz set recipe for AI agents.
- [Manage scheduled content](https://docs.urnextdoor.com/guides/manage-scheduled.md).
- [Create a poll](https://docs.urnextdoor.com/guides/create-poll.md).