API Documentation

Public REST API for daily domain snapshots. Latest-only files (see Domain Data API), Bearer token auth, streaming gzip/zip. Base URL https://primitive.host/api/v1.

Overview

Daily snapshots refreshed once per day (02:00 UTC). The API lists available zones and streams the latest files — one domain per line, sorted and deduplicated, gzip-compressed. Files are overwritten daily and always represent the latest data — no history or date parameters.

Base URL: https://primitive.host/api/v1
Auth: Authorization: Bearer ph_… (create in Account Settings)
Latest-only: no ?date= — use the /dl download endpoints

Authentication

Create a token in Account Settings → API Tokens (shown once, format ph_…). Send Authorization: Bearer ph_… with every request. Missing or invalid token → 401 {"error": …}.

curl -H "Authorization: Bearer ph_YOUR_TOKEN" https://primitive.host/api/v1/zones/

Zones

GET /api/v1/zones/ auth

List all zones with type (public or private) and domain counts. Includes last_run timestamp. 409 {"error":"No snapshots…"} if not yet generated. Rejects query params.

curl -H "Authorization: Bearer ph_…" https://primitive.host/api/v1/zones/ # {"zones":[{"name":"com","suffix_type":"public","domains":123456},…],"last_run":1714000000}

GET /api/v1/zones/{zone}/

Detail for one zone. 404 if unknown.

GET /api/v1/zones/{zone}/dl/ stream

Download the zone file — gzip-compressed text, one domain per line, sorted and deduplicated. 404 if not yet available.

curl -H "Authorization: Bearer ph_…" https://primitive.host/api/v1/zones/com/dl/ -o com.txt.gz

New domains

GET /api/v1/new/

Metadata for today’s new domains: size and last_modified. 404 if not yet generated.

GET /api/v1/new/dl/ stream

Download today’s new domains as a gzip-compressed file.

Expired domains

GET /api/v1/expired/

Metadata for today’s expired domains: size and last_modified. 404 if not yet available.

GET /api/v1/expired/dl/ stream

Download today’s expired domains as a gzip-compressed file.

All zones bundle

GET /api/v1/all/dl/ stream

Download a ZIP containing every zone file — one .txt.gz per zone.

curl -H "Authorization: Bearer ph_…" https://primitive.host/api/v1/all/dl/ -o all.zip

Errors & limits

401 — missing, invalid or revoked token
404 — unknown zone or file not yet generated
409 — /zones/ empty state before first snapshot
No pagination — zone files are pre-sorted; use the download endpoints for bulk data.

Examples

List then download

TOKEN=ph_xxx curl -H "Authorization: Bearer $TOKEN" https://primitive.host/api/v1/zones/ | jq '.zones[0]' curl -H "Authorization: Bearer $TOKEN" https://primitive.host/api/v1/zones/ru.com/dl/ -o ru.com.txt.gz gunzip -c ru.com.txt.gz | head

Check token

curl -i -H "Authorization: Bearer $TOKEN" https://primitive.host/api/v1/zones/ | head -1 # HTTP/1.1 200 or 409 → valid; 401 → invalid

Tokens: Account Settings → API Tokens (top section, shown once).