# Assets

## GET /v1/assets

> List assets

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Assets"}],"servers":[{"url":"https://app.hivo.com.au/api/rest","description":"Production"}],"security":[{"XUserId":[],"XApiKey":[]}],"components":{"securitySchemes":{"XUserId":{"type":"apiKey","in":"header","name":"X-User-Id","description":"HIVO User ID"}},"schemas":{"AssetListResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"links":{"$ref":"#/components/schemas/PaginationLinks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AssetListAssetResource"}}},"required":["meta","data"]},"TopLevelMeta":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server timestamp in milliseconds"},"authentication":{"type":"string","description":"Authentication method, e.g. apiKey"},"links":{"type":"object","properties":{"me":{"type":"string","format":"uri"}}}}},"PaginationLinks":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"first":{"type":"string","format":"uri"},"prev":{"type":"string","format":"uri","nullable":true},"next":{"type":"string","format":"uri","nullable":true}}},"AssetListAssetResource":{"type":"object","properties":{"type":{"type":"string","enum":["assets"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/AssetListAssetAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"AssetListAssetAttributes":{"allOf":[{"$ref":"#/components/schemas/AssetAttributes"},{"type":"object","properties":{"versions":{"$ref":"#/components/schemas/AssetVersionsSummaryMap"}}}]},"AssetAttributes":{"type":"object","description":"Asset attributes. Fields are optional and may vary by endpoint and permissions.","properties":{"name":{"type":"string"},"createdAt":{"type":"integer","description":"Unix seconds"},"lastModified":{"type":"integer","description":"Unix seconds"},"tags":{"type":"array","items":{"type":"string"}},"versions":{"type":"object","additionalProperties":true},"collectionIds":{"type":"array","items":{"type":"string"}},"collections":{"type":"array","items":{"type":"object"}},"skus":{"type":"array","items":{"type":"string"}},"path":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"views":{"type":"integer"},"downloads":{"type":"integer"},"clientId":{"type":"string"},"createdBy":{"type":"string"},"sensitiveAt":{"type":"integer"},"expires":{"type":"integer"},"licenseExpiresAt":{"type":"integer"},"batchId":{"type":"string"},"favs":{"type":"array","items":{"type":"string"}},"approvedAt":{"type":"integer"},"taskIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"AssetVersionsSummaryMap":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AssetVersionSummary"}},"AssetVersionSummary":{"type":"object","properties":{"size":{"type":"integer"},"type":{"type":"string"},"extension":{"type":"string"}},"additionalProperties":false},"JsonApiLinkage":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/Link"},"thumbnail":{"$ref":"#/components/schemas/LinkObject"}},"additionalProperties":true},"Link":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/LinkObject"}]},"LinkObject":{"type":"object","description":"JSON:API link object","properties":{"href":{"type":"string","format":"uri"},"meta":{"type":"object","description":"Non-standard meta-information for the link","properties":{"version":{"type":"string","description":"Asset version name used to generate the link (e.g., thumbnail)"}},"additionalProperties":true}},"required":["href"]},"ErrorResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorObject"}}},"required":["errors"]},"ErrorObject":{"type":"object","properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["status","title"]},"Error429Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamp":{"type":"integer"},"retryAfter":{"type":"integer"}}}}}]}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429Response"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/assets":{"get":{"summary":"List assets","operationId":"listAssets","tags":["Assets"],"parameters":[{"name":"sort","in":"query","description":"Sort key. Allowed values are createdAt, -createdAt. Defaults to -createdAt.","schema":{"type":"string","enum":["createdAt","-createdAt"]}},{"name":"limit","in":"query","description":"Maximum number of assets to return (1–256). Defaults to 32.","schema":{"type":"integer","minimum":1,"maximum":256,"default":32}},{"name":"skip","in":"query","description":"Number of assets to skip (pagination) (0–65536). Defaults to 0.","schema":{"type":"integer","minimum":0,"maximum":65536,"default":0}},{"name":"includeThumbnails","in":"query","description":"When true, each listed asset may include a short‑lived signed thumbnail link under `links.thumbnail`.\nThe thumbnail link is a JSON:API link object with `href` and `meta.version`.\n","schema":{"type":"boolean"}},{"name":"filter[search]","in":"query","description":"General search string (max 256 chars). Prefix‑matches asset name and tags (case‑insensitive).","schema":{"type":"string","maxLength":256}},{"name":"filter[id]","in":"query","description":"Asset ID filter. May be repeated and/or provided as a comma‑separated list. Max 512 IDs.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"filter[path]","in":"query","description":"Exact path match (max 512 chars). When combined with filter[collectionId], matches collection‑scoped paths.","schema":{"type":"string","maxLength":512}},{"name":"filter[pathPrefix]","in":"query","description":"Path prefix match (max 512 chars). When combined with filter[collectionId], matches collection‑scoped prefixes.","schema":{"type":"string","maxLength":512}},{"name":"filter[sensitive]","in":"query","description":"Filters by sensitive status. May require additional permissions.","schema":{"type":"boolean"}},{"name":"filter[archived]","in":"query","description":"true returns archived assets; false (default) returns non‑archived. May require additional permissions.","schema":{"type":"boolean"}},{"name":"filter[licenseExpired]","in":"query","description":"Filters assets with expired licenses. May require additional permissions.","schema":{"type":"boolean"}},{"name":"filter[approved]","in":"query","description":"Filters by approval status.","schema":{"type":"boolean"}},{"name":"filter[favoriteBy]","in":"query","description":"User ID who favorited the asset (ObjectId).","schema":{"type":"string"}},{"name":"filter[collectionId]","in":"query","description":"Collection ID to filter within (ObjectId).","schema":{"type":"string"}},{"name":"filter[clientId]","in":"query","description":"Admin‑only. Client ID to filter within (ObjectId).","schema":{"type":"string"}},{"name":"filter[batchId]","in":"query","description":"Batch identifier (max 256 chars).","schema":{"type":"string","maxLength":256}},{"name":"filter[createdMin]","in":"query","description":"Created at (Unix seconds) lower bound.","schema":{"type":"integer"}},{"name":"filter[createdMax]","in":"query","description":"Created at (Unix seconds) upper bound.","schema":{"type":"integer"}},{"name":"filter[sku]","in":"query","description":"SKU (max 128 chars).","schema":{"type":"string","maxLength":128}},{"name":"filter[metadata.KEY]","in":"query","description":"Metadata filter for arbitrary keys. Replace KEY with the metadata key you wish to filter on. Value is matched case‑insensitively.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /v1/assets/{assetId}

> Get asset

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Assets"}],"servers":[{"url":"https://app.hivo.com.au/api/rest","description":"Production"}],"security":[{"XUserId":[],"XApiKey":[]}],"components":{"securitySchemes":{"XUserId":{"type":"apiKey","in":"header","name":"X-User-Id","description":"HIVO User ID"}},"schemas":{"AssetResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"},"data":{"$ref":"#/components/schemas/AssetResource"}},"required":["meta","data"]},"TopLevelMeta":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server timestamp in milliseconds"},"authentication":{"type":"string","description":"Authentication method, e.g. apiKey"},"links":{"type":"object","properties":{"me":{"type":"string","format":"uri"}}}}},"JsonApiLinkage":{"type":"object","properties":{"self":{"$ref":"#/components/schemas/Link"},"thumbnail":{"$ref":"#/components/schemas/LinkObject"}},"additionalProperties":true},"Link":{"oneOf":[{"type":"string","format":"uri"},{"$ref":"#/components/schemas/LinkObject"}]},"LinkObject":{"type":"object","description":"JSON:API link object","properties":{"href":{"type":"string","format":"uri"},"meta":{"type":"object","description":"Non-standard meta-information for the link","properties":{"version":{"type":"string","description":"Asset version name used to generate the link (e.g., thumbnail)"}},"additionalProperties":true}},"required":["href"]},"AssetResource":{"type":"object","properties":{"type":{"type":"string","enum":["assets"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/AssetAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"AssetAttributes":{"type":"object","description":"Asset attributes. Fields are optional and may vary by endpoint and permissions.","properties":{"name":{"type":"string"},"createdAt":{"type":"integer","description":"Unix seconds"},"lastModified":{"type":"integer","description":"Unix seconds"},"tags":{"type":"array","items":{"type":"string"}},"versions":{"type":"object","additionalProperties":true},"collectionIds":{"type":"array","items":{"type":"string"}},"collections":{"type":"array","items":{"type":"object"}},"skus":{"type":"array","items":{"type":"string"}},"path":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"views":{"type":"integer"},"downloads":{"type":"integer"},"clientId":{"type":"string"},"createdBy":{"type":"string"},"sensitiveAt":{"type":"integer"},"expires":{"type":"integer"},"licenseExpiresAt":{"type":"integer"},"batchId":{"type":"string"},"favs":{"type":"array","items":{"type":"string"}},"approvedAt":{"type":"integer"},"taskIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorObject"}}},"required":["errors"]},"ErrorObject":{"type":"object","properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["status","title"]},"Error429Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamp":{"type":"integer"},"retryAfter":{"type":"integer"}}}}}]}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429Response"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/assets/{assetId}":{"get":{"summary":"Get asset","operationId":"getAsset","tags":["Assets"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /v1/assets/{assetId}/download

> Download asset version

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Assets"}],"servers":[{"url":"https://app.hivo.com.au/api/rest","description":"Production"}],"security":[{"XUserId":[],"XApiKey":[]}],"components":{"securitySchemes":{"XUserId":{"type":"apiKey","in":"header","name":"X-User-Id","description":"HIVO User ID"}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429Response"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/TopLevelMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorObject"}}},"required":["errors"]},"TopLevelMeta":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server timestamp in milliseconds"},"authentication":{"type":"string","description":"Authentication method, e.g. apiKey"},"links":{"type":"object","properties":{"me":{"type":"string","format":"uri"}}}}},"ErrorObject":{"type":"object","properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["status","title"]},"Error429Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamp":{"type":"integer"},"retryAfter":{"type":"integer"}}}}}]}}},"paths":{"/v1/assets/{assetId}/download":{"get":{"summary":"Download asset version","operationId":"downloadAsset","tags":["Assets"],"parameters":[{"name":"version","in":"query","description":"Version name to download. Defaults to original.","schema":{"type":"string","default":"original"}},{"name":"attachment","in":"query","description":"Set to 1 for Content‑Disposition attachment or 0 for inline.","schema":{"type":"string","enum":["0","1"],"default":"1"}},{"name":"inline","in":"query","description":"Inverse of attachment. Set to 1 for inline or 0 for attachment.","schema":{"type":"string","enum":["0","1"],"default":"0"}}],"responses":{"302":{"description":"Found. Redirect to a short‑lived S3 URL.","headers":{"Location":{"description":"Presigned S3 URL","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```