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

Create a Vision Event

post

Create a single vision event.

Authorizations

bearerAuth

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Body

application/json

eventIdstringRequired

Globally unique identifier. Use a UUID (v4).

eventTypestring · enumRequiredPossible values:

useCaseIdstring · max: 256Required

The use case this event belongs to.

timestampstring · date-timeRequired

ISO 8601 timestamp. Must be between one year ago and tomorrow.

deviceIdstring · max: 256Optional

streamIdstring · max: 256Optional

workflowIdstring · max: 256Optional

workflowVersionstring · max: 64Optional

displayImagePositioninteger · max: 999Optional

eventDataobjectRequired

Type-specific event data. Structure depends on eventType.

Responses

201

Event created successfully.

application/json

eventIdstringOptional

createdbooleanOptional

deprecationsstring[]Optional

400

Validation error.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events

HTTPcURLJavaScriptPython

POST /vision-events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 720

{
  "eventId": "text",
  "eventType": "quality_check",
  "useCaseId": "text",
  "timestamp": "2026-07-16T20:04:11.918Z",
  "deviceId": "text",
  "streamId": "text",
  "workflowId": "text",
  "workflowVersion": "text",
  "images": [
    {
      "label": "text",
      "sourceId": "text",
      "inputSourceId": "text",
      "objectDetections": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1
        }
      ],
      "classifications": [
        {
          "class": "text",
          "confidence": 1
        }
      ],
      "instanceSegmentations": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "points": [
            [
              1
            ]
          ]
        }
      ],
      "keypoints": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "keypoints": [
            {
              "id": 1,
              "x": 1,
              "y": 1,
              "occluded": true
            }
          ]
        }
      ]
    }
  ],
  "displayImagePosition": 1,
  "eventData": {},
  "customMetadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "eventId": "text",
  "created": true,
  "warnings": [
    {
      "type": "text",
      "path": "text",
      "value": "text",
      "valueType": "text"
    }
  ],
  "deprecations": [
    "text"
  ]
}

Example Request

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

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.

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

Event Data Schemas

The structure of eventData depends on the eventType:

quality_check

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

• result (string, optional): "pass" or "fail".

• externalId (string, max 1000, optional): External reference ID.

inventory_count

safety_alert

custom

operator_feedback

Image Objects

To attach images to an event, you must first upload each image using the Upload a Vision Event Image 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.

{
  "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.

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

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

Example Response

201

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

400

403

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.

{
  "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.