total2257 API

API version 2 · machine-readable spec: /openapi.json · interactive reference: /docs · /redoc

This is how compliance records get into total2257.com, where the compliance team reviews them. A record describes one production: its performers, their identity documents and the paperwork behind them. Records can come from any company workflow; each sends them in the one format described here.

When a workflow finishes a production's paperwork, it sends the record here. The API checks that every performer was 18 or older on their production date, stores the record under a new id, and answers with a verdict per performer. Failing records show up on the compliance team's to-do list at total2257.com.

Quick start

curl -s https://api.total2257.com/records \
     -H "Authorization: Bearer $API_TOKEN" \
     -F record=@record.json \
     -F pdf=@packet.pdf \
     -F id-1.jpg=@id-1.jpg -F id-2.jpg=@id-2.jpg
# -> 202 {"id": "0d6c…", "status": "queued", "queue_position": 1, "verdict_pass": true, "performers": [...]}
#    Location: /records/0d6c…

Every call needs Authorization: Bearer <token> except /healthz, this page, /docs, /redoc and /openapi.json.

Endpoints

The request

POST /records takes multipart/form-data:

Every request creates a new record with its own id. Give each one a ref_id (with its source) and sending the same one twice is refused with 409, so retrying is always safe.

The record

Dates are YYYY-MM-DD. When a document gives a date any other way, put its text in the matching *_raw field instead (or as well). Required: title, studio, production_dates and performers; everything else is optional. The full schema is in /docs.

{
  "ref_id": "your own reference",
  "source": "2257ex-api",
  "title": "Example Movie 5",
  "studio": "Example Studio",
  "production_dates": ["2024-05-04", "2024-05-05"],
  "metadata": { "scene": "3" },
  "performers": [{
    "stage_names": ["Example Name"],
    "legal_name": "…",
    "date_of_birth": "1999-02-16",
    "production_dates": ["2024-05-04"],
    "id_documents": [{
      "type": "driver license", "number": "…", "legal_name": "…",
      "date_of_birth": "1999-02-16", "expires": "2027-02-16",
      "page": 14, "image": "id-1.jpg"
    }],
    "documents": [{ "kind": "model release", "pages": [10], "form_date": "2024-05-04" }],
    "notes": "…"
  }],
  "pages": [{ "page": 1, "what": "model release" }],
  "files": [{ "name": "release.pdf", "pages": [1, 2] }]
}

The response

202 Accepted comes back as soon as the record is received and checked; there is nothing more to send. Storing it happens shortly after, in order: GET /records/{id} says when it is stored.

{"id": "0d6c1f7e-…", "status": "queued", "queue_position": 1, "verdict_pass": false,
 "performers": [{"idx": 1, "verdict": "pass"}, {"idx": 2, "verdict": "under_18"}]}

Following it: GET /records/{id} answers status queued or storing (ask again after Retry-After, 30 seconds), then stored with the full record. In the rare case it says failed, the record could not be stored: send it again.

Verdicts

The youngest ID reading governs: disagreeing ID documents pass only when every reading does.

Errors

Every error is RFC 9457 application/problem+json: {"type", "title", "status"}, plus detail on 4xx and 503. detail names the field at fault and never quotes what you sent.

Limits