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

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

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

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.

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

See Async Tasks 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).