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

Overview

This endpoint returns a cursor-paginated page of bundles. By default the page is most recently run first, with never-run bundles last. Filter by pinned blueprint, search by name or id, and optionally include each bundle’s most recent runs so run history can be rendered without a second call to /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 bundles that follow this one in the current sort order. Pass the next_cursor of the previous page to fetch the next page. Mutually exclusive with before. Valid only under the sort it was minted for. v1.1.11+
string
Backward cursor: return the bundles that precede this one in the current sort order. Mutually exclusive with after. Valid only under the sort it was minted for. v1.1.11+
string
default:"last_run_at"
Sort field: last_run_at (default) ranks bundles by their newest visible run, created_at by creation, name alphabetically. 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. v1.1.11+
string
Sort direction: asc or desc. Defaults per field — desc for last_run_at and created_at, asc for name. Keep it constant while paging with a cursor. v1.1.11+
string
Case-insensitive substring match over the bundle name and id. Omit for no search filter.
string
Restrict to bundles pinning this blueprint (blp_ id, exact match).
boolean
default:"false"
Include each bundle’s most recent runs as latest_runs. Off by default — it costs an extra join per bundle in the page.

Response

array
required
The page, in the requested sort and order — in both cursor directions, so render it as returned. Each entry is a bundle. The default (sort omitted) is most recently run first: ordered by each bundle’s newest visible run, with never-run bundles last (newest created first within either group). Run recency is scoped like latest_runs — to the caller’s org and own runs — so that order is per-viewer. v1.1.11+
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: the newest page has nothing to step back to. Provided because the cursor is opaque, so a client cannot mint the backward anchor from a row itself. v1.1.12+

Bundle object

string
required
TypeID-encoded bundle identifier (bnd_ prefix).
string
required
Human label for the bundle.
string
required
Human description of the bundle.
string
required
The pinned blueprint’s immutable blp_ id. Resolve its key via the blueprint registry when needed.
object
required
User value overrides, layered over the blueprint defaults at run time.
string
required
Build lifecycle of the bundle: building, ready, or failed.
boolean
required
true for a canonical (platform-authored) bundle, visible to every organization.
string
required
Creation timestamp (date-time).
string
Owning org; omitted for a canonical bundle.
object
required
Per-slot model overrides: slot name to registry tag. If this object is empty, the bundle uses the blueprint’s default for every slot.
object
Artifact links attached to the bundle.
array
The bundle’s five most recent runs, newest first. Present only when the read asked for it via include_latest_runs=true; an empty array means the bundle has never been run. Runs are scoped to the caller’s org, so a canonical bundle shows only the caller’s own runs of it.

Run summary object (latest_runs[])

string
required
TypeID-encoded agent identifier (agt_ prefix).
string
required
Agent lifecycle status: running, paused, completed, failed, or cancelled.
string
required
Creation timestamp (date-time).
string
When the run started; null before then.
string
When the run finished; null while unfinished.
string
External executor’s job id for this run (a JOS job_ id). Present once the run has been dispatched.
string
Failure detail; null unless the run failed.

Important Notes

  • after and before are mutually exclusive — send at most one of them.
  • A cursor snapshots the edge row’s sort key, so it is only valid under the sort it was minted for. Keep sort and order constant while paging; replaying a cursor under a different sort returns 400 rather than a wrong or empty page. v1.1.11+
  • Every sort resolves to a full keyset ending in id. Because TypeIDs are random UUIDv4, id is only the final tiebreak, never a sort key of its own. v1.1.11+
  • include_latest_runs=true costs an extra join per bundle in the page; leave it off for plain listings.
  • latest_runs is capped at the five most recent runs and is scoped to the caller’s org.
  • A bundle in Phase 1 is built on create, so status is normally ready; building/failed exist for the eventual image-build path.