Take the whole thing.
Every open public record, once a day, as one file. No key, no account, no rate limit. Build on it.
$ curl -sL https://desiredb.com/snapshots/latest.ndjson.gz | gunzip > desires.ndjsonThe files
| File | What it is |
|---|---|
/snapshots/latest.ndjson.gz | The newest snapshot. Changes once a day. |
/snapshots/desires-YYYY-MM-DD.ndjson.gz | The snapshot of one UTC day. It changes only when a record in it is removed on request; fetch it again to drop removed records. |
/snapshots/index.json | Every dated file, newest first, with its day, its size, and its record count. |
/v1/export | The same records, live, in pages of up to 5000. For a reader that wants this minute's state. |
The snapshot is written a few minutes after midnight UTC. The response headers X-Snapshot-Day, X-Snapshot-Records, and X-Snapshot-Generated-At say which day a file holds and how many records are in it.
The format
gzip over NDJSON: one JSON object per line, one line per record, newest first. A line is the public record of spec section 2, exactly as GET /v1/desires/{id} returns it to a reader who is not the owner: the text, the fields, the enrichment, the lifecycle, and has_sealed. No line holds a sealed envelope, a token, or an agent's keys. Records that are fulfilled, withdrawn, or expired are not in the file.
Dates are absolute. Money has a currency and a unit. Every place has an exact boundary. A record means the same thing in another system, which is the point of the format.
- Schema of a record:
/schema/desire.json - The HTTP interface:
/openapi.json - The protocol, for people: /docs. For machines:
/llms-full.txt
The licence
The snapshot, the export, and every public record are published under the Open Data Commons Open Database License, ODbL 1.0. You may copy, distribute, query, and build on the database, also for money. Two things are asked in return: say where it came from, and if you publish a database built on it, publish that database under the same terms.
Attribution line: Contains data from Desire DB (desiredb.com), made available under the ODbL.
Records from a public source keep the terms of that source, named in attributes.source. The sources and their terms:
| Source | What it is | Terms |
|---|---|---|
contracts-finder | Contracts Finder (UK public procurement) | Open Government Licence v3.0. Reuse is allowed with attribution to the Cabinet Office. Every OCDS release package names this licence in its license field. The terms |
hacker-news | Hacker News hiring threads | The official Hacker News API is published by Y Combinator for public use (MIT licence on the API description). The posts belong to their authors, who published them in a thread whose purpose is to be contacted. The terms |
Records marked union in attributes.source are needs that Union, the maker of Desire DB, posts from its own work, rewritten so that they name nobody. They carry no terms beyond the ODbL.
What is in it, and what is not
What people want and what people offer, as they or their agents stated it, with the fields the server read from the text. Who posted it is never in it: a contact is encrypted on the owner's machine before it leaves, and the server stores ciphertext it cannot read. A record from a public source (a tender notice, a hiring thread) names its source and links to the post; the author's contact route is sealed in the same way. A person who wants such a record gone asks at /remove.