List Versions

List the historic versions of a dds_record, newest first.

Each item is a thin summary โ€” submission state and version number only. Use Get Version for the full plot snapshot.

Why 404 instead of empty list

The handler runs a parent-record visibility check first. If the record isn't visible to the caller (cross-org or missing), the response is 404 rather than 200 + [], so clients can distinguish "no versions" from "no permission".

Per-version status fields

Each entry's lifecycle_status is the ยง8.1 dashboard verdict โ€” seven values (draft / awaiting_submission / submitting / submitted / accepted / rejected / stale) derived from the audit log + TRACES round-trip status + the staleness flag. This is the field a UI renders.

Note: the list view doesn't carry completeness, so a version that would be awaiting_submission on the detail endpoint degrades to draft here. Fetch the version detail when the "ready to file" distinction matters.

submitting_at / submitted_at are derived from the same audit events (version.submit_started / version.submitted / version.marked_submitted) that drive lifecycle_status โ€” they will never contradict the status field.

This is not the same enum as the report builder's computed_status.status. The report's status is a narrower five-state audit-log fact (draft / submitting / submitted / manually_submitted / submission_failed) used for reconciliation. See Get Audit Record Summary for the full side-by-side reference.

Pagination

ParamDefaultMaxMeaning
page[number]1โ€”1-based page index
page[size]20100Versions per page

Response meta carries count (total versions for this record), page, and page_size.

Ordering

Versions are returned in version_number DESC (newest first). There is no client-controllable sort in v1.

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing/invalid API key
404NOT_FOUNDRecord isn't visible to the caller

Required scope: ingestions:read