Upload a Vision Event Bundle

Ingest a tarball bundle written by an air-gapped deployment to create a Vision Event.

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

Upload a Vision Event Bundle

post

Create one vision event from a self-contained tarball bundle written by the Write Vision Event Bundle workflow block. Post the raw archive bytes as the body.

Authorizations

AuthorizationstringRequired

Roboflow API key passed as a Bearer token.

Query parameters

useCaseIdstring · max: 256Optional

The use case the event belongs to. This overrides the useCaseId inside payload.json. Required when the bundle does not carry one.

Body

string · binaryOptional

Gzipped tar archive holding payload.json and its image members.

Responses

201

Event created successfully.

application/json

eventIdstringOptionalExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

createdbooleanOptionalExample: true

deprecationsstring[]Optional

400

Bad archive, bad payload, more than 100 images, or no use case in the query or the payload.

application/json

403

Insufficient permissions for this resource.

application/json

413

A size limit was exceeded.

application/json

post/vision-events/bundle

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

"binary"

{
  "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"
  ]
}

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

Limit	Value	Status on failure
Request body	25 MB	413
Decompressed archive	75 MB	413
payload.json	10 MB	413
Archive entries	217	413
Images per bundle	100	400
Pixels per image	80 MP	413

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.