API
Update & Delete Media
Rename media, update metadata, or soft-delete media items
Update & Delete Media
Update Media
Rename a media item or update its metadata JSONB field.
Endpoint
PATCH /api/media/{mediaId}Request Body
At least one field is required:
| Field | Type | Description |
|---|---|---|
name | string | New display name |
metadata | object | Full metadata replacement (JSONB) |
Partial metadata updates
metadata is replaced entirely — not merged. To update only tags, fetch the current metadata first with GET /api/media/{id}, merge your changes, then PATCH the full object.
For tag-only updates, use the dedicated Tags endpoints which do atomic add/remove operations.
Example Request
# Rename
curl -X PATCH https://lab.coreviz.io/api/media/MEDIA_ID \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "hero-shot-final.jpg" }'Response
Status Code: 200 OK
{
"media": {
"id": "abc123def456",
"name": "hero-shot-final.jpg",
"updatedById": "userId123",
"updatedAt": "2026-03-23T10:00:00.000Z"
}
}Error Responses
| Status | Description |
|---|---|
400 | Neither name nor metadata was provided |
401 | Missing or invalid authentication |
404 | Media not found |
Delete Media
Soft-delete a media item (and all its versions). Sets status = "deleted" on the item, its frames, detected objects, and any derived versions. Decrements the organization's storage counter.
Endpoint
DELETE /api/media/{mediaId}Example Request
curl -X DELETE https://lab.coreviz.io/api/media/MEDIA_ID \
-H "x-api-key: YOUR_API_KEY"Response
Status Code: 200 OK
{
"id": "abc123def456",
"deletedCount": 3
}| Field | Type | Description |
|---|---|---|
id | string | ID of the deleted item |
deletedCount | integer | Number of versions deleted (1 for originals with no edits) |
Error Responses
| Status | Description |
|---|---|
401 | Missing or invalid authentication |
404 | Media not found |
JavaScript Examples
const headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
};
// Rename
await fetch('https://lab.coreviz.io/api/media/MEDIA_ID', {
method: 'PATCH',
headers,
body: JSON.stringify({ name: 'new-name.jpg' }),
});
// Delete
await fetch('https://lab.coreviz.io/api/media/MEDIA_ID', {
method: 'DELETE',
headers: { 'x-api-key': 'YOUR_API_KEY' },
});