> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Tornar público ou privado
> Dê a um arquivo um link fixo que não vence, ou tire esse link do ar na hora.
Cada arquivo do Blob é **público** ou **privado**:
* **Público:** o arquivo ganha o `publicUrl`, como `https://cdn.cubehost.dev/q7Rf2kLm9xA1/logo.png`. O link é fixo, não vence e abre sem chave: a imagem abre no navegador (bom para o avatar de um bot, o banner de um site ou um anexo numa mensagem), e o resto baixa como anexo.
* **Privado** (o padrão pela API e pela CLI): só abre por [link temporário](/api-reference/blob/download-url), que vence.
Tornar privado derruba o link público **na hora**: quando a resposta chega, o link já responde `404`. Tornar público de novo volta **o mesmo** link. Apagar o arquivo também tira os links do ar.
Já quer o arquivo público no envio? Mande `visibility: "public"` em [Pedir o envio](/api-reference/blob/create): o `publicUrl` vem na confirmação.
## Erros comuns
| Código | HTTP | O que fazer |
| ------------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| [`not_found`](/errors#param-not-found) | 404 | Confira o `id`: arquivo de outra conta também dá 404. |
| [`invalid_request`](/errors#param-invalid-request) | 400 | Mande `visibility` com `public` ou `private`. |
| [`insufficient_permission`](/errors#param-insufficient-permission) | 403 | Use uma chave de leitura e escrita ou Só Blob. |
| [`blob_unavailable`](/errors#param-blob-unavailable) | 503 | Nada mudou: tente de novo em instantes. |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml PATCH /blob/objects/{id}
openapi: 3.1.0
info:
title: API da Cube Hosting
version: 1.0.0
description: >-
Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
inicie, pare, reinicie, leia logs e métricas, cuide das variáveis de
ambiente, faça e baixe backups, volte para uma versão anterior, crie bancos
de dados (PostgreSQL, MySQL, MongoDB e Redis), guarde arquivos privados no
Blob, use um domínio seu nos sites e veja o uso do plano. Para agentes de
IA, o servidor MCP da conta (`POST https://app.cubehosting.com.br/api/mcp`,
JSON-RPC, com a mesma chave) está em
https://docs.cubehosting.com.br/account-mcp.
contact:
name: Cube Hosting
url: https://discord.gg/pv6D9tUsDV
servers:
- url: https://app.cubehosting.com.br/api
security:
- bearerAuth: []
tags:
- name: Projetos
- name: Controle
- name: Logs e métricas
- name: Variáveis de ambiente
- name: Backups
- name: Versões dos envios
- name: Bancos de dados
- name: Blob
- name: Domínios
- name: Templates
- name: Avisos
- name: Conta
paths:
/blob/objects/{id}:
patch:
tags:
- Blob
summary: Tornar público ou privado
description: >-
Público: o arquivo ganha o `publicUrl`,
`https://cdn.cubehost.dev//`, um link fixo que **não vence** e
abre sem chave (imagem abre no navegador; o resto baixa). Privado: o
link público para **na hora**, antes da resposta, e o arquivo só sai por
[link temporário](/api-reference/blob/download-url). Tornar público de
novo volta o mesmo link. Entra na Atividade da conta.
operationId: updateBlobObject
parameters:
- $ref: '#/components/parameters/BlobObjectId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- visibility
additionalProperties: false
properties:
visibility:
type: string
enum:
- public
- private
example:
visibility: public
responses:
'200':
description: O arquivo, com a visibilidade nova.
content:
application/json:
schema:
type: object
required:
- object
properties:
object:
$ref: '#/components/schemas/BlobObject'
example:
object:
id: 01JA3F7K2M9P4R6T8V0X1Z3B5D
path: img/logo.png
sizeBytes: 23456
contentType: image/png
status: ready
visibility: public
publicUrl: https://cdn.cubehost.dev/q7Rf2kLm9xA1/logo.png
createdAt: '2026-09-28T13:10:02.000Z'
'400':
description: '`visibility` fora de `public` e `private`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: invalid_request
value:
status: error
code: invalid_request
message: 'Mande visibility: "public" ou "private".'
'401':
description: Chave ausente, inválida ou revogada.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_api_key:
summary: invalid_api_key
value:
status: error
code: invalid_api_key
message: >-
Chave de API inválida ou revogada. Confira o cabeçalho
"Authorization: Bearer " ou crie outra em Chaves de
API no painel.
'403':
description: A chave é só de leitura.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
insufficient_permission:
summary: insufficient_permission
value:
status: error
code: insufficient_permission
message: >-
Esta chave é só de leitura. Para enviar, iniciar, parar,
reiniciar, mexer nas variáveis, fazer e baixar backups,
baixar e voltar versões dos envios, criar, ligar, desligar
e ver a senha dos bancos de dados ou enviar e apagar
arquivos do Blob, crie uma chave de leitura e escrita no
painel.
'404':
description: >-
O arquivo não existe ou não é da sua conta (a mesma resposta para os
dois).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
not_found:
summary: not_found
value:
status: error
code: not_found
message: Arquivo não encontrado no Blob.
'429':
description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limit_exceeded:
summary: rate_limit_exceeded
value:
status: error
code: rate_limit_exceeded
message: >-
A sua conta passou do limite da API do plano Free: 10
pedidos por minuto. Espere 42 s e tente de novo.
too_many_attempts:
summary: too_many_attempts
value:
status: error
code: too_many_attempts
message: Muitas tentativas. Tente de novo em 15 minutos.
'503':
description: 'O armazenamento não respondeu: nada mudou. Tente de novo.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
blob_unavailable:
summary: blob_unavailable
value:
status: error
code: blob_unavailable
message: >-
O Blob não está disponível agora. Tente de novo em
instantes.
x-codeSamples:
- lang: bash
label: curl
source: >-
curl -X PATCH
https://app.cubehosting.com.br/api/blob/objects/$BLOB_ID \
-H "Authorization: Bearer $CUBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"visibility": "public"}'
- lang: javascript
label: Node.js
source: >-
const API = 'https://app.cubehosting.com.br/api';
const headers = { Authorization: `Bearer
${process.env.CUBE_API_KEY}` };
const res = await
fetch(`${API}/blob/objects/${process.env.BLOB_ID}`, {
method: 'PATCH',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ visibility: 'public' }),
});
const { object } = await res.json();
console.log(object.publicUrl);
- lang: python
label: Python
source: >-
import os
import requests
API = "https://app.cubehosting.com.br/api"
headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}
r = requests.patch(f"{API}/blob/objects/{os.environ['BLOB_ID']}",
headers=headers, json={"visibility": "public"}, timeout=30)
r.raise_for_status()
print(r.json()["object"]["publicUrl"])
components:
parameters:
BlobObjectId:
name: id
in: path
required: true
description: >-
O ID do arquivo do Blob (26 caracteres), de [Listar arquivos do
Blob](/api-reference/blob/list).
schema:
type: string
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
example: 01JA3F7K2M9P4R6T8V0X1Z3B5D
schemas:
BlobObject:
type: object
required:
- id
- path
- sizeBytes
- contentType
- status
- visibility
- publicUrl
- createdAt
properties:
id:
type: string
description: ID do arquivo (26 caracteres).
path:
type: string
description: O nome, com pastas por `/` (`img/logo.png`).
sizeBytes:
type: integer
contentType:
type: string
description: O tipo mandado no envio (`application/octet-stream` sem ele).
status:
type: string
enum:
- pending
- ready
description: '`pending` até a confirmação do envio.'
visibility:
type: string
enum:
- public
- private
description: >-
`public`: abre pelo `publicUrl`, sem vencer. `private` (o padrão):
só por link temporário.
publicUrl:
type:
- string
- 'null'
description: >-
O link fixo (`https://cdn.cubehost.dev//`) do arquivo
pronto e público; `null` no privado e no envio em andamento.
createdAt:
type: string
format: date-time
description: Quando o envio foi confirmado.
Error:
type: object
required:
- status
- code
- message
properties:
status:
type: string
const: error
code:
type: string
description: Código fixo em inglês. Veja [Códigos de erro](/errors).
message:
type: string
description: Texto em português para mostrar a uma pessoa.
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
Mande como `Authorization: Bearer cube_…`.
````