> ## 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.
# Salvar as regras de pasta
> Troque a lista inteira de regras de pasta do Blob.
Mande a lista inteira: a que não vier sai (lista vazia apaga todas).
`deleteAfterDays` apaga os arquivos da pasta com mais desses dias, **inclusive os que já estão lá**, a partir de 24 horas depois de salvar (`deletionStartsAt`). Arquivo apagado não volta. Salvar de novo com o mesmo número mantém a data; trocar recomeça as 24 horas. Tirar ou renomear a regra de uma subpasta também recomeça as 24 horas da regra de cima que apaga, porque os arquivos dela passam para essa regra.
`cacheMaxAgeSeconds` deixa o navegador guardar o link público pelo tempo escolhido: quem já abriu fica com a cópia até vencer, mesmo se o arquivo ficar privado ou for apagado. Sem ele, o navegador confere o link a cada uso.
## Erros comuns
| Código | HTTP | O que fazer |
| - | - | - |
| [`invalid_folder_rule`](/errors#param-invalid-folder-rule) | 400 | Corrija a pasta ou a extensão que a `message` diz, ou junte as duas regras da mesma pasta. |
| [`folder_rule_limit_reached`](/errors#param-folder-rule-limit-reached) | 409 | Remova regras ou mude para um plano maior: o `limit` diz quantas o plano tem. |
| [`blob_not_in_plan`](/errors#param-blob-not-in-plan) | 403 | Assine um plano pago: o Free não tem Blob. |
| [`insufficient_permission`](/errors#param-insufficient-permission) | 403 | Use uma chave de leitura e escrita (a Só Blob não mexe nas regras). |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml PUT /blob/folder-rules
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, veja a análise das visitas dos
sites, 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: Análise
- 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/folder-rules:
put:
tags:
- Blob
summary: Salvar as regras de pasta
description: >-
Troca a lista inteira de regras da conta (lista vazia apaga todas).
Visibilidade, expiração, cache, tamanho e extensões valem nos **envios**
para a pasta; a expiração e o cache ficam gravados em cada arquivo.
**Apagar com mais de N dias** (`deleteAfterDays`) vale também para os
arquivos que já estão na pasta e só começa **24 horas depois de salvar**
(`deletionStartsAt`): salvar de novo com o mesmo N mantém a data, e
trocar o N recomeça as 24 horas. Tirar ou renomear a regra de uma
subpasta também recomeça as 24 horas da regra de cima que apaga, porque
os arquivos dela passam para essa regra. Arquivo apagado não volta. A
pasta vem sem `/` nas pontas e as extensões em minúsculas, sem o ponto.
operationId: saveBlobFolderRules
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- rules
properties:
rules:
type: array
maxItems: 50
items:
$ref: '#/components/schemas/BlobFolderRuleInput'
example:
rules:
- folder: backups/diarios
allowedExtensions:
- zip
deleteAfterDays: 7
responses:
'200':
description: As regras salvas e o limite do plano.
content:
application/json:
schema:
$ref: '#/components/schemas/BlobFolderRules'
example:
rules:
- folder: backups/diarios
defaultVisibility: private
defaultExpirationDays: 30
cacheMaxAgeSeconds: null
maxFileSizeBytes: 52428800
allowedExtensions:
- zip
- tar.gz
deleteAfterDays: 7
deletionStartsAt: '2026-10-01T13:10:02.000Z'
updatedAt: '2026-09-30T13:10:02.000Z'
limit: 5
'400':
description: >-
O corpo saiu do formato, ou uma regra tem a pasta ou uma extensão
torta, ou há duas para a mesma pasta. Nada mudou.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: invalid_request
value:
status: error
code: invalid_request
message: >-
Mande rules: a lista de regras, cada uma com folder e, se
quiser, defaultVisibility, defaultExpirationDays,
cacheMaxAgeSeconds, maxFileSizeBytes, allowedExtensions e
deleteAfterDays.
invalid_folder_rule:
summary: invalid_folder_rule
value:
status: error
code: invalid_folder_rule
message: >-
Duas regras para a pasta backups/diarios. Junte as duas
numa só e salve de novo.
'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 ou Só Blob, ou o plano não tem Blob (Free).
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, baixar e restaurar
backups, baixar e voltar versões dos envios, criar, ligar,
desligar, fazer backup e ver a senha dos bancos de dados
ou enviar e apagar arquivos do Blob, crie uma chave de
leitura e escrita no painel.
blob_not_in_plan:
summary: blob_not_in_plan
value:
status: error
code: blob_not_in_plan
message: >-
O Blob é dos planos pagos. Assine um plano em Plano e
cobrança para enviar arquivos.
'409':
description: Mais regras que o plano tem. Nada mudou.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
folder_rule_limit_reached:
summary: folder_rule_limit_reached
value:
status: error
code: folder_rule_limit_reached
message: >-
O plano Block tem até 5 regras de pasta. Junte ou remova 1
e salve de novo, ou mude para um plano maior.
limit: 5
'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.
x-codeSamples:
- lang: bash
label: curl
source: |-
curl -X PUT https://app.cubehosting.com.br/api/blob/folder-rules \
-H "Authorization: Bearer $CUBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rules": [{"folder": "backups/diarios", "allowedExtensions": ["zip"], "deleteAfterDays": 7}]}'
- 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/folder-rules`, {
method: 'PUT',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ rules: [{ folder: 'backups/diarios', allowedExtensions: ['zip'], deleteAfterDays: 7 }] }),
});
const { rules } = await res.json();
console.log(rules[0].deletionStartsAt);
- 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.put(
f"{API}/blob/folder-rules",
headers=headers,
json={"rules": [{"folder": "backups/diarios", "allowedExtensions": ["zip"], "deleteAfterDays": 7}]},
timeout=30,
)
r.raise_for_status()
print(r.json()["rules"])
components:
schemas:
BlobFolderRuleInput:
type: object
required:
- folder
properties:
folder:
type: string
description: >-
A pasta (`backups/diarios`), sem `/` nas pontas; a regra vale também
para as subpastas.
defaultVisibility:
type:
- string
- 'null'
description: >-
`public` ou `private`: a visibilidade dos envios que não dizem a
deles.
defaultExpirationDays:
type:
- integer
- 'null'
description: >-
De 1 a 3650: em quantos dias vencem os envios que não dizem o
`expiresAt`.
cacheMaxAgeSeconds:
type:
- integer
- 'null'
description: >-
De 60 a 31536000: o cache do link público dos arquivos enviados. Com
ele, quem já abriu fica com a cópia até vencer, mesmo se o arquivo
ficar privado ou for apagado.
maxFileSizeBytes:
type:
- integer
- 'null'
description: O maior arquivo aceito na pasta (até 4 GB).
allowedExtensions:
type: array
maxItems: 50
items:
type: string
description: As extensões aceitas (`png`, `tar.gz`); vazia aceita qualquer uma.
deleteAfterDays:
type:
- integer
- 'null'
description: >-
De 1 a 3650: apaga os arquivos da pasta com mais desses dias,
inclusive os que já estão lá, a partir de 24 horas depois de salvar.
BlobFolderRules:
type: object
required:
- rules
- limit
properties:
rules:
type: array
items:
$ref: '#/components/schemas/BlobFolderRule'
limit:
type: integer
description: >-
Quantas regras o plano tem: 1 por GB da cota, até 50 (Block 5, Stack
10, Tower 25); 0 no Free.
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
BlobFolderRule:
allOf:
- $ref: '#/components/schemas/BlobFolderRuleInput'
- type: object
required:
- deletionStartsAt
- updatedAt
properties:
deletionStartsAt:
type:
- string
- 'null'
description: >-
Quando o `deleteAfterDays` começa a apagar (24 horas depois de
salvo); `null` sem ele.
updatedAt:
type: string
format: date-time
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_…`.
````