Criar um token de upload para uploads no navegador
curl --request POST \
--url https://blob.vertracloud.app/v1/upload-tokens \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"path": "<string>",
"prefix": "<string>",
"visibility": "<string>",
"max_size": 123,
"allowed_extensions": [
"<string>"
],
"cache_control": "<string>",
"content_disposition": "<string>",
"expires_at": "<string>",
"metadata": {},
"overwrite": true,
"expires_in": 123,
"max_uses": 123
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
path: '<string>',
prefix: '<string>',
visibility: '<string>',
max_size: 123,
allowed_extensions: ['<string>'],
cache_control: '<string>',
content_disposition: '<string>',
expires_at: '<string>',
metadata: {},
overwrite: true,
expires_in: 123,
max_uses: 123
})
};
fetch('https://blob.vertracloud.app/v1/upload-tokens', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://blob.vertracloud.app/v1/upload-tokens"
payload = {
"path": "<string>",
"prefix": "<string>",
"visibility": "<string>",
"max_size": 123,
"allowed_extensions": ["<string>"],
"cache_control": "<string>",
"content_disposition": "<string>",
"expires_at": "<string>",
"metadata": {},
"overwrite": True,
"expires_in": 123,
"max_uses": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://blob.vertracloud.app/v1/upload-tokens"
payload := strings.NewReader("{\n \"path\": \"<string>\",\n \"prefix\": \"<string>\",\n \"visibility\": \"<string>\",\n \"max_size\": 123,\n \"allowed_extensions\": [\n \"<string>\"\n ],\n \"cache_control\": \"<string>\",\n \"content_disposition\": \"<string>\",\n \"expires_at\": \"<string>\",\n \"metadata\": {},\n \"overwrite\": true,\n \"expires_in\": 123,\n \"max_uses\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"response": {
"token": "vcup_9f2c7d1e4b8a6035c2f1d9e7a4b3c8d2",
"expires_at": "2026-10-14T12:15:00.000Z",
"max_uses": 1
}
}
Conta
Criar um token de upload para uploads no navegador
Cria um token de upload de curta duração que fixa o caminho ou a pasta, o tamanho, as extensões e a visibilidade. Use-o no navegador no lugar da sua chave de API.
POST
/
v1
/
upload-tokens
Criar um token de upload para uploads no navegador
curl --request POST \
--url https://blob.vertracloud.app/v1/upload-tokens \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"path": "<string>",
"prefix": "<string>",
"visibility": "<string>",
"max_size": 123,
"allowed_extensions": [
"<string>"
],
"cache_control": "<string>",
"content_disposition": "<string>",
"expires_at": "<string>",
"metadata": {},
"overwrite": true,
"expires_in": 123,
"max_uses": 123
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
path: '<string>',
prefix: '<string>',
visibility: '<string>',
max_size: 123,
allowed_extensions: ['<string>'],
cache_control: '<string>',
content_disposition: '<string>',
expires_at: '<string>',
metadata: {},
overwrite: true,
expires_in: 123,
max_uses: 123
})
};
fetch('https://blob.vertracloud.app/v1/upload-tokens', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://blob.vertracloud.app/v1/upload-tokens"
payload = {
"path": "<string>",
"prefix": "<string>",
"visibility": "<string>",
"max_size": 123,
"allowed_extensions": ["<string>"],
"cache_control": "<string>",
"content_disposition": "<string>",
"expires_at": "<string>",
"metadata": {},
"overwrite": True,
"expires_in": 123,
"max_uses": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://blob.vertracloud.app/v1/upload-tokens"
payload := strings.NewReader("{\n \"path\": \"<string>\",\n \"prefix\": \"<string>\",\n \"visibility\": \"<string>\",\n \"max_size\": 123,\n \"allowed_extensions\": [\n \"<string>\"\n ],\n \"cache_control\": \"<string>\",\n \"content_disposition\": \"<string>\",\n \"expires_at\": \"<string>\",\n \"metadata\": {},\n \"overwrite\": true,\n \"expires_in\": 123,\n \"max_uses\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"response": {
"token": "vcup_9f2c7d1e4b8a6035c2f1d9e7a4b3c8d2",
"expires_at": "2026-10-14T12:15:00.000Z",
"max_uses": 1
}
}
Cria um token de upload que um navegador ou outro cliente não confiável pode usar para enviar arquivos, sem a sua chave de API. O token fixa todas as restrições que você enviar: um
path para um arquivo ou um prefix para qualquer arquivo de uma pasta, o maior tamanho, as extensões permitidas e a visibilidade. Ele funciona somente nas rotas de upload, e deixa de funcionar quando a chave de API que o criou é revogada. O token é mostrado uma única vez.
Escopo: blob:write.
string
Caminho exato para onde o token pode enviar. Use este ou
prefix, não os dois.string
Pasta para onde o token pode enviar. O sufixo aleatório é forçado. Use este ou
path, não os dois.string
public ou private. Fixado pelo token.number
Maior arquivo que o token aceita, em bytes.
string[]
De 1 a 20 extensões, em minúsculas, sem o ponto.
string
cache_control fixo para os objetos enviados.string
inline ou attachment fixo para os objetos enviados.string
Timestamp ISO 8601 para a exclusão dos objetos enviados.
object
Metadados fixos para os objetos enviados. Enterprise-12 ou superior.
boolean
Permite que os uploads feitos com este token substituam um arquivo existente. Padrão
false: sem ele, o token nunca sobrescreve um arquivo que já existe.number
Segundos que o token fica válido, de 60 a 3600. Padrão
900.number
Quantos uploads o token permite, de 1 a 100. Padrão
1.string
O ID do workspace, quando o blob pertence a um workspace. A chamada atua sobre o blob do proprietário do workspace e exige a permissão
blob:read do workspace (blob:manage nas rotas que alteram dados). Deixe de fora para atuar sobre o seu próprio blob.Exemplo de requisição
curl -X POST "https://blob.vertracloud.app/v1/upload-tokens" \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prefix":"avatars/","max_size":5000000,"allowed_extensions":["png","jpg","webp"],"expires_in":900}'
Resposta
object
{
"response": {
"token": "vcup_9f2c7d1e4b8a6035c2f1d9e7a4b3c8d2",
"expires_at": "2026-10-14T12:15:00.000Z",
"max_uses": 1
}
}
Respostas de erro
string
O código de erro que indica o motivo da falha. Valores possíveis:
AUTH_TOKEN_MISSING(401): o cabeçalhoAuthorizationnão foi enviado.API_KEY_INVALID(401): a chave de API não existe, foi revogada ou o segredo não confere.API_KEY_SCOPE_DENIED(403): a chave não tem o escopo que esta rota exige (blob:readoublob:write);details.requiredinforma qual.WORKSPACE_PERMISSION_DENIED(403): somente comworkspace_id: você não é membro, ou o seu papel não tem a permissão de blob.WORKSPACE_NOT_FOUND(404): somente comworkspace_id: não existe workspace com esse ID, ou você não é membro.BLOB_NAMESPACE_SUSPENDED(403): o armazenamento de blob da conta está suspenso, ou o plano expirou. Uploads e outras gravações são recusados desde o início do período de carência de 72 horas.VALIDATION_ERROR(400): um parâmetro ou campo do corpo falhou na validação.details.pathinforma o campo.PLAN_RESTRICTED_FEATURE(403):metadatafoi enviado em um plano abaixo do Enterprise-12.RATE_LIMIT_EXCEEDED(429): mais de 60 tokens criados em um minuto;details.retry_afterinforma quantos segundos esperar.
{
"code": "AUTH_TOKEN_MISSING"
}
{
"code": "API_KEY_SCOPE_DENIED"
}
{
"code": "WORKSPACE_NOT_FOUND"
}
{
"code": "VALIDATION_ERROR"
}
Última modificação em 28 de outubro de 2026