Create a Share Link for a Blob Object
curl --request POST \
--url https://blob.vertracloud.app/v1/shares \
--header 'Content-Type: application/json' \
--data '
{
"object_id": "<string>",
"expires_in": 123,
"max_downloads": 123,
"password": "<string>"
}
'import requests
url = "https://blob.vertracloud.app/v1/shares"
payload = {
"object_id": "<string>",
"expires_in": 123,
"max_downloads": 123,
"password": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
object_id: '<string>',
expires_in: 123,
max_downloads: 123,
password: '<string>'
})
};
fetch('https://blob.vertracloud.app/v1/shares', 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/shares",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'object_id' => '<string>',
'expires_in' => 123,
'max_downloads' => 123,
'password' => '<string>'
]),
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/shares"
payload := strings.NewReader("{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://blob.vertracloud.app/v1/shares")
.header("Content-Type", "application/json")
.body("{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://blob.vertracloud.app/v1/shares")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
"object_id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"url": "https://vertracloud.app/share/xK3mP9qLwT2vN8rY",
"expires_at": "2026-10-15T12:00:00.000Z",
"max_downloads": 10,
"remaining_downloads": 10,
"has_password": false,
"object_is_public": false,
"created_at": "2026-10-14T12:00:00.000Z"
}
}
Shares
Create a Share Link for a Blob Object
Creates a share page link for a blob object, with optional expiration, download limit and password. Returns 201.
POST
/
v1
/
shares
Create a Share Link for a Blob Object
curl --request POST \
--url https://blob.vertracloud.app/v1/shares \
--header 'Content-Type: application/json' \
--data '
{
"object_id": "<string>",
"expires_in": 123,
"max_downloads": 123,
"password": "<string>"
}
'import requests
url = "https://blob.vertracloud.app/v1/shares"
payload = {
"object_id": "<string>",
"expires_in": 123,
"max_downloads": 123,
"password": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
object_id: '<string>',
expires_in: 123,
max_downloads: 123,
password: '<string>'
})
};
fetch('https://blob.vertracloud.app/v1/shares', 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/shares",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'object_id' => '<string>',
'expires_in' => 123,
'max_downloads' => 123,
'password' => '<string>'
]),
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/shares"
payload := strings.NewReader("{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://blob.vertracloud.app/v1/shares")
.header("Content-Type", "application/json")
.body("{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://blob.vertracloud.app/v1/shares")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"object_id\": \"<string>\",\n \"expires_in\": 123,\n \"max_downloads\": 123,\n \"password\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"response": {
"id": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
"object_id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"url": "https://vertracloud.app/share/xK3mP9qLwT2vN8rY",
"expires_at": "2026-10-15T12:00:00.000Z",
"max_downloads": 10,
"remaining_downloads": 10,
"has_password": false,
"object_is_public": false,
"created_at": "2026-10-14T12:00:00.000Z"
}
}
Creates a share link for one private object: a page on the website where the recipient downloads the file. Shares expire after
expires_in seconds (default 24 hours), can stop after max_downloads, and can require a password on Enterprise-12 or higher. A share doesn’t protect a public object, so object_is_public is true in that case.
Scope: blob:write.
string
required
The object to share.
number
Seconds until the share stops working, 60 to 2,592,000 (30 days). Default
86400 (24 hours).number
Download limit, 1–10,000. Omit for no limit.
string
Password the recipient must type, 8–128 characters. 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 POST "https://blob.vertracloud.app/v1/shares" \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"object_id":"0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c","expires_in":3600,"max_downloads":10}'
Response
object
The share link. Responds with
201.Show properties
Show properties
string
Share ID. Use it to revoke the share.
string
The object the share gives access to.
string
Share page URL. Send it to whoever should download the file.
string
When the share stops working, as an ISO 8601 timestamp.
number | null
Download limit.
null means no limit.number | null
Downloads left.
null when there is no limit.boolean
Whether the share asks for a password.
boolean
true when the object is public. A public object is reachable by its URL, so the share doesn’t protect it.string
ISO 8601 creation time.
{
"response": {
"id": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
"object_id": "0b6f7c1e-3d2a-4f5b-9a8c-1d2e3f4a5b6c",
"url": "https://vertracloud.app/share/xK3mP9qLwT2vN8rY",
"expires_at": "2026-10-15T12:00:00.000Z",
"max_downloads": 10,
"remaining_downloads": 10,
"has_password": false,
"object_is_public": false,
"created_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): Theobject_iddoesn’t exist in this account.PLAN_RESTRICTED_FEATURE(403):passwordwas sent on a plan below Enterprise-12.
{
"code": "AUTH_TOKEN_MISSING"
}
{
"code": "API_KEY_SCOPE_DENIED"
}
{
"code": "WORKSPACE_NOT_FOUND"
}
{
"code": "VALIDATION_ERROR"
}