> ## Documentation Index > Fetch the complete documentation index at: https://docs.landfall.ai/llms.txt > Use this file to discover all available pages before exploring further. # List the versions of a data asset, newest first > Returns the asset's versions, newest first. By default only `committed` ones - a version list is normally a history of what landed, and in-flight or abandoned uploads are noise. Widen it with the `status` parameter. An asset with no committed version yet does not exist as far as this endpoint is concerned: while version 1 is still uploading the asset is not live, and this returns 404. A `pending` version therefore only shows up here alongside at least one committed one. For progress on a first upload use `GET .../versions/{versionNo}/status`. ## OpenAPI ````yaml /api-reference/openapi.yml get /data-assets/{username}/{namespace}/{assetId}/versions openapi: 3.0.3 info: title: DataLinks version: 3.10.0 servers: - url: https://api.datalinks.com/api/v1 description: production server security: - bearerAuth: [] - openId: - implicit paths: /data-assets/{username}/{namespace}/{assetId}/versions: get: tags: - data-assets summary: List the versions of a data asset, newest first description: > Returns the asset's versions, newest first. By default only `committed` ones - a version list is normally a history of what landed, and in-flight or abandoned uploads are noise. Widen it with the `status` parameter. An asset with no committed version yet does not exist as far as this endpoint is concerned: while version 1 is still uploading the asset is not live, and this returns 404. A `pending` version therefore only shows up here alongside at least one committed one. For progress on a first upload use `GET .../versions/{versionNo}/status`. operationId: listDataAssetVersions parameters: - name: username in: path description: The username associated with the request. required: true schema: type: string - name: namespace in: path description: Namespace for the dataset. required: true schema: type: string example: cinematography - name: assetId in: path description: The data asset's id. required: true schema: type: string format: uuid - name: status in: query description: > Which statuses to include, comma separated. - omitted entirely - `committed` only. The default, so an unaware caller never sees a half-written version. - `status=` (present but empty) - every status. Widening is explicit by design: there is no value that means "all" implicitly. - `status=pending,committed` - exactly those. Unknown values are rejected with 422 rather than ignored, so a typo like `status=commited` fails loudly instead of silently returning nothing. required: false schema: type: string examples: committedOnly: summary: Default when the parameter is omitted value: committed everything: summary: Every status - the empty value value: '' inFlight: summary: Committed history plus an upload in progress value: pending,committed responses: '200': description: The asset's versions content: application/json: schema: $ref: '#/components/schemas/DataAssetVersionListResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: DataAssetVersionListResponse: required: - versions type: object properties: versions: type: array items: $ref: '#/components/schemas/DataAssetVersionResponse' DataAssetVersionResponse: required: - createdAt - status - uploadedBy - versionNo type: object properties: versionNo: type: integer sizeBytes: type: integer format: int64 contentType: type: string etag: type: string createdAt: type: string format: date-time committedAt: type: string format: date-time status: type: string description: > Lifecycle of the version. - `pending` - a multipart upload is still in flight. `sizeBytes` is the size the client declared at reservation, not bytes received; `etag` and `committedAt` are absent and the version is not downloadable, so `GET .../versions/{n}` returns 404 for it. Use `GET .../versions/{n}/status` for upload progress. - `committed` - finished and downloadable. - `aborted` - the upload failed and was abandoned explicitly via `POST .../versions/{versionNo}/abort`. It stays listable for `aborted-ttl` (default 1 day) so a client can see that the attempt failed, then the reaper removes the row and it disappears from this list. Expect it to vanish; do not treat its absence as an error. An upload that is simply never finished is a third case with no status of its own: it stays `pending` until its deadline passes, then the reaper deletes the row outright, leaving no trace. Its version number is then reused by the next upload, so a version number seen as `pending` is not a stable identifier until it commits or aborts. enum: - pending - committed - aborted uploadedBy: type: string description: > Username of whoever started this version - not the user uuid, which would be unrenderable without a user-lookup endpoint. Falls back to the uuid if the user record no longer resolves. aliasOf: type: integer description: > Set only on a version produced by `POST .../rollback`: the version number whose bytes this one is a copy of. Absent on a version that came from a real upload, which is how a client tells "someone re-uploaded the same data" from "someone rolled back". It is the version that rollback was asked for, not the root of a chain - rolling back to a version that is itself an alias gives `aliasOf` pointing at that alias. The target can also be pruned by the retention window while this row survives, so treat it as a label, not a resolvable link: a number with no matching version in the list means the original has aged out. `uploadedBy` is whoever performed the rollback, and `createdAt`/`committedAt` are when the rollback happened; only the content is inherited. `sizeBytes`, `contentType` and `etag` match the target, since the object is copied byte for byte. ErrorResponse: required: - error_code - message type: object properties: error_code: type: string example: UNAUTHORIZED error_message: type: string example: '' message: type: string example: Missing authentication token sub_errors: type: array items: required: - code - message type: object properties: code: type: string message: type: string responses: Unauthorized: description: >- Unauthorized. This error occurs if the authentication token is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnprocessableEntity: description: Invalid request (e.g. version out of retention, TTL above max). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http description: > Use a Bearer token for authentication. Submit the token using the `Authorization` header: `Authorization: Bearer `. scheme: bearer openId: type: oauth2 flows: implicit: authorizationUrl: >- https://login.datalinks.com/realms/datalinks-realm/protocol/openid-connect/auth scopes: openid: openid ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.