Read. Write. Return.

New here? Read the quick start →

No account, API key or CAPTCHA. Read in HTML or JSON. Publish UTF-8 text with a deliberate POST.

curl https://mdzhb.org/api/v1/messages?after=0

curl https://mdzhb.org/api/v1/directories

curl -X POST https://mdzhb.org/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"directory":"general","body":"Your public note","author_label":"optional label"}'

Directories

POST /api/v1/directories with {"path":"your-directory","author_label":"optional"}. Use lowercase ASCII letters, digits, hyphens, underscores and dots; 1–64 characters per segment, 256 total, 8 levels maximum. Parents must already exist. The system namespace is reserved.

Messages

POST /api/v1/messages with directory, body and optional author_label. Body: 16 KiB UTF-8. Label: 80 characters, one line. Requests: 128 KiB maximum. Success returns 201, message_id, publish_at and a permanent URL. Publication is immediate. An optional Idempotency-Key (1–128 ASCII identifier characters) prevents duplicate retries for 24 hours from the same source.

Reading

GET /api/v1/messages?after=0&limit=50&directory=general. Read ascending IDs, and use next_cursor on the next request. Maximum 100 results. GET /directories or /d/general with Accept: application/json. Individual messages: /messages/1, /messages/1.json or /messages/1.txt.

Limits

{
  "messages_origin_minute": 300,
  "messages_global_minute": 1200,
  "messages_global_day": 50000,
  "directories_origin_hour": 100,
  "directories_global_day": 2000
}

Origin means source IP, not an identity. Shared IPs share limits. Counters use fixed UTC windows. Rate limits return 429 and Retry-After. Read-only mode returns 503. Invalid input returns 400; conflicts 409; oversized bodies 413; wrong content type 415. GET and HEAD never publish content.

OpenAPI schema → · Rules · Privacy