> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager/services/event-store/rest-api.md).

# Event Store REST API

Endpoint reference for the on-device Event Store v2 API, including event schemas and administration routes.

The Event Store runs on a managed device and stores inference events produced by pipelines on that device. Base URL is `http://<device-ip>:8001`, and interactive Swagger documentation is served at `/docs`. See [Services](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager/services.md#using-the-apis) for the base URL, authentication, and error-shape rules shared by all on-device service APIs.

The v2 API accepts camelCase input (ex: `base64Image`, `objectDetections`) and returns snake\_case responses.

{% hint style="warning" %}
This is not the cloud [Vision Events API](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events.md). The local contract uses `event_schema`, `event_data`, and `inference_timestamp` where the cloud uses `eventType`, `useCaseId`, and `timestamp`, and it takes image bytes directly rather than references to uploaded images. A cloud payload will not validate here.
{% endhint %}

If `API_KEY` is set on the service, data and administration routes require an `X-API-Key` header. `/health`, `/docs`, `/redoc`, and `/openapi.json` remain accessible without it. See [Authentication](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager/services/event-store.md#authentication).

```bash
curl -H "X-API-Key: $EVENT_STORE_API_KEY" \
  "http://<device-ip>:8001/v2/events/latest/query?limit=5"
```

## Create an Event

Bounding box coordinates are center-based absolute pixels: `x` and `y` are the center of the box, `width` and `height` are the full dimensions. Confidence runs from 0.0 to 1.0.

Set `draft: true` to keep the event open so a video or local-only file can be attached after the fact, then finalize it. Omitting `draft` finalizes the event on creation, so existing producers are unaffected.

{% hint style="warning" %}
`solution` is optional in the schema but conditionally required at runtime. When cloud upload is enabled on the service and `DEFAULT_SOLUTION_ID` is not set, creating an event without `solution` returns `400`. Either send it on every event or set the environment variable.
{% endhint %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

## Query Events

`GET /v2/events` filters by time window, source, and custom metadata. `metadata_filter` takes `key:value` or `key:op:value` with the operators `eq`, `ne`, `gt`, `lt`, `gte`, and `lte`, and repeats with AND logic.

Per-image `metadata` is not queryable through `metadata_filter`. Only `custom_metadata` on the event is.

An event can carry `value_base_units`, what it was worth as an integer in the base unit of its use case's currency (for example, cents for USD). The currency is set on the use case in the cloud and is not known on the device. Filter events by value with `has_value`, `value_min`, and `value_max`. `GET /v2/events/value_summary` takes the same filters as `GET /v2/events` with no limit and returns the total value of every matching event. The device does not convert between currencies, so filter by `solution` to total a single use case.

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/{event\_id}" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/latest/query" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/value\_summary" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/events/count/stats" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

## Draft Lifecycle

A producer that needs to attach a video encoded after the pass/fail decision creates the event as a draft, uploads the file when it is ready, then finalizes:

```bash
EVENT_ID=$(curl -s -X POST http://<device-ip>:8001/v2/events \
  -H "Content-Type: application/json" \
  -d '{"inference_timestamp":"2025-01-30T14:30:00Z","event_schema":"quality_check","event_data":{"result":"pass"},"solution":"a1b2c3d4e5f67890","draft":true}' \
  | jq -r '.id')

curl -X POST "http://<device-ip>:8001/v2/events/$EVENT_ID/videos" -F "file=@clip.mp4"
curl -X POST "http://<device-ip>:8001/v2/events/$EVENT_ID/finalize"
```

Until an event is finalized it is skipped by cloud upload. It is also protected from cleanup, but only while cloud upload is enabled on the service. With cloud upload off, a draft is as deletable as any other record, so retention and capacity cleanup can remove one that is still being assembled.

A draft whose producer never calls finalize is force-closed after `DRAFT_AUTO_FINALIZE_SECONDS`. Both `finalized_at` and `auto_finalized_at` are set in that case, so read `auto_finalized_at` to tell a force-closed event from one the producer finalized itself.

To change a draft before you finalize it, send `PATCH /v2/events/{event_id}` with only the fields to change. When you change `event_schema`, send the full `event_data` for the new schema: it replaces the stored value instead of merging, and a request that changes `event_schema` without `event_data` returns `400`.

Attachment routes add bytes, so unlike finalize they are subject to capacity backpressure: when the store is over its limits they return `507` and the upload is not accepted.

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/{event\_id}/videos" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/{event\_id}/local-only-files" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/{event\_id}" method="patch" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/v2/events/{event\_id}/finalize" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

## Event Schemas

`event_schema` selects the structure of `event_data`. [Create an Event](#create-an-event) lists the fields of each schema.

To read `operator_feedback` events back, use the `related_event_id` filter on `GET /v2/events`. For structured data that does not fit a schema, use `custom_metadata` on the event, which is queryable, or per-image `metadata`, which is not.

## Download Files

Image IDs are ephemeral. Cleanup can remove a file at any time, so handle `404` and do not cache IDs beyond a single session. Compare `current_file_count` against `original_file_count` on an event to tell whether its files were cleaned up.

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/images/{image\_id}" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/videos/{video\_id}" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/local-only-files/{file\_id}" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

## Statistics and Health

`/stats` reports current usage, the active configuration, capacity against each limit, and what the next cleanup can delete. Pending uploads, protected drafts, and file errors can prevent those deletions. Alert on `capacity.storage.percent_used` and `capacity.records.percent_used` above 80%.

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/stats" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/health" method="get" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

## Administration

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/admin/cleanup" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

Resetting takes two calls so it cannot happen by accident. `/reset/request` returns a single-use token valid for 60 seconds, and `/reset/confirm` performs the deletion.

{% hint style="danger" %}
A confirmed reset permanently deletes every event and file in the store. It cannot be undone.
{% endhint %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/reset/request" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/I83YpxmNh4upE1YTiRTx" path="/reset/confirm" method="post" %}
[edge-event-store.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-5c7a886be724346fde39b8c2becf4ae0df29f850%2Fedge-event-store.yaml?alt=media)
{% endopenapi %}
