Changelog

API version history and the integration roadmap.

v1.2 (October 2026)

One request submits a study, and one request returns everything about it.

• POST /studies takes the file as multipart form data, stores it and starts the read. It returns the study object, the same shape as GET /studies/{id}, with status: queued. A JSON body is refused with 400 validation_error.
• A study that cannot be read is not kept: 422 no_processable_series, series_not_found, scan_type_undetected and body_part_mismatch are returned from the submit, and the sender resubmits with the corrected fields.
• Removed: the presigned-URL variant of POST /studies, GET /studies/{id}/upload, the three /uploads/multipart routes, POST /studies/{id}/process, and the auto_process field. 409 already_processing no longer occurs.
• patient.sex is now patient.gender on every response. Values are unchanged: M, F, O.
• The submit takes the patient as patient[name], patient[dob] and patient[gender], the same object the responses return. The flat patient_name, patient_dob and patient_gender fields are gone.
• GET /studies/{id} carries the result: report is null until the read completes, then holds markdown, findings, impression, sections, figures, unavailable_figure_numbers, html_url, generated_at, completion_status and review_required. The top-level report_markdown, figures and protocol fields are gone.
• Figures gain location: the DICOM series_uid, plane, sop_instance_uid and instance_number of the slice shown, and the marked point in patient coordinates, so a figure can be opened in your own viewer. location.marks carries the shapes drawn on the figure (circle, line or outline, each with a finding or mirror role) in the same coordinates.
• report.markdown cites figures as [Fig. N] and no longer embeds image links; the figures are in report.figures, and report.html embeds them.
• Removed: GET /studies/{id}/report, /findings, /images and /series. GET /studies/{id}/report.html remains. The section label and the constant authority field are gone.
• vendor_ref is removed: it is no longer accepted on submit or returned anywhere. study_id is the handle; keep your own mapping to your accession number.
• The callback body is the study object, the same as GET /studies/{id}, plus "event": "study.completed".

v1.1 (October 2026)

The contract was tidied before partner integrations are frozen. Everything removed was either always empty or described storage rather than the study.

• One status set everywhere: uploaded, queued, processing, complete, error. materializing is reported as processing.
• Timestamps are always YYYY-MM-DDTHH:MM:SSZ; an unknown time is null.
• POST /studies: the upload block no longer carries s3_prefix or per-file path.
• POST /studies/{id}/process: job_id removed; study_id is the only handle.
• GET /studies/{id}: the integer figures/images counts are gone; figures is the list of cited figures once complete.
• GET /studies/{id}/report: report_pdf_url, report_url_expires_in, run_version, schema_version and evidence_url removed. Figures are { number, caption, url }.
• GET /studies/{id}/findings: typed shape { study_id, generated_at, review_required, report { findings, impression }, findings [ { id, label, text, figures } ] }.
• GET /studies/{id}/images: preview_url removed; entries are { number, caption, url }.
• GET /studies/{id}/evidence removed; /images and /report carry the figures.
• DELETE /studies/{id}: the free-text deleted list removed; deleted_objects is the number to record.
• GET /studies/{id}/upload: path removed; status renamed upload_status.
• Multipart complete and abort return { study_id, filename, ... } instead of { ok, path }.
• Errors: unknown routes and methods now use the error envelope; validation_error.details is [{ field, message }].

v1 (July 2026)

Initial release of the Vendor API at https://api.vitalview.ai/v1.

• API-key authentication (X-API-Key), organization-scoped access
• POST /studies: create a study and receive presigned DICOM upload URLs
• POST /studies/{id}/process: implicit series detection and dispatch
• GET /studies, GET /studies/{id}: study list and per-stage status
• GET /studies/{id}/report: draft report markdown and HTML with figures
• GET /studies/{id}/findings: structured findings
• GET /studies/{id}/images: key images
• OpenAPI reference at api.vitalview.ai/v1/docs

Roadmap

Planned for future releases, in rough order:

• Completion webhooks: push notification to your callback URL when a study completes, replacing polling
• Multipart uploads through /v1 for very large single files
• Signed image URLs with configurable expiry
• Scoped keys: read-only keys for viewer integrations
• Cursor pagination on GET /studies
• HL7 FHIR: DiagnosticReport and ImagingStudy resource mapping
• Usage export: per-study metering reports for reconciliation

Integration feedback shapes this list. Write to we@vitalview.ai.