> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar bucket
> Provisione um novo intervalo. O nome deve ser exclusivo dentro da região (regra S3); 3-63 caracteres minúsculos, dígitos e hífens; sem hífen inicial/final.
Requer a ação do IAM **`storage:CreateBucket`**. Consulte [permissões de armazenamento](/pt/storage/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/storage.yaml post /v1/buckets
openapi: 3.0.3
info:
title: API de armazenamento Basaltic
version: 1.0.0
description: >
As referências de armazenamento aceitam UUIDs, CRNs ou nomes de escopo em um
campo. Os nomes de snapshot requerem um volume fixo; source_snapshot aceita
somente UUID ou CRN aninhado. Bloqueie volumes com seus snapshots e
políticas de snapshot, além de gerenciamento de bucket para armazenamento de
objetos. O próprio protocolo de fio S3 é servido separadamente em
`objects.{region}.basaltic.cloud`.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://storage.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
paths:
/v1/buckets:
post:
tags:
- Buckets
summary: Criar bucket
description: >
Provisione um novo intervalo. O nome deve ser exclusivo dentro da região
(regra S3); 3-63 caracteres minúsculos, dígitos e hífens; sem hífen
inicial/final.
operationId: createBucket
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBucketRequest'
responses:
'201':
description: O bucket foi criado.
content:
application/json:
schema:
$ref: '#/components/schemas/BucketResponse'
'400':
description: Corpo de solicitação ou nome de intervalo inválido.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: O chamador não tem a permissão IAM necessária.
'409':
description: >-
O nome do intervalo já está ocupado ou a cota do intervalo da conta
está esgotada.
'422':
$ref: '#/components/responses/UnprocessableEntity'
security:
- BearerAuth: []
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
Chave opcional gerada pelo cliente que torna uma criação segura para
reprodução. A reintentar uma solicitação com a mesma chave retorna o
resultado original literalmente em vez de criar um recurso duplicado. A
reutilização de uma chave com um corpo de solicitação diferente é
rejeitada (422); uma solicitação cuja chave ainda está sendo processada
retorna 409. Os registros são honrados por 24 horas. Use um UUID ou
token exclusivo semelhante.
required: false
schema:
type: string
maxLength: 255
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
CreateBucketRequest:
type: object
required:
- name
properties:
name:
description: >-
Os nomes de recursos não devem começar com o prefixo literal crn: ou
ser UUIDs (formas canônicas, compactas, entre colchetes ou
urn:uuid:, em qualquer caso).
type: string
minLength: 3
maxLength: 63
pattern: ^[a-z0-9][a-z0-9\-]{1,61}[a-z0-9]$
example: my-app-assets
object_lock_enabled:
type: boolean
description: >
Quando true, ativa o bloqueio de objetos do S3 no intervalo no
momento da criação e ativa o controle de versão. O Bloqueio de
objeto não pode ser ativado posteriormente.
example: false
BucketResponse:
type: object
properties:
bucket:
$ref: '#/components/schemas/Bucket'
Bucket:
type: object
required:
- id
- name
- crn
- acl
- versioning
- deletion_protection
- recovery_window_days
- deleted_at
- created_at
properties:
id:
type: string
format: uuid
readOnly: true
example: c4e2a1f8-6b3d-4e9a-8c7f-2d1e0a3b4c5d
name:
description: >-
Os nomes de recursos não devem começar com o prefixo literal crn: ou
ser UUIDs (formas canônicas, compactas, entre colchetes ou
urn:uuid:, em qualquer caso).
type: string
example: my-app-assets
crn:
type: string
example: crn:storage:sa-saopaulo-1:platform:bucket/my-app-assets
readOnly: true
acl:
type: string
example: private
versioning:
type: string
description: >-
Estado de versionamento. `suspended` significa que o versionamento
estava ligado e foi desligado — as versões existentes são mantidas,
novas gravações param de criá-las — o que é distinto de `disabled`,
um bucket que nunca o teve habilitado. O endpoint compatível com S3
escreve os mesmos estados `Enabled` / `Suspended` em seu XML e
relata `disabled` omitindo o elemento.
enum:
- disabled
- enabled
- suspended
example: disabled
deletion_protection:
type: boolean
description: >-
Quando true, DeleteBucket agenda a exclusão em vez de remover o
bucket imediatamente. O padrão false deliberadamente preserva a
exclusão imediata do S3.
default: false
example: false
recovery_window_days:
type: integer
description: >-
Janela de recuperação configurada em dias inteiros (padrão 7). Novas
gravações exigem 1-30; buckets históricos desabilitados podem reter
valores legados fora do intervalo.
example: 7
deleted_at:
type: string
format: date-time
nullable: true
readOnly: true
description: >-
Quando a exclusão foi solicitada; nulo quando não pendente ou para
janelas históricas.
scheduled_purge_at:
type: string
format: date-time
readOnly: true
description: >-
Prazo de limpeza, presente enquanto a exclusão está pendente.
Restaure antes desse tempo para cancelar.
example: '2026-01-22T09:30:00Z'
created_at:
type: string
format: date-time
readOnly: true
example: '2026-01-15T09:30:00Z'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de erro identificando o tipo de erro
example: INVALID_INPUT
message:
type: string
description: Mensagem de erro legível pelo ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores não sensíveis opcionais para interpolação de erros
localizados, codificados por código de erro. Nunca presente para
erros de servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuração
example: 550e8400-e29b-41d4-a716-446655440000
responses:
Unauthorized:
description: Autenticação necessária ou token inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
UnprocessableEntity:
description: >
A solicitação está bem formada, mas não pode ser processada conforme
enviada. Nas operações que aceitam `Idempotency-Key` este é o caso de
reutilização de chave: a chave foi vista pela primeira vez com uma carga
de solicitação diferente, então reproduzir o resultado armazenado
responderia a uma pergunta que o chamador não fez.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: IDEMPOTENCY_KEY_REUSED
message: >-
This Idempotency-Key was already used with a different request
payload
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `.
Esta é a forma recomendada de autenticação.
Obtenha o token trocando o par de chaves de acesso de uma conta de
serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
com OAuth podem obter e renovar o token para você.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
também serve como credencial AWS SigV4 para o endpoint de objetos
compatível com S3, que aceita somente esse método de autenticação.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.