> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api.md).

# Oz API

<figure><img src="/files/BTOW2K47EB8nhvHCQI4q" alt=""><figcaption></figcaption></figure>

Oz API is the most important component of the system – it connects all the other components together, and it is the unified REST interface you call to run **Liveness** and **Biometry** analyses. Oz API:

* provides the unified REST API interface to run the Liveness and Biometry analyses,
* processes authorization and user-permission management,
* tracks and records requested orders and analyses to the database (for example, in 6.0 the database size for 100 000 orders with analyses is \~4 GB),
* archives the inbound media files,
* collects telemetry from connected mobile apps,
* provides settings for specific device models,
* generates reports with analyses' results.

For the latest API methods collection, please refer to our [API reference](https://apidoc.ozforensics.com/).

### Persistent and non-persistent (Instant) modes

Oz API runs the same analyses in two modes that differ mostly in **what is stored**:

|                | Persistent (`/api/folders/`)                                                                  | Non-persistent – Instant API (`/api/instant/folders/`)          |
| -------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| What is stored | Creates a folder; media, analyses, results, and reports are stored and can be retrieved later | Nothing is stored – the result exists only in the HTTP response |
| Best for       | Case history, the Web Console, reports, webhooks, re-analysis                                 | Sensitive data, GDPR compliance, a minimal storage footprint    |

Instant API is part of Oz API, not a separate product: it exposes the same analyses through a non-persistent endpoint, and it supports both submission modes described below.

### Single request and multi-request

You can submit your media and analyses in two ways, available in both the persistent and Instant modes:

* [**Single request**](/oz-knowledge/guides/developer-guide/api/oz-api/single-request.md) – send all the media together with the analysis request in one call and receive the results in the same response. This removes the need for multiple API calls – one is sufficient. Introduced in API 6.0.
* **Multi-request** – create the folder, upload the media, assign the analyses, and then poll for the result or receive it via a webhook. Use this for larger media, deferred analysis, or operator review.

### OzCapsula secure capture

For maximum protection of the captured media, the Oz SDKs can pack a capture into [**OzCapsula**](/oz-knowledge/guides/developer-guide/api/oz-api/ozcapsula-data-container.md) – a proprietary, encrypted, integrity-protected data container tied to a single capture session by a short-lived `session_token`. The container is an opaque blob: it is forwarded to the API as-is (with `Content-Type: application/octet-stream`) and validated server-side, which defends against injection, tampering, and replay of the captured data.

{% hint style="info" %}
OzCapsula containers are currently submitted **only via single request** – on either `POST /api/folders/` (persistent) or `POST /api/instant/folders/` (Instant).
{% endhint %}

### Authentication

Oz API calls are [authorized](/oz-knowledge/guides/developer-guide/api/oz-api/use-cases/authentication.md) with a token passed in the `X-Forensic-Access-Token` header. You obtain it by logging in with credentials or by using a long-lived **service token** for server-to-server integrations. Instant API can optionally be run without authorization.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.