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

Overview

This endpoint returns the blueprint catalog visible to the caller’s organization — the organization’s own blueprints plus the platform-authored (canonical) ones — as a cursor-paginated page of blueprint summaries, newest first. Summaries omit the full blueprint document — fetch a single blueprint with GET /agents/blueprints/{reference} when you need its document or yaml_document.

Request

integer
default:"100"
Page size. Minimum 1, maximum 1000.
string
Forward cursor: return blueprints older than the one with this id. Pass the next_cursor of the previous page to fetch the next page. Mutually exclusive with before.
string
Backward cursor: return blueprints newer than the one with this id. Pass the prev_cursor of the current page to walk back. Mutually exclusive with after.
string
Filter to a single key.
string
Filter by project. Omitted: the platform blueprints, your organization’s blueprints outside projects, and those of every project you can see. A project’s prj_ id: that project’s blueprints only (404 when it does not exist or you cannot see it). none: lists the blueprints outside any project, platform ones included. v2.0.0+
boolean
When true, returns only the platform-authored (canonical) blueprints and leaves out your organization’s own blueprints. Omitted or false: both. Canonical blueprints are never in a project, so canonical_only=true with a project_id other than none returns 400. v2.0.1+
boolean
When true, each item carries bundles_count — the number of bundles visible to the caller’s organization pinned to that blueprint. v1.1.11+
boolean
default:"false"
When true, the response includes total. Off by default because it costs an extra count per request. v2.0.1+

Response

array
required
The page, newest first. Each entry is a blueprint summary.
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 a forward page, or as after after a backward one. null when the request carried no cursor.
integer
How many blueprints match the request’s filters across all pages, ignoring limit and the cursor. Present only when you set include_total=true. v2.0.1+

Blueprint summary object

string
required
TypeID-encoded blueprint identifier (blp_ prefix).
string
required
Human-readable key for the blueprint, e.g. osm. An archived version’s key carries a -<date> suffix.
string
required
Display name of the blueprint, from the document.
string
required
Description of the blueprint, from the document. Empty when the document has none.
boolean
required
True for platform-authored (gallery) blueprints shared with every org; false for blueprints owned by a specific org.
boolean
required
True for the current version of a key; false once it has been replaced by a newer blueprint (its key was archived to <key>-<date>).
string
The project the blueprint lives in, or null if the blueprint lives outside any project. v2.0.0+
integer
Number of bundles visible to the caller’s organization — its own plus canonical ones — pinned to this blueprint. Present only when the list was requested with bundles_count=true; omitted otherwise. A blueprint with no matching bundles reports 0. v1.1.11+
string
required
Creation timestamp (date-time).

Important Notes

  • after and before are blueprint ids, and are mutually exclusive — send at most one of them. Passing both, or a malformed one, returns 400.
  • Results are ordered newest first in both cursor directions, so render data as returned.
  • Without project_id, the page includes the blueprints of every project you can see. Pass project_id=none to leave project blueprints out. A project_id that does not exist or that you cannot see returns 404. v2.0.0+
  • canonical_only=true cannot be combined with a project_id other than none; that pair returns 400. Omit project_id or pass project_id=none. v2.0.1+
  • An archived (replaced) blueprint stays in the catalog with is_active: false and a key of the form <key>-<date>.
  • bundles_count=true counts only the bundles visible to the caller’s organization — its own plus canonical ones — so the count is per-viewer. The count is computed over the blueprints on the current page. v1.1.11+