Menu Ur Next DoorAPI Docs Get an API key

Use the API with cURL

Call the Ur Next Door API from the command line with cURL: a reusable shell helper, JSON bodies from files, reading headers, jq, and Windows notes.

View as Markdown

cURL is installed on macOS, Linux and Windows 10 or later. Every example in these docs has a cURL tab; this page collects the habits that make it pleasant.

Set the key once

Shell
read -rs UND_API_KEY && export UND_API_KEY

Every command below uses $UND_API_KEY, so the key never appears in your history.

A small helper

Put this in your shell profile to stop repeating the base URL and headers:

Shell
und() {
  local method="$1" path="$2"
  shift 2
  curl -sS -X "$method" "https://urnextdoor.com/api/v1$path" \
    -H "Authorization: Bearer $UND_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    "$@"
}

Then:

Shell
und GET /me
und GET /usage
und POST /posts -d @post.json
und GET "/geo?level=states&country=IN"

The API ignores Idempotency-Key on GET. For a retry that must reuse the same key, call curl directly with a fixed value instead of the helper.

Keep bodies in files

Quoting JSON on the command line is error prone, especially HTML with quotes. Write the body to a file and send it with -d @file:

post.json
{
  "title": "Five easy ways to save water at home",
  "body": "<p>Small habits add up.</p><ul><li>Fix dripping taps the same week.</li></ul>",
  "tags": ["water", "home"]
}
Shell
und POST /posts -d @post.json

For large bodies, such as a base64 image, use --data-binary @upload.json so cURL sends the file exactly as it is. See Upload images.

The full request, without the helper

cURL
curl -X POST "https://urnextdoor.com/api/v1/posts" \
  -H "Authorization: Bearer $UND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Five easy ways to save water at home",
  "body": "<p>Small habits add up. These five saved our building a lot of water this summer.</p><ul><li>Fix dripping taps the same week.</li><li>Run the washing machine only when it is full.</li></ul>",
  "tags": [
    "water",
    "home"
  ]
}'
JavaScript
const res = await fetch("https://urnextdoor.com/api/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "Five easy ways to save water at home",
    body: "<p>Small habits add up. These five saved our building a lot of water this summer.</p><ul><li>Fix dripping taps the same week.</li><li>Run the washing machine only when it is full.</li></ul>",
    tags: ["water", "home"],
  }),
});
console.log(res.status, await res.json());
Python
import os
import uuid

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.post(
    "https://urnextdoor.com/api/v1/posts",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "title": "Five easy ways to save water at home",
        "body": "<p>Small habits add up. These five saved our building a lot of water this summer.</p><ul><li>Fix dripping taps the same week.</li><li>Run the washing machine only when it is full.</li></ul>",
        "tags": ["water", "home"],
    },
    timeout=30,
)
print(response.status_code, response.json())
PHP
<?php
$apiKey = getenv('UND_API_KEY');

$payload = [
    'title' => 'Five easy ways to save water at home',
    'body' => '<p>Small habits add up. These five saved our building a lot of water this summer.</p><ul><li>Fix dripping taps the same week.</li><li>Run the washing machine only when it is full.</li></ul>',
    'tags' => ['water', 'home'],
];

$ch = curl_init('https://urnextdoor.com/api/v1/posts');
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": 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"
}

Read headers and pick fields

Shell
# Show response headers too (quota, request id)
curl -sS -D - "https://urnextdoor.com/api/v1/usage" -H "Authorization: Bearer $UND_API_KEY"

# With jq installed: print only the link of a new post
und POST /posts -d @post.json | jq -r '.web_url'

-D - prints headers such as X-Request-Id and, on creates, X-RateLimit-Remaining.

Windows

In PowerShell, call curl.exe (plain curl may be an alias for a different command in older Windows PowerShell), and keep bodies in files:

POWERSHELL
curl.exe -sS -X POST "https://urnextdoor.com/api/v1/posts" `
  -H "Authorization: Bearer $env:UND_API_KEY" `
  -H "Content-Type: application/json" `
  -H "Idempotency-Key: $([guid]::NewGuid())" `
  --data-binary "@post.json"

uuidgen is not available on Windows; [guid]::NewGuid() does the same job.

Next steps

Last updated