> ## 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.
# Listar arquivos do Blob
> Os arquivos do Blob da conta, com pastas pelo nome, busca, páginas e o uso da cota.
Devolve os arquivos já confirmados, na ordem do nome, e o uso da cota do plano (`usage`). Para navegar por pastas, mande `delimiter=/` e o `prefix` da pasta (`img/`): o que fica dentro de uma subpasta vem junto em `folders`. Funciona com a chave de leitura, a de leitura e escrita e a **Só Blob**. Guia completo em [Blob](/hosting/blob).
Com mais itens que o `limit`, a resposta traz `nextCursor`: mande de volta em `cursor` para a próxima página, até ele vir `null`.
## Erros comuns
| Código | HTTP | O que fazer |
| ---------------------------------------------------------- | ---- | --------------------------------------------------------------------------- |
| [`invalid_request`](/errors#param-invalid-request) | 400 | Confira os parâmetros: `delimiter` só aceita `/` e `limit` vai de 1 a 1000. |
| [`invalid_api_key`](/errors#param-invalid-api-key) | 401 | Confira o cabeçalho `Authorization: Bearer cube_…` ou crie outra chave. |
| [`rate_limit_exceeded`](/errors#param-rate-limit-exceeded) | 429 | Espere o `Retry-After`: a conta passou do limite do plano. |
Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).
## OpenAPI
````yaml GET /blob/objects
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: Avisos
- name: Conta
paths:
/blob/objects:
get:
tags:
- Blob
summary: Listar arquivos do Blob
description: >-
Os arquivos do Blob da conta, na ordem do nome, e o uso da cota do
plano. `prefix` filtra pelo começo do nome (uma pasta é o começo com
`/`: `img/`); com `delimiter=/`, o que fica dentro de uma subpasta vem
junto em `folders`. `search` procura o texto no nome inteiro, sem
diferenciar maiúsculas (e ignora o `delimiter`). Com mais itens que o
`limit`, `nextCursor` vem preenchido: mande de volta em `cursor` para a
próxima página. Só aparece o que já foi confirmado (`complete`). Guia em
[Blob](/hosting/blob).
operationId: listBlobObjects
parameters:
- name: prefix
in: query
description: 'O começo do nome (ex.: `img/`).'
schema:
type: string
maxLength: 1024
- name: delimiter
in: query
description: 'Só `/`: junta as subpastas em `folders`.'
schema:
type: string
enum:
- /
- name: search
in: query
description: Texto que o nome precisa conter.
schema:
type: string
maxLength: 200
- name: cursor
in: query
description: O `nextCursor` da página anterior.
schema:
type: string
- name: limit
in: query
description: Itens por página, de 1 a 1000.
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
responses:
'200':
description: Os arquivos, as subpastas e o uso da cota.
content:
application/json:
schema:
$ref: '#/components/schemas/BlobList'
example:
objects:
- id: 01JA3F7K2M9P4R6T8V0X1Z3B5D
path: img/logo.png
sizeBytes: 23456
contentType: image/png
status: ready
createdAt: '2026-09-28T13:10:02.000Z'
folders:
- prefix: img/icones/
objectCount: 3
sizeBytes: 12288
nextCursor: null
usage:
usedBytes: 48213991
quotaBytes: 5368709120
objectCount: 7
maxObjectBytes: 4294967296
isAvailable: true
'400':
description: Um parâmetro saiu do formato.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_request:
summary: invalid_request
value:
status: error
code: invalid_request
message: >-
Use prefix, delimiter "/", search, cursor e limit de 1 a
1000.
'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.
'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
"https://app.cubehosting.com.br/api/blob/objects?delimiter=/&prefix=img/"
\
-H "Authorization: Bearer $CUBE_API_KEY"
- 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?delimiter=/&prefix=img/`, { headers });
const { objects, folders, usage } = await res.json();
for (const f of folders) console.log(f.prefix, f.objectCount);
for (const o of objects) console.log(o.path, o.sizeBytes);
console.log(`${usage.usedBytes} de ${usage.quotaBytes} bytes`);
- 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.get(
f"{API}/blob/objects",
headers=headers,
params={"delimiter": "/", "prefix": "img/"},
timeout=30,
)
r.raise_for_status()
for o in r.json()["objects"]:
print(o["path"], o["sizeBytes"])
components:
schemas:
BlobList:
type: object
required:
- objects
- folders
- nextCursor
- usage
properties:
objects:
type: array
items:
$ref: '#/components/schemas/BlobObject'
folders:
type: array
description: 'Com `delimiter=/`: as subpastas da pasta pedida.'
items:
type: object
required:
- prefix
- objectCount
- sizeBytes
properties:
prefix:
type: string
description: O prefixo da pasta, com `/` no fim (`img/icones/`).
objectCount:
type: integer
sizeBytes:
type: integer
nextCursor:
type:
- string
- 'null'
description: Para a próxima página, em `cursor`; `null` na última.
usage:
$ref: '#/components/schemas/BlobUsage'
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
BlobObject:
type: object
required:
- id
- path
- sizeBytes
- contentType
- status
- 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.'
createdAt:
type: string
format: date-time
description: Quando o envio foi confirmado.
BlobUsage:
type: object
required:
- usedBytes
- quotaBytes
- objectCount
- maxObjectBytes
- isAvailable
properties:
usedBytes:
type: integer
description: O que já está guardado (envios confirmados).
quotaBytes:
type: integer
description: >-
A cota do plano (1 GB = 1024³ bytes): Block 5 GB, Stack 10, Tower
25, Fortress 50, Monolith 100; 0 no Free.
objectCount:
type: integer
maxObjectBytes:
type: integer
description: O maior arquivo aceito (4 GB).
isAvailable:
type: boolean
description: >-
`false` quando o armazenamento não está disponível: a lista
funciona, enviar e baixar não.
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_…`.
````