CSAM Hash Database API¶

Older endpoint notes

Rendered from ProjectInfo/api-docs/media/csam-db.md on docs/encryption-modes-spec. These notes predate the REST API reference, which is canonical wherever the two overlap. They are published because they still cover endpoints the reference does not yet document — check shapes against the reference and the spec errata.

Distributes the NCMEC hash database to clients for local scanning.

All endpoints require Authorization: Bearer <token>.

Status: Database is currently stub data. Real NCMEC hashes pending Technology Coalition membership.

GET /media/csam/manifest¶

Get metadata about the downloadable CSAM hash database.

Response 200:

{
  "version": "string",
  "size": 12345,
  "download_token": "jwt-string",
  "client_key": "base64-encoded-key"
}

download_token: short-lived JWT for the download endpoint
client_key: AES key to decrypt the hash DB

GET /media/csam/hashdb?token={download_token}¶

Download the encrypted CSAM hash database.

Response: Encrypted binary database

Decrypt with client_key from the manifest (AES-256-GCM).

Client Usage¶

Clients MAY implement local scanning before displaying received images/videos. Optional — server always scans server-side.

1. GET /media/csam/manifest
2. GET /media/csam/hashdb?token={download_token}
3. Decrypt with client_key
4. Cache locally (update when version changes)
5. Before displaying image: compute pHash
6. Compare against DB (no network call)
7. Match → blur + warning + [Report] button

Report matches via POST /api/reports/csam after user consent.
See csam-reports.md.