Understanding the REST API

The REST API makes the inventory in Docusnap365 available to your own applications: read, query and create assets. It is the way for everything that happens regularly and automatically—reports in your own tool, transfer to another system, your own interfaces on your own data. It returns the same data as the interface under the same rights. For questions in your own words, use the AI Assistant; to connect an AI tool, use the MCP connector. The REST API is the programmatic route.

Address and calls

All calls go to https://api.docusnap365.com/api/v1. The API works with assets only and has seven endpoints:

Task	Endpoint	Access
List assets	`GET /assets`	Read
Read one asset	`GET /asset/{id}`	Read
Query assets, with details	`POST /assets/query`	Read
Load details of one asset	`POST /assets/expand`	Read
Continue paging	`POST /cursor/continue`	Read
Create or update an asset	`POST /asset`	Read and Write
Create or update several assets	`POST /asset/bulk`	Read and Write

Parameters, schemas and examples of each endpoint are in the API reference in the sidebar.

curl https://api.docusnap365.com/api/v1/assets \
  -H "x-api-key: <your key>"

The response is one page of at most 50 assets.

Keys and permissions

Every call carries an API key in the x-api-key header. No other headers and no prior sign-in are needed. Owners and administrators create keys under Administration › Integrations › API Keys; see Manage API keys. When you create a key, you choose the access. Read is enough for the reading endpoints; POST /asset and POST /asset/bulk require Read and Write. A key without the required access receives the response 403. If the key is missing or invalid, the API responds with 401 and no content. A key belongs to a user, and that user’s rights apply: what the user does not see in the interface, the API does not return either. Missing rights do not raise an error—they yield a smaller result set. If you see less than expected, check the user’s rights first, then the query. An asset the user cannot see behaves like a nonexistent one: GET /asset/{id} and POST /assets/expand respond with 404.

Assets and types

An asset consists of its core data and, on request, its details. Every reading endpoint returns the core data: among others id, name, schemaId, objectType, parentId, the assignment to organization, location, platform and domain, as well as status, origin and the creation and modification information. Everything else is not part of the core data and comes through expands. Every asset has a type, schemaId in the API. The type determines which data the asset carries. The types with their fields are in the data model. To create an asset you need the schemaId of the matching type.

Reading and querying

GET /assets returns the first 50 assets. Pass select and search as a JSON array:

GET /api/v1/assets?select=["id","name","status"]&search=["name=SRV"]

search takes entries of the form field=value and finds what contains the value, ignoring case. Several entries apply together. On this endpoint, select only determines which fields are read; the response still carries all fields, with empty values for those not selected. POST /assets/query is the way for filters, sorting and field selection. All parts of the query are optional:

Part	Meaning
`select`	Core data returned; all if omitted
`filter`	Group of conditions with `path`, `op` and `value`, combined with `And` or `Or`; groups can be nested through `groups`
`sort`	Fields with direction (`desc`); `nulls` determines where empty values go
`limit`	Assets per page, default 50
`expands`	Details that come along

{
  "select": ["id", "name", "schemaId"],
  "filter": {
    "logic": "And",
    "conditions": [
      { "path": "objectType", "op": "Eq", "value": "basedef::windows" },
      { "path": "name", "op": "StartsWith", "value": "SRV" }
    ]
  },
  "sort": [{ "path": "name", "desc": false }],
  "limit": 50
}

Filtering and sorting work on the core data only. A path with data. in the filter of the query ends with 400 UNKNOWN_PATH. You read the captured data of a type through an expand and evaluate it in your own application.

Group	Operators	Note
Comparison	`Eq`, `Neq`, `Gt`, `Gte`, `Lt`, `Lte`	`Neq` keeps assets with an empty field
Text	`Contains`, `StartsWith`, `EndsWith`	ignoring case
Pattern	`Like`	with `%` and `_`, case matters
Set	`In`, `NotIn`	`value` is an array; `NotIn` keeps assets with an empty field
Empty	`IsNull`, `IsNotNull`	without `value`
List	`ArrayAny`, `ArrayAll`, `ArrayContains`	for lists in the data of an expand; like `ArrayAny`, `ArrayAll` requires only one matching element

Loading details

An expand loads part of the details for each asset. There are four, with fixed names:

Name	Per asset	Content
`object_data`	one entry	the captured data of the type, for example serial number, manufacturer, operating system
`object_essentials`	several	the quick view, one entry per kind (`quickinfo`, `statistics`)
`object_blocks`	several	the blocks of the asset, each entry a `type` with its data
`children`	several	the child assets with the same core data

An expand has its own select, filter, sort and limit (default 50). select also picks individual values of the data, such as data.serialNumber. Which values a type has is in the data model. A filter on schemaId in the query speeds up the resolution of the data. paths. filter, sort and limit apply per asset for object_essentials, object_blocks and children; for object_data only select applies.

object_blocks is the expensive case: an asset carries several thousand blocks on average, over 95,000 in individual cases. Request this expand only with filter and a small limit.

An unknown name in expands is skipped by POST /assets/query and rejected with 400 by POST /assets/expand. Where the details appear in the response depends on select. With select, each expand appears under its name directly on the asset, object_data as an object, the others as a list. Without select, all expands appear together under expands, each as a list. POST /assets/expand loads one expand for a single asset. parentId and expandName are required. With a cursor from incompleteExpands or nextCursor, the call continues where the cursor was issued; select, filter, sort and limit in the body then do not apply.

Paging with the cursor

Every reading response except GET /asset/{id} has the same shape:

Field	Content
`items`	the assets of this page
`hasMore`	whether more pages follow
`nextCursor`	cursor for the next page, otherwise `null`
`incompleteExpands`	expands that have more entries for an asset than their `limit` allowed

POST /cursor/continue returns the next page with { "cursor": "<nextCursor>" }. The cursor is bound to the subscription and the user and expires after one hour; after that, start the query again. Treat it as an opaque value.

Follow-up pages always carry the full core data and only the expand object_data. A select and the other expands of the first page do not apply there. To get object_essentials, object_blocks and children on every page, call POST /assets/expand per asset.

Creating and updating

POST /asset writes one asset, POST /asset/bulk up to 100 in one transaction. Docusnap365 decides itself whether it already knows the asset: if so, it is updated, otherwise created. The API answers 201 for a newly created asset and 200 for an updated one.

{
  "id": "9e2b7c11-1111-2222-3333-444455556666",
  "schemaId": "…",
  "object": {
    "name": "SRV01",
    "sourceType": "manual",
    "completenessLevel": 80
  },
  "objectData": { "serialNumber": "CZC811922L" }
}

Field	Meaning
`schemaId`	Type of the asset, required
`id`	Identifier of your choice within the request; it comes back in the response as `idPair.fakeId`
`object.name`	Required, at most 256 characters; leading and trailing spaces are removed
`object.completenessLevel`	How complete the source is; protects more complete records from being overwritten by poorer ones
`objectData`	The data of the type according to its data definition; a call replaces it entirely
`essentials`, `facets`	Quick view and ITAM and ISMS data

Without objectData, object.id is required and the asset is updated. A more complete existing record that must not be overwritten, and a record with too few identity values, are rejected. The response names the ID of the asset (id, idPair.dbId), whether it was created (isCreate) and whether it succeeded (isSuccess, otherwise errorMessage). For POST /asset/bulk, results returns one result per entry in the order of the request, matched through idPair.fakeId, plus successCount and failedCount. An entry without object, or with a missing or too long name, aborts the whole call with 400. A protected asset, or one with too few identity values, is skipped and carries its errorMessage in results; the other entries are written.

The status 200 on POST /asset/bulk does not mean that all entries were saved. Check failedCount and results[].isSuccess.

Errors

API errors arrive as application/problem+json according to RFC 9457 with status, errorCode, detail, instance and a traceId. Evaluate errorCode in your application; detail is a technical English sentence that can change and is not shown to end users. When you contact support, include the traceId. Rejections when writing, such as a protected asset, do not arrive as a problem response but as a result with errorMessage. Tell the two forms apart by the content type: application/problem+json versus application/json. Display the messages in errorMessage at most.

Status	`errorCode`	Cause	Action
400	`VALIDATION_FAILED`	Body unreadable, required field missing, unknown operator, unknown `expandName`	Correct the request
400	`INVALID_FORMAT`	`select` or `search` is not a JSON array of strings, or an entry in `search` contains more than one `=`	Correct the parameter
400	`UNKNOWN_PATH`	Field in `select`, `filter` or `sort` unknown, or `data.` path in the main query	Check field names; `data.` paths only in expands
400	`FIELD_TYPE_MISMATCH`, `UNSUPPORTED_OPERATOR`	Value or operator does not fit the field	Adjust value or operator
400	`INVALID_CURSOR`, `CURSOR_EXPIRED`, `CURSOR_SOURCE_MISMATCH`	Cursor damaged, older than one hour, or does not match `parentId` and `expandName`	Start the query again
401	`UNAUTHORIZED`	Key missing or invalid	Check the key
403	`FORBIDDEN`	Key does not have the required access	Use a key with the right access
403	`CURSOR_USER_MISMATCH`, `CURSOR_DATA_SOURCE_MISMATCH`	Cursor comes from another user or another subscription	Start your own query
404	`NOT_FOUND`	Asset does not exist or is not visible, or unknown endpoint	Check ID and rights
429	`REST_REQUEST_QUOTA_EXCEEDED`	Quota used up	Wait until `Retry-After`
500	`INTERNAL_ERROR`	Unexpected error	Contact support with the `traceId`
503	`SERVICE_UNAVAILABLE`	The quota could not be checked; the request was not executed	Retry later

Quota

Every call to one of the seven endpoints counts one request against the subscription’s quota (API & MCP Requests); the REST API and MCP share this quota. The request counts even if it fails afterwards, for example on an unknown field or an expired cursor. Requests that already fail on a missing key (401), missing access (403) or an unknown endpoint (404) are not counted. Additional requests are not reset with the period; the included ones are. When both are used up, the API responds with 429 and does not execute the request; rejected requests count as well. With a limited quota, all responses, including error responses, carry these headers:

Header	Content
`X-RateLimit-Limit`	Requests included in the period
`X-RateLimit-Remaining`	Requests still available, included and additional combined
`X-RateLimit-Extra-Remaining`	Of these, additional requests still available
`X-RateLimit-Reset`	Start of the next period as a Unix timestamp in seconds
`Retry-After`	Only with `429`: start of the next period as an HTTP date

With an unlimited quota, these headers are absent.

The API reference (in the sidebar under API Reference)—all endpoints with parameters, schemas and examples
Data model—types, fields, properties
Manage API keys—create keys, permissions, expiry
AI Connections—quota usage

​Address and calls

​Keys and permissions

​Assets and types

​Reading and querying

​Loading details

​Paging with the cursor

​Creating and updating

​Errors

​Quota

​Related

Address and calls

Keys and permissions

Assets and types

Reading and querying

Loading details

Paging with the cursor

Creating and updating

Errors

Quota

Related