{"openapi":"3.1.0","info":{"title":"2257 packet API","description":"POST a 2257 records packet, poll for the result. The guide is at [/](/); every field of the result is explained at [/help/result](/help/result).","version":"9"},"paths":{"/healthz":{"get":{"summary":"Liveness and queue depth","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/extractions":{"post":{"summary":"Submit a packet","operationId":"post_packet_extractions_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Submission"}}},"required":true},"responses":{"202":{"description":"Accepted. Poll the Location until done.","headers":{"Location":{"description":"/extractions/{id}","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"},"example":{"id":"9f2c4d1e00000000000000000000000000000000000000000000000000000000","status":"queued","version":9,"created":"2026-10-18T16:28:39+00:00","pages":35,"page_map":[{"file":"release.pdf","pages":[1,2,3,4]},{"file":"ID front.heic","pages":[5]},{"file":"ID back.jpg","pages":[],"excluded":"unreadable image (JPEG): Premature end of JPEG file"}],"metadata":{"title":"Example Movie 5","scene":["1","3"]}}}}},"413":{"description":"Too large: over the size or file-count limit.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Content_Too_Large0":{"value":{"type":"about:blank","title":"Content Too Large","status":413,"detail":"too many files (201 > 200)","instance":"/extractions"}}}}}},"422":{"description":"The request can't be processed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Unsupported_File0":{"value":{"type":"about:blank","title":"Unsupported File","status":422,"detail":"(request): no usable files: clip.mp4: content is not a supported file type (named .mp4)","instance":"/extractions","file":"(request)"}},"Invalid_Metadata1":{"value":{"type":"about:blank","title":"Invalid Metadata","status":422,"detail":"too many metadata keys (51 > 50)","instance":"/extractions"}},"Validation_Error2":{"value":{"type":"about:blank","title":"Validation Error","status":422,"detail":"no files: upload at least one part named 'files'","instance":"/extractions"}}}}}},"503":{"description":"The queue is full; retry after Retry-After seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Service_Unavailable0":{"value":{"type":"about:blank","title":"Service Unavailable","status":503,"detail":"queue is full (32 jobs); try again later","instance":"/extractions"}}}}}}}}},"/extractions/{job_id}":{"get":{"summary":"Poll a job; the result when done","description":"Every field of every response is explained at [/help/result](/help/result).","operationId":"get_packet_extractions__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Queued or running (poll again after Retry-After), or done (the result).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Queued"},{"$ref":"#/components/schemas/Running"},{"$ref":"#/components/schemas/Done"}],"discriminator":{"propertyName":"status","mapping":{"queued":"#/components/schemas/Queued","running":"#/components/schemas/Running","done":"#/components/schemas/Done"}},"title":"Response Get Packet Extractions  Job Id  Get"},"examples":{"done":{"value":{"status":"done","version":9,"created":"2026-10-18T16:28:39+00:00","started":"2026-10-18T16:37:55+00:00","finished":"2026-10-18T16:44:12+00:00","expires_at":"2026-10-18T19:44:12+00:00","packet_sha256":"9f2c4d1e00000000000000000000000000000000000000000000000000000000","pages":35,"page_map":[{"file":"release.pdf","pages":[1,2,3,4]}],"metadata":{"title":"Example Movie 5"},"answer":{"pages":[{"page":1,"what":"model release, page 1"}],"performers":[],"unassigned":[]},"id_crops":[{"performer":1,"copy":1,"page":5,"status":"verified","note":"passport; DOE JANE A","jpeg_base64":"/9j/4AAQ…"}],"pdf":"/extractions/9f2c4d1e00000000000000000000000000000000000000000000000000000000/pdf"}},"queued":{"value":{"id":"9f2c4d1e00000000000000000000000000000000000000000000000000000000","status":"queued","version":9,"created":"2026-10-18T16:28:39+00:00","queue_position":1}},"running":{"value":{"id":"9f2c4d1e00000000000000000000000000000000000000000000000000000000","status":"running","version":9,"created":"2026-10-18T16:28:39+00:00","started":"2026-10-18T16:37:55+00:00"}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}},"Expires-At":{"description":"When the job, its result and its PDF are deleted (RFC 3339 UTC).","schema":{"type":"string","format":"date-time"}}}},"404":{"description":"Unknown id, or the job expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Not_Found0":{"value":{"type":"about:blank","title":"Not Found","status":404,"detail":"no such extraction (unknown id, or deleted after the retention window)","instance":"/extractions/9f2c4d1e00000000000000000000000000000000000000000000000000000000"}}}}}},"500":{"description":"The job failed (a system or code failure); re-submit the same inputs to retry.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Extraction_Failed0":{"value":{"type":"about:blank","title":"Extraction Failed","status":500,"detail":"URLError: <urlopen error [Errno 111] Connection refused>","instance":"/extractions/9f2c4d1e00000000000000000000000000000000000000000000000000000000","id":"9f2c4d1e00000000000000000000000000000000000000000000000000000000","version":9}}}}}}}}},"/extractions/{job_id}/pdf":{"get":{"summary":"The combined PDF","operationId":"get_packet_pdf_extractions__job_id__pdf_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"The combined PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}},"headers":{"Expires-At":{"description":"When the job, its result and its PDF are deleted (RFC 3339 UTC).","schema":{"type":"string","format":"date-time"}}}},"404":{"description":"Unknown id, or the job expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"Not_Found0":{"value":{"type":"about:blank","title":"Not Found","status":404,"detail":"no such extraction (unknown id, or deleted after the retention window)","instance":"/extractions/9f2c4d1e00000000000000000000000000000000000000000000000000000000"}}}}}}}}}},"components":{"schemas":{"Accepted":{"properties":{"id":{"type":"string","title":"Id","description":"The extraction's id: sha256 of its inputs (the combined PDF, plus the metadata when any was sent)."},"status":{"type":"string","enum":["queued","running","done"],"title":"Status"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The processing version that produced the job: one number for assembly, model, prompt, crop checks, date parsing and response shape. null for jobs from before versioning."},"created":{"type":"string","format":"date-time","title":"Created","description":"When the job was submitted (RFC 3339, UTC)."},"started":{"anyOf":[{"type":"string","format":"date-time","description":"RFC 3339, UTC, to the second."},{"type":"null"}],"title":"Started","description":"Once running."},"finished":{"anyOf":[{"type":"string","format":"date-time","description":"RFC 3339, UTC, to the second."},{"type":"null"}],"title":"Finished","description":"Once done."},"expires_at":{"anyOf":[{"type":"string","format":"date-time","description":"RFC 3339, UTC, to the second."},{"type":"null"}],"title":"Expires At","description":"Once done: when the job is deleted."},"pages":{"type":"integer","title":"Pages","description":"Pages in the combined PDF."},"page_map":{"items":{"$ref":"#/components/schemas/PageMapEntry"},"type":"array","title":"Page Map","description":"One entry per uploaded file, in upload order."},"metadata":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"type":"object","title":"Metadata","description":"The metadata fields sent with the files, unchanged; {} if none. A key sent more than once has a list of values."}},"type":"object","required":["id","status","version","created","pages","page_map","metadata"],"title":"Accepted","description":"The POST's answer: the job the inputs landed on. Re-sending the same inputs lands on the\nsame job, so a resubmission can come back running or done."},"Done":{"properties":{"status":{"type":"string","const":"done","title":"Status"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The processing version that produced the job: one number for assembly, model, prompt, crop checks, date parsing and response shape. null for jobs from before versioning."},"created":{"type":"string","format":"date-time","title":"Created","description":"When the job was submitted (RFC 3339, UTC)."},"started":{"type":"string","format":"date-time","title":"Started","description":"When the extraction began."},"finished":{"type":"string","format":"date-time","title":"Finished","description":"When the extraction ended."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When the job, this result and its PDF are deleted; same as the Expires-At header."},"packet_sha256":{"type":"string","title":"Packet Sha256","description":"SHA-256 of the combined PDF. Equals the job id when no metadata was sent and no file was excluded."},"pages":{"type":"integer","title":"Pages","description":"Pages in the combined PDF."},"page_map":{"items":{"$ref":"#/components/schemas/PageMapEntry"},"type":"array","title":"Page Map","description":"One entry per uploaded file, in upload order."},"metadata":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"type":"object","title":"Metadata","description":"The metadata fields sent with the files, unchanged; {} if none. A key sent more than once has a list of values."},"answer":{"properties":{"pages":{"items":{"properties":{"page":{"type":"integer","minimum":1.0},"what":{"type":"string"}},"type":"object","required":["page","what"]},"type":"array"},"performers":{"items":{"properties":{"stage_names":{"items":{"type":"string"},"type":"array"},"legal_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"id_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"id_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"id_expiration":{"anyOf":[{"type":"string"},{"type":"null"}]},"id_expiration_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"production_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"production_date_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"id_copies":{"items":{"properties":{"page":{"type":"integer","minimum":1.0},"box_2d":{"items":{"type":"integer"},"type":"array","maxItems":4,"minItems":4},"id_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"legal_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"id_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"expiration_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiration_date_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"unreadable_fields":{"items":{"type":"string","enum":["legal_name","id_number","date_of_birth","expiration_date"]},"type":"array"}},"type":"object","required":["page","box_2d","id_type","legal_name","id_number","date_of_birth","date_of_birth_parsed","expiration_date","expiration_date_parsed","unreadable_fields"]},"type":"array"},"documents":{"items":{"properties":{"pages":{"items":{"type":"integer","minimum":1.0},"type":"array"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"legal_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"id_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_of_birth_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"production_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"production_date_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."},"form_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"form_date_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."}},"type":"object","required":["pages","kind","stage_name","legal_name","id_number","date_of_birth","date_of_birth_parsed","production_date","production_date_parsed","form_date","form_date_parsed"]},"type":"array"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"type":"object","required":["stage_names","legal_name","date_of_birth","date_of_birth_parsed","id_type","id_number","id_expiration","id_expiration_parsed","production_date","production_date_parsed","id_copies","documents","notes"]},"type":"array"},"unassigned":{"items":{"properties":{"page":{"type":"integer","minimum":1.0},"what":{"anyOf":[{"type":"string"},{"type":"null"}]}},"type":"object","required":["page","what"]},"type":"array"},"production_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"production_date_parsed":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"The date beside it, parsed (rules at /help/result#dates); null if it can't be read."}},"type":"object","required":["pages","performers","unassigned","production_date","production_date_parsed"],"title":"Answer","description":"What the model found in the packet. Every date is copied as printed, with a `<field>_parsed` ISO date beside it."},"id_crops":{"items":{"$ref":"#/components/schemas/IdCrop"},"type":"array","title":"Id Crops","description":"Every ID copy cut out of the PDF as a JPEG, with its check."},"pdf":{"type":"string","title":"Pdf","description":"Where to fetch the combined PDF: /extractions/{id}/pdf."}},"type":"object","required":["status","version","created","started","finished","expires_at","packet_sha256","pages","page_map","metadata","answer","id_crops","pdf"],"title":"Done","description":"The result. Every field is explained at /help/result."},"Health":{"properties":{"status":{"type":"string","const":"ok","title":"Status"},"version":{"type":"integer","title":"Version","description":"The processing version this server applies to new jobs."},"queued":{"type":"integer","title":"Queued","description":"Jobs waiting; the one running isn't counted."}},"type":"object","required":["status","version","queued"],"title":"Health"},"IdCrop":{"properties":{"performer":{"type":"integer","title":"Performer","description":"Which performer: answer.performers[performer-1]."},"copy":{"type":"integer","title":"Copy","description":"Which of their ID copies: id_copies[copy-1]."},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"The page the crop was cut from; for a repaired crop, the corrected page."},"status":{"anyOf":[{"type":"string","enum":["verified","repaired","failed"]},{"type":"null"}],"title":"Status","description":"verified: an ID showing the recorded date of birth. repaired: the first cut wasn't, a neighbouring page was, and the crop was taken from there. failed: no ID found where the model pointed. null: not checked."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"One line for a reviewer: ID type and name read off the crop, where a repaired crop moved to, or what a failed crop shows."},"jpeg_base64":{"type":"string","contentEncoding":"base64","contentMediaType":"image/jpeg","title":"Jpeg Base64","description":"The crop, a base64-encoded JPEG."}},"type":"object","required":["performer","copy","page","status","note","jpeg_base64"],"title":"IdCrop","description":"One ID copy cut out of the combined PDF, with its check."},"PageMapEntry":{"properties":{"file":{"type":"string","title":"File","description":"The uploaded filename, as sent."},"pages":{"items":{"type":"integer"},"type":"array","title":"Pages","description":"Its page numbers in the combined PDF; empty when it was excluded."},"duplicate_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duplicate Of","description":"Present when this file has the same bytes as an earlier upload: it was included once, and `pages` points at that copy."},"render_notes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Render Notes","description":"Present when the file was not read or rendered the way its name suggests: its content is another type than its extension says (it is read as what it is), an image had several frames and only the first was included, or an office file could not be rendered as intended (e.g. a spreadsheet's landscape fit-to-width)."},"excluded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excluded","description":"Present when the file was left out of the combined PDF, with the reason: its content is no supported type, or it could not be read in full (e.g. a truncated JPEG). The model never saw it."}},"type":"object","required":["file","pages"],"title":"PageMapEntry","description":"Where one uploaded file's pages went in the combined PDF."},"Queued":{"properties":{"id":{"type":"string","title":"Id","description":"The extraction's id: sha256 of its inputs (the combined PDF, plus the metadata when any was sent)."},"status":{"type":"string","const":"queued","title":"Status"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The processing version that produced the job: one number for assembly, model, prompt, crop checks, date parsing and response shape. null for jobs from before versioning."},"created":{"type":"string","format":"date-time","title":"Created","description":"When the job was submitted (RFC 3339, UTC)."},"queue_position":{"type":"integer","title":"Queue Position","description":"1 = next to run."}},"type":"object","required":["id","status","version","created","queue_position"],"title":"Queued","description":"Waiting for the GPU. Poll again after Retry-After."},"Running":{"properties":{"id":{"type":"string","title":"Id","description":"The extraction's id: sha256 of its inputs (the combined PDF, plus the metadata when any was sent)."},"status":{"type":"string","const":"running","title":"Status"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The processing version that produced the job: one number for assembly, model, prompt, crop checks, date parsing and response shape. null for jobs from before versioning."},"created":{"type":"string","format":"date-time","title":"Created","description":"When the job was submitted (RFC 3339, UTC)."},"started":{"type":"string","format":"date-time","title":"Started","description":"When the extraction began."}},"type":"object","required":["id","status","version","created","started"],"title":"Running","description":"On the GPU. Poll again after Retry-After."},"Problem":{"additionalProperties":true,"description":"RFC 9457 problem details: the body of every non-2xx response.","properties":{"type":{"description":"Always about:blank: `title` names the problem.","title":"Type","type":"string"},"title":{"description":"The kind of problem; the guide at / lists every title.","title":"Title","type":"string"},"status":{"description":"The HTTP status code.","title":"Status","type":"integer"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"What went wrong, for a person.","title":"Detail"},"instance":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The path that was requested.","title":"Instance"},"file":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Unsupported File: the file refused.","title":"File"},"id":{"anyOf":[{"description":"The extraction's id: sha256 of its inputs (the combined PDF, plus the metadata when any was sent).","type":"string"},{"type":"null"}],"default":null,"title":"Id"},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The processing version that produced the job: one number for assembly, model, prompt, crop checks, date parsing and response shape. null for jobs from before versioning.","title":"Version"},"created":{"anyOf":[{"description":"RFC 3339, UTC, to the second.","format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"Extraction Failed: the job's timestamps.","title":"Created"},"started":{"anyOf":[{"description":"RFC 3339, UTC, to the second.","format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Started"},"finished":{"anyOf":[{"description":"RFC 3339, UTC, to the second.","format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Finished"},"expires_at":{"anyOf":[{"description":"RFC 3339, UTC, to the second.","format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Expires At"},"errors":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null,"description":"Validation Error: what didn't match.","title":"Errors"}},"required":["type","title","status"],"title":"Problem","type":"object"},"Submission":{"additionalProperties":{"type":"string"},"description":"Every other field is metadata: any key, none required, shown to the model as submitter context and returned as `metadata`. A repeated key keeps every value.","properties":{"files":{"description":"The packet's files, repeated; part order is page order.","items":{"format":"binary","type":"string"},"title":"Files","type":"array"}},"required":["files"],"title":"Submission","type":"object"}}}}