Skip to main content
GET
Requires version 2.0.0 or later of the Archetype platform.

Overview

This endpoint returns a cursor-paginated page of your organization’s packages. By default the page is newest built first. By default the page holds the packages outside projects and those of every project you can see. Narrow it to one project, or to the packages outside any project, with project_id. Narrow it to the packages holding one blueprint with blueprint_id: those are the packages that keep the blueprint from being deleted. Search by name, description or id with query. Set include_latest_runs=true to attach each package’s most recent runs, so run history can be rendered without a second call to /api/agents/instances. Choose a different ordering with the sort and order parameters.

Request

integer
default:"100"
Page size. Minimum 1, maximum 1000.
string
Forward cursor: return the packages ranked after it in the current sort order. Pass the next_cursor of the previous page to fetch the next page. The cursor is opaque: never build it from package fields. Mutually exclusive with before.
string
Backward cursor: return the packages ranked before it in the current sort order. Pass the prev_cursor of the current page to walk back. The cursor is opaque: never build it from package fields. Mutually exclusive with after.
string
default:"created_at"
Sort field: created_at (default) ranks packages by when they were built, last_run_at by the newest of their runs you may see, with never-run packages last under desc, and name alphabetically, ignoring case. A cursor is only valid under the sort it was minted for. Replaying it with a different sort is rejected with HTTP status code 400.
string
Sort direction: asc or desc. Defaults per field: desc for created_at and last_run_at, asc for name. Keep it constant while paging with a cursor: a cursor replayed under the other order is accepted but pages the other way from it.
string
Case-insensitive substring match over the package name, description and id. Omit for no search filter.
boolean
default:"false"
Include each package’s most recent runs as latest_runs. Off by default because it costs an extra query per page.
string
Restrict to packages holding this blueprint (blp_ id, exact match).
string
Filter by project. Omitted: the packages outside projects and those of every project you can see. A project’s prj_ id: that project’s packages only (404 when it does not exist or you cannot see it). none: the packages outside any project.

Response

array
required
The page, in the requested sort and order (by default newest built first) in both cursor directions. Each entry is a package, with the same fields as Get Package returns, including latest_runs when you set include_latest_runs=true.
boolean
required
True when more results exist beyond this page in the direction of travel.
string
Cursor for the next page in the same direction. Pass it as after when paging forward, or as before when you supplied before. null when has_more is false.
string
Cursor to step back the way this page was reached. Pass it as before after paging forward, or as after after paging backward. null on a request that carried no cursor.

Important Notes

  • Passing both after and before returns 400, as does a malformed blueprint_id, a repeated parameter, or a parameter of the wrong type.
  • A malformed cursor, or a cursor replayed under a different sort, returns 400.
  • A project_id that does not exist or that you cannot see returns 404.