Upload a Vision Event Image

Upload an image for use in vision events. This is a workspace-level upload that is not associated with any specific project. The returned sourceId can be referenced in the images array when creating events.

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

Upload a Vision Event Image

post

Upload an image for use in vision events.

Authorizations

bearerAuth

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Body

multipart/form-data

filestring · binaryRequired

The image file to upload.

namestringOptional

Custom name for the image.

metadatastringOptional

JSON string of custom metadata.

Responses

201

Image uploaded successfully.

application/json

successbooleanOptional

sourceIdstringOptional

Reference ID for use in event images.

urlstringOptional

Public URL of the uploaded image.

400

Missing file or invalid metadata.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events/upload

HTTPcURLJavaScriptPython

POST /vision-events/upload HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 49

{
  "file": "binary",
  "name": "text",
  "metadata": "text"
}

{
  "success": true,
  "sourceId": "text",
  "url": "text"
}

Example Request

curl -X POST "https://api.roboflow.com/vision-events/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@inspection-photo.jpg" \
  -F "name=inspection-photo.jpg"

Request Parameters

Send as multipart/form-data:

• file (binary, required): The image file to upload. Supported formats: JPEG, PNG, WebP, GIF, TIFF, BMP, HEIC, and AVIF.

• name (string, optional): A custom name for the image.

• metadata (JSON string, optional): Custom metadata to attach to the image. Must be a valid JSON object following the same constraints as event custom metadata: max 100 keys, key names must match [a-zA-Z0-9_ -]+ (max 100 characters), string values max 1000 characters, number and boolean values are also supported.

Example Response

201

{
  "success": true,
  "sourceId": "ve-img-abc123def456",
  "url": "https://storage.roboflow.com/vision-events/images/ve-img-abc123def456.jpg"
}

Use the sourceId value in the images[].sourceId field when creating a vision event:

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "quality_check",
  "useCaseId": "a1b3c8e1",
  "timestamp": "2024-01-15T10:30:00Z",
  "images": [
    {
      "sourceId": "ve-img-abc123def456",
      "objectDetections": [
        {
          "class": "defect",
          "x": 100,
          "y": 200,
          "width": 50,
          "height": 30,
          "confidence": 0.95
        }
      ]
    }
  ],
  "eventData": {
    "result": "fail"
  }
}

400

403