# Collections

## GET /v1/collections

> List collections

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Collections"}],"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":{"CollectionListResponse":{"type":"object","properties":{"meta":{"type":"object"},"links":{"$ref":"#/components/schemas/PaginationLinks"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionResource"}}},"required":["meta","data"]},"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}}},"CollectionResource":{"type":"object","properties":{"type":{"type":"string","enum":["collections"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/CollectionAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"CollectionAttributes":{"type":"object","description":"Collection 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"},"createdBy":{"type":"string"},"lastModifiedBy":{"type":"string"},"clientId":{"type":"string"},"description":{"type":"string"},"thumbnailId":{"type":"string"},"thumbnailDescription":{"type":"string"},"path":{"type":"string"},"relatedIds":{"type":"array","items":{"type":"string"}},"favs":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"isPublicCollection":{"type":"boolean"}},"additionalProperties":true},"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"]},"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"}}}}}]}},"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/collections":{"get":{"summary":"List collections","operationId":"listCollections","tags":["Collections"],"parameters":[{"name":"sort","in":"query","description":"Sort key. Allowed values are createdAt, -createdAt, lastModified, -lastModified, name, -name. Defaults to -createdAt.","schema":{"type":"string","enum":["createdAt","-createdAt","lastModified","-lastModified","name","-name"],"default":"-createdAt"}},{"name":"limit","in":"query","description":"Maximum number of collections to return (1–256). Defaults to 32.","schema":{"type":"integer","minimum":1,"maximum":256,"default":32}},{"name":"skip","in":"query","description":"Number of collections to skip (pagination) (0–65536). Defaults to 0.","schema":{"type":"integer","minimum":0,"maximum":65536,"default":0}},{"name":"filter[id]","in":"query","description":"Collection 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[search]","in":"query","description":"General search string (max 256 chars). Prefix‑matches collection name (case‑insensitive).","schema":{"type":"string","maxLength":256}},{"name":"filter[clientId]","in":"query","description":"Admin‑only. Client ID to filter within (ObjectId).","schema":{"type":"string"}},{"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[modifiedMin]","in":"query","description":"Last modified (Unix seconds) lower bound.","schema":{"type":"integer"}},{"name":"filter[modifiedMax]","in":"query","description":"Last modified (Unix seconds) upper bound.","schema":{"type":"integer"}},{"name":"filter[favoriteBy]","in":"query","description":"User ID who favorited the collection (ObjectId).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"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/collections/{collectionId}

> Get collection

```json
{"openapi":"3.0.3","info":{"title":"HIVO REST API","version":"1.0.0"},"tags":[{"name":"Collections"}],"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":{"CollectionResponse":{"type":"object","properties":{"meta":{"type":"object"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"},"data":{"$ref":"#/components/schemas/CollectionResource"}},"required":["data"]},"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"]},"CollectionResource":{"type":"object","properties":{"type":{"type":"string","enum":["collections"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/CollectionAttributes"},"links":{"$ref":"#/components/schemas/JsonApiLinkage"}},"required":["type","id"]},"CollectionAttributes":{"type":"object","description":"Collection 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"},"createdBy":{"type":"string"},"lastModifiedBy":{"type":"string"},"clientId":{"type":"string"},"description":{"type":"string"},"thumbnailId":{"type":"string"},"thumbnailDescription":{"type":"string"},"path":{"type":"string"},"relatedIds":{"type":"array","items":{"type":"string"}},"favs":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"isPublicCollection":{"type":"boolean"}},"additionalProperties":true},"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"}}}}}]}},"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/collections/{collectionId}":{"get":{"summary":"Get collection","operationId":"getCollection","tags":["Collections"],"parameters":[{"name":"filter[clientId]","in":"query","description":"Admin‑only. Client ID to filter within (ObjectId).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"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"}}}}}}
```