> ## 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.

# Understanding the REST API

> What the Docusnap365 REST API can do, how you authenticate, and how query, cursor and details fit together.

The REST API gives external systems access to a tenant's assets: read, query,
create. It returns the same data as the interface under the same rights — no
more, no less.

## What the API can do

The API works with **assets** only: the systems, devices, applications and
manually created objects of the inventory. It can

* **list and read** assets — individually or page by page,
* **query** assets — with filter, sorting and field selection,
* **create** assets — individually or up to 100 in one call.

It **cannot** start scans, edit risks or controls, or read or write documents.
There are no endpoints for that.

<Note>
  The API grows with the product. Further areas — ITAM, ISMS, documents — will
  follow; the reference always shows the current state.
</Note>

## Keys and permissions

Every call carries an API key in the `x-api-key` header. You create keys under
*Administration › API keys*; see [Manage API keys](/docs/en/settings/api-access).

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.

Every key carries the *Read* permission; *Write* can be granted in addition.
Read endpoints require *Read*; `POST /asset` and `POST /asset/bulk` require
*Write*.

<Note>
  Only **active** assets are returned. Deleted, archived and hidden assets are
  out of reach — even through a filter on `status`.
</Note>

## The first call

```bash theme={null}
curl https://api.docusnap365.com/api/v1/assets \
  -H "x-api-key: <your key>"
```

The response is one page of at most 50 assets. If it contains a `cursor`,
there are more pages — see below.

## Query, cursor, details

The reference has seven endpoints. Three terms explain how they fit together:

**Query.** `POST /assets/query` is the way for everything beyond a plain list:
filters on fields, sorting, selection of the returned fields. Fields with the
prefix `data.` address the data of the type — which ones exist is in the
[data model](/docs/en/api/data-model).

**Cursor.** Large results come page by page. Every response that is not
complete carries a `cursor`; `POST /cursor/continue` returns the next page
with it. Cursors are bound to tenant and user and expire after one hour.

**Details.** An asset consists of core data and details: the data of its type,
the quick view, typed blocks, child assets. In a query you load details along
through `expands`; for a single asset, `POST /assets/expand` loads them page
by page.

<Warning>
  The expand `object_blocks` is the expensive case: an asset carries several
  thousand blocks on average. Request it only with `limit` or `filter`.
</Warning>

## Types

Every asset has a type — `schemaId` in the API. The type determines which
fields `objectData` carries and which `data.` paths can be queried. The types
with their fields are in the [data model](/docs/en/api/data-model); to create an
asset you need the `schemaId` of the matching type.

## Related

* [API reference](/docs/en/api-reference) — all endpoints with parameters, schemas and examples
* [Data model](/docs/en/api/data-model) — types, fields, properties
* [Manage API keys](/docs/en/settings/api-access) — create keys, permissions, expiry


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.