--- updatedAt: 2026-04-02T21:43:09.000Z agentTools: projectIndex: https://developer.air.inc/llms.txt --- # /assets Get a list of assets. Sorted by coverVersion.updatedAt descending (most recently updated asset version first). # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Air API", "version": "1.0.0" }, "servers": [ { "url": "api.air.inc" } ], "security": [ { "ApiKeyAuth": [], "WorkspaceIdAuth": [] }, { "BearerAuth": [], "WorkspaceIdAuth": [] } ], "paths": { "/v1/assets": { "get": { "summary": "/assets", "tags": [ "Assets" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "The max number of assets to return in the response", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Cursor to the next page of assets", "schema": { "type": "string" } }, { "name": "parentBoardId", "in": "query", "required": false, "description": "The parent board ID of the assets to return", "schema": { "type": "string" } }, { "name": "showcaseId", "in": "query", "required": false, "description": "Only return assets added to this showcase. With `includeNestedAssets=true`, also returns the assets inside the boards added to it. Items on the showcase's sub-pages are not returned. Cannot be combined with `parentBoardId` or `semantic=true`; supplying either returns a `400`. Returns `404` if the showcase does not exist and `403` if you cannot view it.", "schema": { "type": "string" } }, { "name": "includeNestedAssets", "in": "query", "required": false, "description": "When set to `true` along with a `parentBoardId`, returns assets from all nested sub-boards rather than only the immediate children of the specified board. With a `showcaseId`, also returns the assets inside the boards added to the showcase. Requires `parentBoardId` or `showcaseId` to be provided.", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "description": "Search for assets with metadata matching the provided value including the title, description, etc.", "schema": { "type": "string" } }, { "name": "semantic", "in": "query", "required": false, "description": "When set to `true`, the value for `search` will be used to perform a semantic search using AI embeddings. `search` must be non-blank. \nIt only returns one page of results ordered by relevance.\nThe following fields will be rejected with a `400` error: `tag`, `customField`, `createdAt`, and `cursor`.\n**This requires Semantic Search to be enabled for the workspace.**", "schema": { "type": "boolean" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter assets by attached tags. If multiple `tag=value` pairs are provided, only assets with all specified tags will be included.", "schema": { "type": "string" } }, { "name": "customField", "in": "query", "required": false, "description": "For single- and multi-select custom fields, filter for entities matching specific values. This query parameter can be supplied multiple times, as custom field ID UUID and custom field value ID UUID pairs, separated by a colon `:`, e.g. `&customField=fb9e852c-eb2a-4dd0-81f4-7af266c335d1:7b6e39bb-28bb-46ae-be8a-5c01bbacf78c`. Supplying multiple custom field UUID's matches all (AND), and mutliple custom field value UUID's per the same repeated custom field matches any (OR).", "schema": { "type": "string" } }, { "name": "createdAt", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filter assets by creation date. Provide an object with optional `gte` (greater than or equal) and `lte` (less than or equal) properties as ISO 8601 date strings, e.g. `createdAt[gte]=2024-01-01T00:00:00.000Z&createdAt[lte]=2024-12-31T23:59:59.999Z`.", "schema": { "type": "object", "properties": { "gte": { "type": "string", "format": "date-time", "description": "Filter assets created on or after this date" }, "lte": { "type": "string", "format": "date-time", "description": "Filter assets created on or before this date" } } } } ], "x-codeSamples": [ { "lang": "JavaScript", "label": "Air SDK", "source": "import { AirApi } from \"@air/api-sdk\";\n\nconst air = new AirApi({\n apiKey: \"your-api-key\",\n workspaceId: \"your-workspace-id\",\n});\n\nconst page = await air.assets.list({ limit: 10 });\nconsole.log(page.data);\n" } ], "responses": { "200": { "description": "Filter by tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/CustomFieldType" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } }, "coverVersion": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "description": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "smartTags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "ext": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "createdAt": { "type": "string", "format": "style" }, "uploadedAt": { "type": "string" }, "fileCreatedAt": { "type": "string", "format": "style" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "size": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } }, "urls": { "type": "object", "properties": { "thumbnail": { "type": "string", "format": "uri" }, "preview": { "type": "string", "format": "uri" } } } } } } } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "cursor": { "nullable": true } } }, "total": { "type": "integer" } } } } } } }, "description": "Get a list of assets.\n\nSorted by coverVersion.updatedAt descending (most recently updated asset version first)." } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Air API key for authentication" }, "WorkspaceIdAuth": { "type": "apiKey", "in": "header", "name": "x-air-workspace-id", "description": "Your Air workspace ID" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "OAuth 2.0 bearer token. Some endpoints (notably discovery endpoints such as `GET /v1/workspaces`) accept bearer authentication exclusively and do not accept API keys; see the security requirements on each endpoint." } }, "schemas": { "CustomFieldType": { "type": "string", "enum": [ "single-select", "multi-select", "plain-text", "date" ], "description": "The type of custom field" } } } } ```