Build on
good records.

A consistent API for DVD release metadata. Search titles, connect credits, and contribute what’s missing.

Base URL https://api.blvckout.foo/v1 (also available at https://blvckout.foo/api/v1)

Authentication

Create a key from your account. Send it in the Authorization header. Read keys search and retrieve releases. Write keys also submit changes and require contributor rights.

Authorization: Bearer YOUR_API_KEY

Keys expire after 30, 90 or 365 days and can be revoked immediately. Keep server keys out of public source code and never place keys in URLs.

Find the right release.

curl 'https://blvckout.foo/api/v1/releases?q=your+title' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "items": [],
  "total": 0,
  "page": 1,
  "limit": 24,
  "pages": 0
}

One record. All the essentials.

{
  "id": "release-uuid",
  "title": "Release title",
  "year": 2026,
  "studio": "Studio name",
  "genres": ["Genre"],
  "performers": ["Performer name"],
  "front_cover": "https://source.example/front.jpg",
  "back_cover": "https://source.example/back.jpg",
  "source_url": "https://source.example/release",
  "barcode": "",
  "notes": "",
  "version": 1,
  "created_at": "2026-01-01 12:00:00",
  "updated_at": "2026-01-01 12:00:00"
}

Example values above illustrate the schema. Missing image URLs and text fields are empty strings. A missing year is null. Dates are UTC. Cover URLs point to external hosts; availability and permissions remain with the source.

Contribute a release.

Requires a write key and contributor rights. Send the metadata object below as JSON. All submissions enter the review queue; an API response does not mean a release is already published.

curl 'https://blvckout.foo/api/v1/releases' \
  -H 'Authorization: Bearer YOUR_WRITE_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Release title","studio":"Studio name",
    "genres":[],"performers":[],"front_cover":"",
    "back_cover":"","source_url":"","barcode":"","year":null}'

{"id":"submission-uuid","status":"pending","message":"Submitted for review."}

Edit an existing release

Send {"base_version":1,"data":{…complete metadata…}}. The base version must match the current release. A conflicting revision returns HTTP 409. Edits also require moderation.

Import a reviewed batch.

Requires a write key and contributor rights. Send {"releases":[…metadata objects…]}, with 1–20 releases per request and a body of at most 512 KiB. Responses contain one result per source: pending, duplicate or error. Existing and already queued source URLs are skipped. Up to 40 batch requests are allowed per account per hour. Published data still requires moderator approval.

Limits & errors

120 requests per minute per API key, with an additional 240-request per-IP limit. Write submissions are limited to 60 per account per hour. Keep request bodies below 64 KiB. Responses are JSON.

For the authenticated account identity, use GET /api/v1/me. Browser integrations may use Bearer authentication with CORS; session cookies are not accepted as API keys.