Media endpoint

Upload an image as base64 JSON or multipart, then use the returned URL as a featured image or in a gallery.

All paths are relative to https://urnextdoor.com/api/v1. See API reference for the envelope and headers every endpoint shares.

Endpoint	What it does	Scope	Daily quota
`POST /media`	Upload an image	`media`	`media`

Upload an image

POST https://urnextdoor.com/api/v1/media

Uploads one image as JSON (base64) or multipart. It is converted to WebP and must end at 2 MB or less. Use data.url as featured_image or in gallery. Counts against the media quota.

Auth: your API key (Bearer or X-API-Key)
Scope: media
Daily quota: counts as media (see limits)
Idempotency-Key: supported (see Idempotency)
operationId: uploadMedia

Request body

JSON (`application/json`)

Field	Type	Required	Description
`image_base64`	string	Yes	The image as raw base64 or a data: URI (data:image/png;base64,...). PNG, JPEG, GIF or WebP, up to 8 MB before conversion.
`filename`	string	No	A file name such as cover.png. Used to name the stored file.
`context`	string	No	What the image is for. One of: `post`, `question`, `poll`, `mcq`, `community`, `service`, `job`, `misc`. Default: `post`.
`community`	string	No	Optional community slug to file the image under.

Multipart (`multipart/form-data`)

Field	Type	Required	Description
`file`	string	Yes	The image file.
`context`	string	No	What the image is for. One of: `post`, `question`, `poll`, `mcq`, `community`, `service`, `job`, `misc`. Default: `post`.
`community`	string	No	Optional community slug to file the image under.

Example

Base64 JSON (for AI generated images)

cURL

# Build the body in a file: a base64 image is too long for a command line argument.
printf '{"image_base64": "%s", "filename": "cover.png", "context": "post"}' \
  "$(base64 < cover.png | tr -d '\n')" > upload.json

curl -X POST "https://urnextdoor.com/api/v1/media" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @upload.json

JavaScript

import { readFile } from "node:fs/promises";

const image = await readFile("cover.png");

const res = await fetch("https://urnextdoor.com/api/v1/media", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    image_base64: image.toString("base64"),
    filename: "cover.png",
    context: "post",
  }),
});
console.log(res.status, await res.json());

Python

import base64
import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

with open("cover.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("ascii")

response = requests.post(
    "https://urnextdoor.com/api/v1/media",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "image_base64": image_base64,
        "filename": "cover.png",
        "context": "post",
    },
    timeout=30,
)
print(response.status_code, response.json())

PHP

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

$payload = [
    'image_base64' => base64_encode(file_get_contents('cover.png')),
    'filename' => 'cover.png',
    'context' => 'post',
];

$ch = curl_init('https://urnextdoor.com/api/v1/media');
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,
  "data": {
    "id": 318,
    "context": "post",
    "community_id": null,
    "url": "/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp",
    "disk_path": "aarav/post/cover_3f9a1c2b7d4e_1792054800.webp",
    "original_name": "cover.png",
    "extension": "webp",
    "mime_type": "image/webp",
    "size_bytes": 184320,
    "created_at": "2026-10-15 09:00:00",
    "updated_at": "2026-10-15 09:00:00"
  },
  "web_url": "https://urnextdoor.com/storage/aarav/post/cover_3f9a1c2b7d4e_1792054800.webp",
  "request_id": "9f8e7d6c5b4a3921"
}

Multipart file upload