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_submissionon the detail endpoint degrades todrafthere. 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
| Param | Default | Max | Meaning |
|---|---|---|---|
page[number] | 1 | โ | 1-based page index |
page[size] | 20 | 100 | Versions 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
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing/invalid API key |
| 404 | NOT_FOUND | Record isn't visible to the caller |
Required scope:
ingestions:read