# Create a Vision Event

Create a single vision event to record an observation from your computer vision deployment.

**Required scope:** `vision-events:write` or `device:update`

{% openapi src="/files/XCSsl1XUH9tiFJObaN6D" path="/vision-events" method="post" %}
[openapi.yaml](https://1284666567-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe5GEiPeDoFksvZv1vH3A%2Fuploads%2Fgit-blob-d74beeed17fc5b3f8e39dcc93a9e9adaa7837101%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Example Request

```bash
curl -X POST "https://api.roboflow.com/vision-events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
      "result": "fail",
      "externalId": "batch-001"
    },
    "customMetadata": {
      "line": "A1",
      "operator": "John Doe",
      "temperature": 72.5
    }
  }'
```

### Request Body Parameters

{% hint style="info" %}
Each event must have a globally unique `eventId`. We recommend using a UUID (v4) to avoid collisions. Duplicate event IDs will overwrite previously ingested events.
{% endhint %}

**Required fields:**

* **`eventId`** (string): Globally unique identifier for the event. Use a UUID (v4).
* **`eventType`** (string): One of `quality_check`, `inventory_count`, `safety_alert`, `custom`, or `operator_feedback`.
* **`useCaseId`** (string, max 256 characters): The use case this event belongs to. See [Use Cases](https://docs.roboflow.com/deploy/vision-events/use-cases) for how to create and manage use cases.
* **`timestamp`** (string, ISO 8601): When the event occurred. Must be between one year ago and tomorrow.
* **`eventData`** (object): Type-specific event data. See [Event Data Schemas](#event-data-schemas) below for the required structure per event type.

**Optional fields:**

* **`deviceId`** (string, max 256): Identifier for the device that generated the event.
* **`streamId`** (string, max 256): Identifier for the video stream.
* **`workflowId`** (string, max 256): Identifier for the workflow that generated the event.
* **`workflowVersion`** (string, max 64): Version of the workflow.
* **`images`** (array, max 1000): Array of image objects with annotations. See [Image Objects](#image-objects) below.
* **`displayImagePosition`** (number, 0-999): The index position of the image in the `images` array to use as the primary display image. For example, `0` for the first image, `1` for the second, and so on.
* **`customMetadata`** (object, max 100 keys): Key-value pairs for custom metadata. See [Custom Metadata](#custom-metadata) below.

### Event Data Schemas

The structure of `eventData` depends on the `eventType`:

{% tabs %}
{% tab title="quality\_check" %}

```json
{
  "result": "pass",
  "externalId": "batch-001"
}
```

* **`result`** (string, optional): `"pass"` or `"fail"`.
* **`externalId`** (string, max 1000, optional): External reference ID.
  {% endtab %}

{% tab title="inventory\_count" %}

```json
{
  "location": "warehouse-a",
  "itemCount": 42,
  "itemType": "pallets",
  "externalId": "inv-2024-001"
}
```

* **`location`** (string, max 1000, optional): Where the count was taken.
* **`itemCount`** (integer, >= 0, optional): Number of items counted.
* **`itemType`** (string, max 1000, optional): Type of item counted.
* **`externalId`** (string, max 1000, optional): External reference ID.
  {% endtab %}

{% tab title="safety\_alert" %}

```json
{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "Worker detected without required PPE in zone B3.",
  "externalId": "alert-2024-001"
}
```

* **`alertType`** (string, max 256, optional): Type of alert (alphanumeric, underscores, and dashes).
* **`severity`** (string, optional): `"low"`, `"medium"`, or `"high"`.
* **`description`** (string, max 10000, optional): Description of the alert.
* **`externalId`** (string, max 1000, optional): External reference ID.
  {% endtab %}

{% tab title="custom" %}

```json
{
  "value": "Custom event data as a string",
  "externalId": "custom-2024-001"
}
```

* **`value`** (string, max 10000, optional): Freeform event data.
* **`externalId`** (string, max 1000, optional): External reference ID.
  {% endtab %}

{% tab title="operator\_feedback" %}

```json
{
  "relatedEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "feedback": "incorrect"
}
```

* **`relatedEventId`** (string, required): The event ID (UUID) of the event this feedback is about.
* **`feedback`** (string, required): `"correct"`, `"incorrect"`, or `"inconclusive"`.
  {% endtab %}
  {% endtabs %}

### Image Objects

To attach images to an event, you must first upload each image using the [Upload a Vision Event Image](/developer/rest-api/vision-events/upload-a-vision-event-image.md) endpoint to get a `sourceId`. Each image object in the `images` array represents an annotated (output) image. If you also want to associate the original unannotated (input) image, upload it separately and pass its `sourceId` as the `inputSourceId`.

```json
{
  "label": "inspection-photo",
  "sourceId": "img-source-123",
  "inputSourceId": "camera-1",
  "objectDetections": [
    {
      "class": "defect",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.95
    }
  ],
  "classifications": [
    {
      "class": "damaged",
      "confidence": 0.87
    }
  ],
  "instanceSegmentations": [
    {
      "class": "crack",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.92,
      "points": [[100, 200], [120, 210], [110, 230]]
    }
  ],
  "keypoints": [
    {
      "class": "joint",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.88,
      "keypoints": [
        { "id": 0, "x": 105, "y": 205, "occluded": false },
        { "id": 1, "x": 115, "y": 215 }
      ]
    }
  ]
}
```

**Image fields:**

* **`label`** (string, optional): A label for the image.
* **`sourceId`** (string, optional): The `sourceId` returned from [uploading the annotated image](/developer/rest-api/vision-events/upload-a-vision-event-image.md).
* **`inputSourceId`** (string, optional): The `sourceId` returned from uploading the original unannotated (input) image.
* **`objectDetections`** (array, max 1000, optional): Bounding box detections with `class`, `x`, `y`, `width`, `height`, and `confidence` (0-1).
* **`classifications`** (array, max 1000, optional): Classification results with `class` and `confidence` (0-1).
* **`instanceSegmentations`** (array, max 1000, optional): Segmentation results with bounding box fields plus `points` (array of `[x, y]` pairs, minimum 3).
* **`keypoints`** (array, max 1000, optional): Keypoint detections with bounding box fields plus `keypoints` (array of objects with `id`, `x`, `y`, and optional `occluded`, minimum 1 keypoint per detection).

### Custom Metadata

You can attach up to 100 key-value pairs of custom metadata to each event. Custom metadata is queryable through the [Query Vision Events](/developer/rest-api/vision-events/query-vision-events.md) endpoint.

**Constraints:**

* Keys must match the pattern `[a-zA-Z0-9_ -]+` (letters, digits, underscores, hyphens, and spaces), max 100 characters.
* String values are limited to 1000 characters.
* Number values support up to 6 decimal places.
* Boolean values are supported.

```json
{
  "customMetadata": {
    "production_line": "A1",
    "shift": "morning",
    "temperature": 72.5,
    "is_overtime": false
  }
}
```

### Example Response

{% tabs %}
{% tab title="201" %}

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "eventType is required"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "error": "Insufficient permissions for this resource."
}
```

{% endtab %}
{% endtabs %}

### Validation and Warnings

The Vision Events API uses eager ingestion. Only the four required fields (`eventId`, `eventType`, `useCaseId`, `timestamp`) are strictly validated. If these pass, the event is always accepted and stored, even if other fields contain errors.

Any issues with non-required fields are returned as a `warnings` array in the response rather than causing a rejection. This includes:

* Missing required fields within `eventData` (e.g., `relatedEventId` for `operator_feedback`)
* Invalid values for `eventData` fields (e.g., wrong enum value for `severity`)
* Unrecognized fields that are not part of the schema

When warnings are present, the invalid `eventData` is stored as an empty object `{}`, but the event itself is still created.

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "warnings": [
    {
      "type": "any.required",
      "path": "eventData.relatedEventId",
      "value": null,
      "valueType": "object"
    }
  ]
}
```

The response may also include a `deprecations` array if deprecated field names were used.


---

# Agent Instructions: 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:

```
GET https://docs.roboflow.com/developer/rest-api/vision-events/create-a-vision-event.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.