> ## Documentation Index > Fetch the complete documentation index at: https://www.docusnap.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Query assets > Queries assets with filter, sort, field selection, page size and expands. Only the fields of the asset are available for `select`, `filter` and `sort` (see `AssetDto`). Expands add related data; `data.` paths in an expand are resolved against the types. With `select` the response items contain only the selected properties, and the expands are lifted to the top level of the item. Without `select` an item is the complete asset with its expands in `expands`. A page holds `limit` items (default 50). If more exist, `hasMore` is true and `nextCursor` continues with `POST /cursor/continue`. An expand that holds more rows than its `limit` for an asset is reported in `incompleteExpands`; continue it with `POST /assets/expand`. Requires the scope `api_read` (*Read*). ## OpenAPI ````yaml /api-reference/openapi.en.yaml post /assets/query openapi: 3.0.3 info: title: Docusnap365 REST API version: v1 description: > The public REST API of Docusnap365 for reading, querying and writing assets. **Request flow.** Every request passes these checks in this order: the API key (401 if it is missing or invalid), the rights of the key (403 if it lacks the right for the operation), the request quota (429, or 503 when the quota cannot be checked), then the operation itself. You grant the rights when you create the API key under *Administration › Integrations › API Keys*: *Read* (`api_read`) or *Read and Write* (`api_write`). **Request quota.** Every call to one of the operations counts as one request. The quota is shared with the MCP server of the same subscription. Once a request has been counted, the `X-RateLimit-*` headers accompany the response, including error responses; a subscription without a limit gets none. **Errors.** Errors are `application/problem+json` (RFC 9457) with the members `type`, `title`, `status`, `detail`, `instance`, `errorCode`, `traceId` and `errors`. Do not parse `detail`. There are two exceptions: the answer 401 has neither a body nor a Content-Type, even when the API key is missing; and on the write path an error of the ingest service is returned unchanged and carries `errorMessage` instead. servers: - url: https://api.docusnap365.com/api/v1 security: - ApiKeyAuth: [] tags: - name: Assets description: Read and write single assets. - name: Query description: Query assets with filter, sort, expands and paging. paths: /assets/query: post: tags: - Query summary: Query assets description: > Queries assets with filter, sort, field selection, page size and expands. Only the fields of the asset are available for `select`, `filter` and `sort` (see `AssetDto`). Expands add related data; `data.` paths in an expand are resolved against the types. With `select` the response items contain only the selected properties, and the expands are lifted to the top level of the item. Without `select` an item is the complete asset with its expands in `expands`. A page holds `limit` items (default 50). If more exist, `hasMore` is true and `nextCursor` continues with `POST /cursor/continue`. An expand that holds more rows than its `limit` for an asset is reported in `incompleteExpands`; continue it with `POST /assets/expand`. Requires the scope `api_read` (*Read*). operationId: queryAssets requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApiQueryRequest' examples: Assets whose name contains a text, newest first: value: select: - id - name - createdAt filter: logic: And conditions: - path: name op: Contains value: server sort: - path: createdAt desc: true limit: 20 An asset with the captured data of its type: value: select: - id - name filter: conditions: - path: id op: Eq value: 3f2504e0-4f89-11d3-9a0c-0305e82c3301 expands: - name: object_data select: - id - data responses: '200': description: A page of assets. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Extra-Remaining: $ref: '#/components/headers/X-RateLimit-Extra-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ApiQueryResponse' '400': description: >- The body cannot be read, a path is not available, a filter value does not fit the field, or an operator cannot be applied to the field. x-error-codes: - VALIDATION_FAILED - UNKNOWN_PATH - FIELD_TYPE_MISMATCH - UNSUPPORTED_OPERATOR content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' examples: A field that is not available: value: type: urn:ds365:error:unknown-path title: Unknown field path status: 400 detail: Field 'hostname' is not configured for source 'objects' instance: /api/v1/assets/query errorCode: UNKNOWN_PATH traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 errors: - code: UNKNOWN_PATH path: filter data: field: hostname source: objects origin: filter '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenRead' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: ApiQueryRequest: title: Query request type: object properties: select: type: array items: type: string description: The fields to return. Without it, all fields of the asset. filter: $ref: '#/components/schemas/ApiFilterGroup' sort: type: array items: $ref: '#/components/schemas/ApiSortField' description: >- The sort order. Without it, by id. The id is always the last sort key unless it is sorted explicitly. limit: type: integer format: int32 default: 50 description: The page size. expands: type: array items: $ref: '#/components/schemas/ApiExpandDefinition' description: >- Related data to read with each asset. An unknown name is skipped without an error. ApiQueryResponse: title: Query response type: object required: - items properties: items: type: array items: anyOf: - $ref: '#/components/schemas/AssetDto' - $ref: '#/components/schemas/ExpandRow' description: The assets, or for an expand cursor the rows of the expand. nextCursor: type: string nullable: true description: >- Present when more items exist. Valid for one hour, for the same user and subscription. hasMore: type: boolean description: True when more items exist. incompleteExpands: type: object nullable: true additionalProperties: $ref: '#/components/schemas/ApiIncompleteExpand' description: >- Expands that hold more rows than their `limit`, keyed `name:parentId`. ProblemDetails: title: Problem details type: object description: >- An error according to RFC 9457. `errors` is never empty; for one error `errors[0].code` equals `errorCode`. properties: type: type: string description: >- A URN derived from `errorCode`, for example `urn:ds365:error:not-found`. It cannot be resolved. title: type: string description: A fixed English text per code. status: type: integer description: The HTTP status code. detail: type: string description: >- A technical English sentence. The text may change and should not be evaluated. instance: type: string description: The request path. errorCode: type: string description: >- The error code. The codes of an operation are listed in `x-error-codes` of its response. traceId: type: string description: The trace id of the request. Give it to support. errors: type: array items: $ref: '#/components/schemas/ProblemErrorItem' ApiFilterGroup: title: Filter group type: object properties: logic: allOf: - $ref: '#/components/schemas/FilterLogic' default: And conditions: type: array items: $ref: '#/components/schemas/ApiFilterCondition' groups: type: array items: $ref: '#/components/schemas/ApiFilterGroup' description: Nested groups. They are combined with the conditions by `logic`. ApiSortField: title: Sort field type: object required: - path properties: path: type: string description: The field to sort by. desc: type: boolean default: false description: Sort descending. nulls: allOf: - $ref: '#/components/schemas/NullsPosition' default: Default ApiExpandDefinition: title: Expand definition type: object required: - name properties: name: type: string enum: - object_data - object_essentials - object_blocks - children description: > The related data. `object_data` is the captured data of the type (one row), `object_essentials` the essentials (one row per type), `object_blocks` the blocks of the asset (very many rows; always set a `limit`), `children` the assets below it. select: type: array items: type: string description: >- The fields of the expand. In `object_data`, `object_essentials` and `object_blocks` also paths into `data`, for example `data.cpuCores` (depends on the type of the asset). filter: $ref: '#/components/schemas/ApiFilterGroup' sort: type: array items: $ref: '#/components/schemas/ApiSortField' limit: type: integer format: int32 default: 50 description: The number of rows per asset. AssetDto: title: Asset type: object additionalProperties: true description: > An asset. With `select` on `POST /assets/query` an item holds only the selected properties and the lifted expands under their names (`object_data` as an object, the others as a list). properties: id: type: string format: uuid entityId: type: string format: uuid nullable: true schemaId: type: string format: uuid description: The type of the asset. parentId: type: string format: uuid nullable: true name: type: string objectType: type: string type: type: string iconId: type: string sourceType: type: string organizationId: type: string format: uuid nullable: true locationId: type: string format: uuid nullable: true platformId: type: string format: uuid nullable: true domainId: type: string format: uuid nullable: true version: type: integer format: int32 status: type: string isManually: type: boolean createdAt: type: string format: date-time nullable: true createdBy: type: string format: uuid nullable: true createdByDisplayName: type: string modifiedAt: type: string format: date-time nullable: true modifiedBy: type: string format: uuid nullable: true modifiedByDisplayName: type: string deletedAt: type: string format: date-time nullable: true deletedBy: type: string format: uuid nullable: true deletedByDisplayName: type: string expands: type: object nullable: true additionalProperties: type: array items: $ref: '#/components/schemas/ExpandRow' description: >- The expands by name. Only in the complete form, not when `select` lifted them. ExpandRow: title: Expand row type: object additionalProperties: true description: >- One row of an expand. Columns without a value are omitted. JSON columns (`data`) are returned as JSON. ApiIncompleteExpand: title: Incomplete expand type: object required: - parentId - cursor properties: parentId: type: string format: uuid description: The asset whose expand is incomplete. cursor: type: string description: The cursor to continue the expand with `POST /assets/expand`. loadedCount: type: integer format: int32 description: The number of rows already returned. ProblemErrorItem: title: Error item type: object required: - code properties: code: type: string description: The specific code of this item. path: type: string description: >- The field or parameter the error concerns. Absent when it concerns the whole request. data: type: object additionalProperties: true description: >- Further values, for example `entityType` and `id` of a missing asset or `missingScopes`. Absent when empty. FilterLogic: title: Logical operator type: string description: How the conditions and groups of a group are combined. enum: - And - Or ApiFilterCondition: title: Filter condition type: object required: - path - op properties: path: type: string description: The field. Only fields of the source are available. op: $ref: '#/components/schemas/FilterOperator' value: description: >- The comparison value. Its JSON type must fit the field; a list for `In` and `NotIn`. arrayFilter: $ref: '#/components/schemas/ApiFilterGroup' NullsPosition: title: Position of empty values type: string description: >- Where empty values appear in the sort order. `Default` leaves it to the database. enum: - Default - First - Last FilterOperator: title: Filter operator type: string description: > The operator of a condition. Case-insensitive in the request body. `Eq`, `Neq`, `Gt`, `Gte`, `Lt`, `Lte` compare. `Neq` and `NotIn` keep rows whose field is empty. `Contains`, `StartsWith`, `EndsWith` match text without regard to case; `%`, `_` and `\` in `value` are taken literally. `Like` is SQL LIKE with the wildcards of the caller and regard to case. `In` and `NotIn` take a list in `value`. `IsNull` and `IsNotNull` need no `value`. `ArrayAny` is true when at least one element of a JSON array satisfies `arrayFilter`. `ArrayContains` is true when the JSON array contains `value`. Comparison and list operators (`Eq`, `Neq`, `Gt`, `Gte`, `Lt`, `Lte`, `In`, `NotIn`) are rejected on a field that holds a JSON object or array. enum: - Eq - Neq - Gt - Gte - Lt - Lte - Contains - StartsWith - EndsWith - Like - In - NotIn - IsNull - IsNotNull - ArrayAny - ArrayContains headers: X-RateLimit-Limit: description: >- Requests included per quota period. Not sent for a subscription without a limit. schema: type: integer X-RateLimit-Remaining: description: Included plus extra requests still available in the running period. schema: type: integer X-RateLimit-Extra-Remaining: description: Extra requests still available. They are not reset with the period. schema: type: integer X-RateLimit-Reset: description: Start of the next quota period as Unix time in seconds. schema: type: integer format: int64 Retry-After: description: >- Start of the next quota period as an HTTP date. The same instant as `X-RateLimit-Reset`. schema: type: string responses: Unauthorized: description: The API key is missing or invalid. x-error-codes: - UNAUTHORIZED ForbiddenRead: description: >- The key lacks the scope `api_read` (*Read*), or the permission layer of the database refused the access. x-error-codes: - FORBIDDEN - PERMISSION_DENIED - MODULE_NOT_IN_EDITION - TENANT_FROZEN content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' examples: A key without the required scope: value: type: urn:ds365:error:forbidden title: Forbidden status: 403 detail: 'Missing required scopes: api_read' instance: /api/v1/assets errorCode: FORBIDDEN traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 errors: - code: FORBIDDEN data: missingScopes: - api_read TooManyRequests: description: >- The request quota of the subscription is used up, included and extra requests alike. Retry after the instant in `Retry-After`. A denied request is counted as well. x-error-codes: - REST_REQUEST_QUOTA_EXCEEDED headers: Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Extra-Remaining: $ref: '#/components/headers/X-RateLimit-Extra-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' examples: The quota is used up: value: type: urn:ds365:error:rest-request-quota-exceeded title: Request quota exceeded status: 429 detail: >- The request quota of 10000 requests per period is exhausted until 2026-12-01T00:00:00.0000000+00:00. instance: /api/v1/assets errorCode: REST_REQUEST_QUOTA_EXCEEDED traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01 errors: - code: REST_REQUEST_QUOTA_EXCEEDED data: requestsLimit: 10000 requestsUsed: 10000 quotaResetAt: '2026-12-01T00:00:00+00:00' InternalError: description: >- An unexpected fault. `detail` is a fixed sentence; use `traceId` when reporting it. x-error-codes: - INTERNAL_ERROR content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' ServiceUnavailable: description: >- The request quota could not be checked and the request was therefore not served, or the database failed transiently. Retrying may succeed. x-error-codes: - SERVICE_UNAVAILABLE content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- The API key of the subscription. Each operation names the scope it needs in `x-pat-scopes`: `api_read` (in the interface *Read*) or `api_write` (*Read and Write*). The key is created under *Administration › Integrations › API Keys*. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.