# API reference

> Ur Next Door API v1 reference: base URL, authentication, request and response envelopes, headers, and every endpoint grouped by area.

Source: https://docs.urnextdoor.com/reference/

The reference pages are generated from the [OpenAPI document](https://docs.urnextdoor.com/reference/openapi.md), so they always match the API. This page covers what every endpoint shares.

- [Account endpoints](https://docs.urnextdoor.com/reference/account.md): who am I, today's usage, and the OpenAPI document.
- [Content endpoints](https://docs.urnextdoor.com/reference/content.md): create posts, questions, polls, MCQs, communities, services and jobs.
- [Media endpoint](https://docs.urnextdoor.com/reference/media.md): upload an image as base64 JSON or multipart.
- [Scheduling endpoints](https://docs.urnextdoor.com/reference/scheduling.md): list, reschedule, publish now and cancel scheduled items.
- [Lookup endpoints](https://docs.urnextdoor.com/reference/lookups.md): communities, service categories, job options, places and icons.
- [OpenAPI specification](https://docs.urnextdoor.com/reference/openapi.md): the machine readable contract and how to import it.

## Base URL

```text
https://urnextdoor.com/api/v1
```

Always the apex domain. A community subdomain answers `421 wrong_host`. All paths in the reference are relative to this URL.

## Authentication

Send your key in `Authorization: Bearer und_sk_...` or `X-API-Key: und_sk_...`. Never in the URL. See [Authentication](https://docs.urnextdoor.com/getting-started/authentication.md).

## Requests

- Bodies are JSON objects with `Content-Type: application/json`, up to 256 KB. `POST /media` also accepts `multipart/form-data`, and its JSON body may be up to 12 MB (for base64 images).
- Content bodies (`body`, a community's `description`) are HTML. See [Formatting](https://docs.urnextdoor.com/guides/formatting.md).
- Times are ISO 8601 with an offset or `Z`. Scheduling stores UTC and responses use `Z`.
- Ids are numbers. Slugs and usernames are strings.
- `POST` and `DELETE` accept an optional `Idempotency-Key` header. See [Idempotency](https://docs.urnextdoor.com/idempotency.md).

## Successful responses

Every success is a JSON object that starts with `"ok": true` and ends with the `request_id`. Responses that describe an item with a `url` also carry `web_url`, the full address to open or share.

```json
{
  "ok": true,
  "id": 41,
  "slug": "five-easy-ways-to-save-water-at-home",
  "url": "/posts/five-easy-ways-to-save-water-at-home",
  "web_url": "https://urnextdoor.com/posts/five-easy-ways-to-save-water-at-home",
  "item": { "id": 41, "type": "post", "slug": "five-easy-ways-to-save-water-at-home" },
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Error responses

Every error, whatever the `Accept` header, is:

```json
{
  "ok": false,
  "error": "title and body are required",
  "code": "validation_failed",
  "errors": { "body": "Body is required." },
  "request_id": "a1b2c3d4e5f60718"
}
```

`errors` appears only on validation failures, with one message per field. Codes and what to do about each are on [Errors](https://docs.urnextdoor.com/errors.md).

## Headers

| Header | Direction | When | Meaning |
| --- | --- | --- | --- |
| `Authorization` or `X-API-Key` | Request | Every call except the OpenAPI document | Your key |
| `Content-Type` | Request | Calls with a body | `application/json`, or `multipart/form-data` for media |
| `Idempotency-Key` | Request | Optional on `POST` and `DELETE` | Makes a retry safe |
| `X-Request-Id` | Response | Every response | The request's id, also in the body as `request_id` |
| `Cache-Control: no-store` | Response | Every API response except the OpenAPI document | Never cache answers |
| `X-RateLimit-Limit` | Response | Quota-counted calls | Today's limit for that action |
| `X-RateLimit-Remaining` | Response | Quota-counted calls | What is left today |
| `X-RateLimit-Reset` | Response | Quota-counted calls | Unix seconds of the next UTC midnight |
| `Retry-After` | Response | `429` | Seconds to wait |
| `Idempotent-Replayed: true` | Response | A replayed answer | You got the stored answer of an earlier identical request |

## Versioning

The version is in the path (`/api/v1`). Write clients that ignore response fields and error codes they do not recognise, so a new optional field never breaks them. Every change is listed in the [changelog](https://docs.urnextdoor.com/changelog.md).