> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/developer/rest-api/manage-images/update-image-metadata-and-tags.md).

# Update Image Metadata and Tags

You can write custom metadata and tags to images in your workspace using the REST API. There are two endpoints: one for updating a single image synchronously, and one for updating up to 1,000 images in a batch.

Both endpoints require an API key with the `image:tag` scope.

## Request Body

Both endpoints accept the same fields (the batch endpoint wraps them in an `updates` array):

```
- imageId (string) - required for batch update in body, inferred ffrom the path in single update
- metadata (object) - Key-value pairs to set on the image's user metadata.
- removeMetadata (string[]) - Metadata keys to delete from the image.
- addTags (string[]) - Tags to add to the image.
- removeTags (string[]) - Tags to remove from the image.
```

You must include at least one of these fields. You cannot set and remove the same metadata key or tag in the same request.

## Single Image

Update metadata and tags for a single image.

```
POST https://api.roboflow.com/:workspace/images/:image/metadata?api_key=API_KEY
```

### Example

```bash
curl -X POST "https://api.roboflow.com/my-workspace/images/abc123/metadata?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": { "camera": "front", "blur_score": 0.8 },
    "addTags": ["reviewed"]
  }'
```

### Response

```json
{
    "success": true
}
```

## Batch Update

Update metadata and tags for multiple images asynchronously. Accepts up to 1,000 images per request.

```
POST https://api.roboflow.com/:workspace/images/metadata?api_key=API_KEY
```

### Example

```bash
curl -X POST "https://api.roboflow.com/my-workspace/images/metadata?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "imageId": "abc123",
        "metadata": { "camera": "front" },
        "addTags": ["reviewed"]
      },
      {
        "imageId": "def456",
        "removeTags": ["needs-review"]
      }
    ]
  }'
```

### Response

Returns `202` with a task ID. Poll the task URL to check progress.

```json
{
    "taskId": "task-id-here",
    "url": "https://api.roboflow.com/my-workspace/asynctasks/task-id-here"
}
```

See [Async Tasks](/developer/rest-api/async-tasks.md) for how to poll the task status.

## Errors

```
- 400 - Empty body, malformed field types, or conflicting fields (e.g. same key in both metadata and removeMetadata).
- 404 - Image not found in the workspace (single image endpoint only).
```