diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 4b3dd905..23785fb6 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -370,6 +370,8 @@ TPM traceback transactional truthy +TSV +tsv UA ubuntu Ubuntu diff --git a/docs/reference/api/rest-api-endpoints/activities.md b/docs/reference/api/rest-api-endpoints/activities.md index 15a110a2..2c5c653e 100644 --- a/docs/reference/api/rest-api-endpoints/activities.md +++ b/docs/reference/api/rest-api-endpoints/activities.md @@ -243,3 +243,52 @@ Required parameters: Optional parameters: - None + +(reference-activities-exports)= +## POST `/activities/exports` + +Initiates an asynchronous export of activity log history into Tab-Separated Value (TSV) format. See {ref}`reference-rest-api-exports` to manage and download export jobs. + +Optional parameters: + +- `name`: A name to identify the export job. +- `query`: A query string used to filter the activity history to export. Defaults to an empty string, which exports all activities. +- `selected_field_ids`: A list of field IDs to include in the exported TSV file. +- `retain_until`: An ISO 8601-formatted datestamp indicating how long to retain the export. + +Example request: + +```bash +curl -X POST "https://landscape.canonical.com/api/v2/activities/exports" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $JWT" \ + -d '{ + "name": "Monthly Activity Export", + "query": "activity_status:succeeded", + "selected_field_ids": ["id", "creation_time", "summary", "type", "activity_status"], + "retain_until": "2026-07-19T11:00:00Z" + }' +``` + +Example response: + +```json +{ + "id": 43, + "name": "Monthly Activity Export", + "status": "processing", + "progress": 0, + "type": "activity", + "query": "activity_status:succeeded", + "created_at": "2026-06-19T11:01:00Z", + "retain_until": "2026-07-19T11:00:00Z", + "filename": "", + "row_count": 0, + "download_ready": false, + "estimated_seconds_remaining": null +} +``` + +```{note} +This endpoint is available starting in Landscape 26.10. +``` diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index a045a4df..a0ee4412 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -1472,7 +1472,7 @@ Example response: ``` ```{note} -This endpoint is available starting in Landscape 26.04 LTS +This endpoint is available starting in Landscape 26.04 LTS. ``` ## POST `/computers/release-upgrades` @@ -1519,3 +1519,57 @@ Example response: } ``` +(reference-computers-exports)= +## POST `/computers/exports` + +Initiates an asynchronous export of computer data into Tab-Separated Value (TSV) format. See {ref}`reference-rest-api-exports` to manage and download export jobs. + +Optional parameters: + +- `name`: A name to identify the export job. +- `query`: A query string with space-separated tokens used to filter the computers to export. Defaults to an empty string, which exports all computers. +- `archived_only`: If true, only includes archived computers. If false, only includes non-archived computers. Defaults to false. +- `wsl_parents`: If true, restrict the result to WSL parent instances. Defaults to false. +- `wsl_children`: If true, restrict the result to WSL child instances. Defaults to false. +- `selected_field_ids`: A list of field IDs to include in the exported TSV file. +- `retain_until`: An ISO 8601-formatted datestamp indicating how long to retain the export. + +Example request: + +```bash +curl -X POST "https://landscape.canonical.com/api/v2/computers/exports" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $JWT" \ + -d '{ + "name": "Weekly Computer Export", + "query": "tag:server", + "archived_only": false, + "wsl_children": false, + "wsl_parents": false, + "selected_field_ids": ["id", "title", "hostname", "distribution"], + "retain_until": "2026-06-26T12:00:00Z" + }' +``` + +Example response: + +```json +{ + "id": 42, + "name": "Weekly Computer Export", + "status": "processing", + "progress": 0, + "type": "instance", + "query": "tag:server", + "created_at": "2026-06-19T11:00:00Z", + "retain_until": "2026-06-26T12:00:00Z", + "filename": "", + "row_count": 0, + "download_ready": false, + "estimated_seconds_remaining": null +} +``` + +```{note} +This endpoint is available starting in Landscape 26.10. +``` diff --git a/docs/reference/api/rest-api-endpoints/exports.md b/docs/reference/api/rest-api-endpoints/exports.md new file mode 100644 index 00000000..c37c48b9 --- /dev/null +++ b/docs/reference/api/rest-api-endpoints/exports.md @@ -0,0 +1,201 @@ +--- +myst: + html_meta: + description: "REST API endpoints for managing data exports in Landscape. Track, download, and delete TSV exports of systems and activity logs." +--- + +(reference-rest-api-exports)= + +# TSV exports + +```{note} +TSV exports are available starting in Landscape 26.10. +``` + +The endpoints available here are related to managing TSV exports. See {ref}`reference-computers-exports` to export computer data, or {ref}`reference-activities-exports` to export activity log history. + +## GET `/exports` + +Get export jobs associated with the current user. + +Path parameters: + +- None + +Query parameters: + +- `search`: Only export jobs with names matching the search term are returned. +- `limit`: The maximum number of results returned by the method. It defaults to 50. +- `offset`: The offset inside the list of results. +- `type`: Only export jobs of the specified type are returned. Can be `instance` or `activity`. + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/exports?type=instance&limit=1" -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "count": 3, + "results": [ + { + "id": 42, + "name": "Weekly Computer Export", + "status": "completed", + "progress": 100, + "type": "instance", + "query": "tag:server", + "created_at": "2026-06-19T11:00:00Z", + "retain_until": "2026-06-26T12:00:00Z", + "filename": "export_42.tsv", + "row_count": 13, + "download_ready": true, + "estimated_seconds_remaining": null + } + ], + "next": "https://landscape.canonical.com/api/v2/exports?type=instance&limit=1&offset=1", + "previous": null +} +``` + +## GET `/exports/` + +Get the export job associated with a specified ID. + +Path parameters: + +- `id`: The export job ID. + +Query parameters: + +- None + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/exports/42" -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "id": 42, + "name": "Weekly Computer Export", + "status": "processing", + "progress": 45, + "type": "instance", + "query": "tag:server", + "created_at": "2026-06-19T11:00:00Z", + "retain_until": "2026-06-26T12:00:00Z", + "filename": "", + "row_count": 0, + "download_ready": false, + "estimated_seconds_remaining": 30 +} +``` + +## POST `/exports//cancel` + +Cancel an in-progress export job. + +Path parameters: + +- `id`: The export job ID. + +Query parameters: + +- None + +Example request: + +```bash +curl -X POST "https://landscape.canonical.com/api/v2/exports/42/cancel" -H "Authorization: Bearer $JWT" +``` + +This endpoint returns an empty response. + +## POST `/exports//retry` + +Retry a failed export. This creates a new export job and discards the original. The response is the newly created job, which has a new `id`. + +Path parameters: + +- `id`: The export job ID of the failed export. + +Query parameters: + +- None + +Example request: + +```bash +curl -X POST "https://landscape.canonical.com/api/v2/exports/42/retry" -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "id": 51, + "name": "Weekly Computer Export", + "status": "processing", + "progress": 0, + "type": "instance", + "query": "tag:server", + "created_at": "2026-06-19T12:00:00Z", + "retain_until": "2026-06-26T12:00:00Z", + "filename": "", + "row_count": 0, + "download_ready": false, + "estimated_seconds_remaining": null +} +``` + +## GET `/exports//download` + +Download the generated TSV file. + +```{note} +The export must have completed before the file can be downloaded. The file is deleted from storage once the download has finished. +``` + +Path parameters: + +- `id`: The export job ID. + +Query parameters: + +- None + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/exports/42/download" \ + -H "Authorization: Bearer $JWT" \ + -o "export_results.tsv" +``` + +## DELETE `/exports/` + +Delete a finished, failed, or canceled export. + +Path parameters: + +- `id`: The export job ID. + +Query parameters: + +- None + +Example request: + +```bash +curl -X DELETE "https://landscape.canonical.com/api/v2/exports/42" -H "Authorization: Bearer $JWT" +``` + +This endpoint returns an empty response. +