List assets
Lists the assets the project holds, of every type or of the types named in `asset_type`, optionally narrowed by a `label` substring or an `asset_tag`.
GET /context/v1/assets
Lists the assets the project holds, of every type or of the types named in asset_type, optionally narrowed by a label substring or an asset_tag. Reads the live state by default, or the state a given release or tag published. Use view=index to list without bodies, and limit with offset to read a window; a windowed response also reports total. There is no implicit cap. An unknown asset type is a 400, and status is refused with a 400 because no asset type has one.
Requires the context:read scope.
Parameters
| Parameter | Location | Required | Description |
|---|---|---|---|
asset_type | query | no | Restrict to these asset types, as a comma-separated list of type names such as skill,tool. Omit for every type. List the names with the asset-types operation. An unknown name is a 400. |
label | query | no | Keep assets whose display name contains this text, ignoring case. |
expand | query | no | Pass links to attach incoming and outgoing relationships, each with the neighbour's type and display name already resolved. |
status | query | no | Not supported: no asset type has a status, so any value is refused with a 400. |
release | query | no | Read the assets as this release published them: its number or its canonical name (projects/{project}/releases/{n}). Omit for the live state. An unknown release is a 404. Cannot be combined with tag. |
asset_tag | query | no | Keep assets that carry this exact tag among their own tags. Not the same as tag, which names a release. |
tag | query | no | Read the assets as the release currently holding this tag published them. A tag no release holds is a 404. Cannot be combined with release. |
view | query | no | index lists each asset without its body (identity, display name, card and version); full, the default, includes the body. |
limit | query | no | Return at most this many assets. Omit to return all of them. |
offset | query | no | Skip this many assets before returning. |
Responses
| Status | Meaning |
|---|---|
200 | The request succeeded. |
401 | The token is missing, expired or invalid. |
403 | The token does not carry the scope this operation requires. |
404 | No such project, or the token belongs to a different project. |
422 | The request was not valid: a parameter or the body failed validation. |
The 200 response body:
| Field | Type | Required | Description |
|---|---|---|---|
assets | array of AssetSummary | yes | The assets, in a stable order. |
resolved | ResolvedRelease or null | no | The release the list was read as. Present once the project has a release. |
total | integer or null | no | How many assets match before limit and offset were applied. Present only when a window was requested. |
Shapes
The named shapes used above.
AssetSummary
One asset in a list.
| Field | Type | Required | Description |
|---|---|---|---|
asset | object or null | no | The asset's whole body. Present unless the list was requested with view=index; its fields depend on the asset's type. |
asset_id | string | yes | The asset's id. |
asset_type | string | yes | The asset's type. |
card | AssetCard | yes | The asset's short form. |
label | string | yes | The asset's display name. |
last_updated | string or null | no | When the asset last changed. Present with view=index. |
last_updated_by | string or null | no | Who last changed the asset. Present with view=index. |
name | string or null | no | The asset's canonical name, projects/{project}/assets/{asset_id}. A request that takes an asset id in its body or query accepts this name in its place; a URL path takes the bare id. It is null when the id cannot be written in a canonical name. |
noun | string | yes | What an asset of this type is called. |
version | integer or null | no | The asset's version. Present with view=index. |
AssetCard
The short form of an asset: enough to show it in a list without reading its body.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The asset's id. |
summary | string or null | no | A one- or two-line summary, or null when the asset's type has none. |
tags | array of string | yes | The asset's tags. |
title | string or null | no | A short title, or null when the asset's type has none. |
ResolvedRelease
The release a read was resolved at.
| Field | Type | Required | Description |
|---|---|---|---|
tags | array of string | yes | The tags that release carries. |
version | integer | yes | The release number. |
Example
curl -sS "$API_URL/context/v1/assets" \
-H "Authorization: Bearer $TOKEN"