# 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`

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

### Example Request

```bash
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

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

```json
{
  "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](https://docs.roboflow.com/developer/rest-api/vision-events/create-a-vision-event):

```json
{
  "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"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "No file provided"
}
```

{% endtab %}

{% tab title="403" %}

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

{% endtab %}
{% endtabs %}