Update Blob Object Settings
curl --request PATCH \
--url https://blob.vertracloud.app/v1/objects/{object_id} \
--header 'Content-Type: application/json' \
--data '
{
"visibility": "<string>",
"cache_control": {},
"content_disposition": {},
"filename": {},
"expires_at": {},
"metadata": {}
}
'import requests
url = "https://blob.vertracloud.app/v1/objects/{object_id}"
payload = {
"visibility": "<string>",
"cache_control": {},
"content_disposition": {},
"filename": {},
"expires_at": {},
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
visibility: '<string>',
cache_control: {},
content_disposition: {},
filename: {},
expires_at: {},
metadata: {}
})
};
fetch('https://blob.vertracloud.app/v1/objects/{object_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://blob.vertracloud.app/v1/objects/{object_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'visibility' => '<string>',
'cache_control' => [
],
'content_disposition' => [
],
'filename' => [
],
'expires_at' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://blob.vertracloud.app/v1/objects/{object_id}"
payload := strings.NewReader("{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://blob.vertracloud.app/v1/objects/{object_id}")
.header("Content-Type", "application/json")
.body("{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://blob.vertracloud.app/v1/objects/{object_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"path": "images/logo.png",
"size": 48213,
"content_type": "image/png",
"etag": "9b2cf535f27731c974343645a3085d39",
"sha256": null,
"visibility": "public",
"url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
"cache_control": null,
"content_disposition": "inline",
"filename": null,
"metadata": {},
"expires_at": null,
"created_at": "2026-10-14T12:00:00.000Z",
"updated_at": "2026-10-14T12:00:00.000Z"
}
}
Objects
Update Blob Object Settings
Changes an object’s visibility, cache, download name, expiration or metadata without re-uploading the file.
PATCH
/
v1
/
objects
/
{object_id}
Update Blob Object Settings
curl --request PATCH \
--url https://blob.vertracloud.app/v1/objects/{object_id} \
--header 'Content-Type: application/json' \
--data '
{
"visibility": "<string>",
"cache_control": {},
"content_disposition": {},
"filename": {},
"expires_at": {},
"metadata": {}
}
'import requests
url = "https://blob.vertracloud.app/v1/objects/{object_id}"
payload = {
"visibility": "<string>",
"cache_control": {},
"content_disposition": {},
"filename": {},
"expires_at": {},
"metadata": {}
}
headers = {"Content-Type": "application/json"}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
visibility: '<string>',
cache_control: {},
content_disposition: {},
filename: {},
expires_at: {},
metadata: {}
})
};
fetch('https://blob.vertracloud.app/v1/objects/{object_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://blob.vertracloud.app/v1/objects/{object_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'visibility' => '<string>',
'cache_control' => [
],
'content_disposition' => [
],
'filename' => [
],
'expires_at' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://blob.vertracloud.app/v1/objects/{object_id}"
payload := strings.NewReader("{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://blob.vertracloud.app/v1/objects/{object_id}")
.header("Content-Type", "application/json")
.body("{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://blob.vertracloud.app/v1/objects/{object_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"visibility\": \"<string>\",\n \"cache_control\": {},\n \"content_disposition\": {},\n \"filename\": {},\n \"expires_at\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"path": "images/logo.png",
"size": 48213,
"content_type": "image/png",
"etag": "9b2cf535f27731c974343645a3085d39",
"sha256": null,
"visibility": "public",
"url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
"cache_control": null,
"content_disposition": "inline",
"filename": null,
"metadata": {},
"expires_at": null,
"created_at": "2026-10-14T12:00:00.000Z",
"updated_at": "2026-10-14T12:00:00.000Z"
}
}
Changes the settings of one object without touching its bytes. Send only the fields to change. Changing
visibility to public makes the object reachable at its public url; changing it to private removes that URL. Sending null restores the default of a field.
Scope: blob:write.
string
required
The object ID.
string
public or private.string | null
immutable, max-age=<seconds> or no-cache (Enterprise-26 or higher). null restores the default.string | null
inline or attachment. null restores the default.string | null
Name suggested on download.
null uses the last segment of path.string | null
ISO 8601 timestamp for deletion, at least the plan’s minimum from now.
null removes the expiration.object
Keys to set. A key with the value
null is removed. Up to 5 keys in total, 512 bytes; Enterprise-12 or higher.string
The workspace ID, when the blob belongs to a workspace. The call acts on the blob of the workspace owner and needs the
blob:read workspace permission (blob:manage on routes that change data). Leave it out to act on your own blob.Example request
curl -X PATCH "https://blob.vertracloud.app/v1/objects/0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c" \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"visibility":"private","metadata":{"owner":"joao","old-key":null}}'
Response
object
The updated blob object.
Show properties
Show properties
string
Stable ID of the object. It never changes, even when the path, visibility or expiration does.
string
Full path inside the account, for example
images/avatars/joao.png.number
Size in bytes.
string
MIME type, derived on the server from the file extension.
string
Entity tag of the stored content.
string | null
SHA-256 of the content in hex, when the upload sent a checksum.
null otherwise.string
public (readable through its public URL) or private (needs a temporary link or a share).string | null
Public URL.
null while the object is private.string | null
immutable, max-age=<seconds> or no-cache (no-cache needs Enterprise-26 or higher). null means the default.string
inline (shown by the browser) or attachment (downloaded). HTML, SVG and XML are always attachment.string | null
Name suggested on download.
null uses the last segment of path.object
Up to 5 keys, each
[a-z0-9-]{1,64}, 512 bytes in total. Enterprise-12 or higher; {} on other plans.string | null
When the object is deleted, as an ISO 8601 timestamp.
null means no expiration.string
ISO 8601 creation time.
string
ISO 8601 time of the last change.
{
"response": {
"id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"path": "images/logo.png",
"size": 48213,
"content_type": "image/png",
"etag": "9b2cf535f27731c974343645a3085d39",
"sha256": null,
"visibility": "public",
"url": "https://blob.vertracloud.dev/k7p2m9x4qa/images/logo.png",
"cache_control": null,
"content_disposition": "inline",
"filename": null,
"metadata": {},
"expires_at": null,
"created_at": "2026-10-14T12:00:00.000Z",
"updated_at": "2026-10-14T12:00:00.000Z"
}
}
Error Responses
string
The error code indicating the reason for failure. Possible values:
AUTH_TOKEN_MISSING(401): NoAuthorizationheader was sent.API_KEY_INVALID(401): The API key doesn’t exist, was revoked, or its secret doesn’t match.API_KEY_SCOPE_DENIED(403): The key lacks the scope this route needs (blob:readorblob:write);details.requirednames it.WORKSPACE_PERMISSION_DENIED(403): Only withworkspace_id: you’re not a member, or your role lacks the blob permission.WORKSPACE_NOT_FOUND(404): Only withworkspace_id: no workspace with that ID, or you’re not a member.BLOB_NAMESPACE_SUSPENDED(403): The account’s blob storage is suspended, or its plan expired. Uploads and other writes are refused from the start of the 72-hour grace period.VALIDATION_ERROR(400): A parameter or body field failed validation.details.pathnames the field.BLOB_OBJECT_NOT_FOUND(404): No object with that ID in this account (or the workspace’s blob).PLAN_RESTRICTED_FEATURE(403): The plan doesn’t include the setting you sent, such asmetadatabelow Enterprise-12 orno-cachebelow Enterprise-26.
{
"code": "AUTH_TOKEN_MISSING"
}
{
"code": "API_KEY_SCOPE_DENIED"
}
{
"code": "WORKSPACE_NOT_FOUND"
}
{
"code": "VALIDATION_ERROR"
}