Upload a Vision Event Bundle

About

The Write Vision Event Bundle block writes one tarball per event to local disk instead of sending it to Roboflow. Use it when your inference server runs in a network with no route to the cloud. This endpoint takes those tarballs as they are: your uploader posts each file, and Roboflow unpacks it, uploads the images, and creates the Vision Event.

HTTP API

Post the raw archive bytes as the request body. Do not use JSON or multipart. The body is binary, so send your API key in the Authorization: Bearer header or in the api_key query parameter.

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

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

binary

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events/bundle' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/gzip' \
  --header 'Accept: application/json' \
  --data 'binary'

const response = await fetch("https://api.roboflow.com/vision-events/bundle", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/gzip",
    "Accept": "application/json"
  },
  body: JSON.stringify(binary)
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/bundle"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/gzip",
    "Accept": "application/json"
}
payload = binary

response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "images": [
    {
      "file": "images/9f0c1b2a-4d3e-4f5a-8b6c-7d8e9f0a1b2c.jpg",
      "sourceId": "src_abc123"
    }
  ],
  "warnings": [
    {
      "type": "text",
      "path": "text",
      "value": "text",
      "valueType": "text"
    }
  ],
  "deprecations": [
    "text"
  ]
}

{
  "error": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

Bundle Format

Each bundle holds one event. The block writes gzipped tar files, and plain tar also works.

event_<timestamp>_<eventId>.tar.gz
├── payload.json
└── images/<file_id>.jpg

payload.json has the same shape as the Create a Vision Event request body, with two differences:

• bundleFormatVersion is 1.
• images[].file and images[].inputFile hold archive member paths (ex: images/9f0c1b2a.jpg) in place of sourceId and inputSourceId. Roboflow uploads each member and stores the source IDs on the event.

Images must sit under the images/ directory. Members that no image refers to, and top-level directories other than images/, add an ingestion warning but do not stop the event.

Field errors inside payload.json behave the same as on the JSON endpoint. See Validation and Warnings.

Use Case

The useCaseId query parameter overrides the useCaseId in payload.json. If neither one is set, the request fails with a 400. Air-gapped sites normally leave the use case out of the bundle, so no cloud identifiers are stored inside the local network, and set it at upload time instead.

Limits

Retries

You can post the same bundle again after a failed or unclear upload. Images are matched by content, and an event that arrives twice replaces the earlier one. You are billed one time for it.