> ## 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.
# Inspecionar mensagens de uma fila
> Lê sem conceder mensagens: não incrementa `receive_count`, não oculta mensagens dos consumidores e não retorna recibos. Requer `queue:PeekMessages` para permitir inspeção sem autorizar o consumo da fila.
Exige a ação IAM **`queue:PeekMessages`**. Veja [QUEUE permissões](/pt/queue/permissions) para a lista completa, o escopo de cada ação e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/queue.yaml get /v1/queues/{queue_id}/messages
openapi: 3.0.3
info:
title: API Basaltic Queue
version: 1.0.0
description: >-
Filas duráveis com entrega ao menos uma vez. Receber uma mensagem concede
uma reserva temporária: `ReceiveMessage` a oculta pelo timeout de
visibilidade e retorna um recibo. Exclua a mensagem com esse recibo antes do
vencimento para evitar a reentrega. Cada recebimento gera um recibo novo;
recibos vencidos retornam `QUEUE_RECEIPT_HANDLE_EXPIRED`.
Filas padrão têm ordenação de melhor esforço. Filas FIFO terminam em
`.fifo`, mantêm a ordem por `message_group_id` e deduplicam
`message_deduplication_id` por cinco minutos. Grupos diferentes podem ser
processados em paralelo. O tipo é imutável. `wait_time_seconds` permite
aguardar até 20 segundos por mensagens.
Os corpos são criptografados em repouso. `kms_key` aceita UUID, nome na
conta ou CRN completo de uma chave simétrica habilitada na mesma conta e
região. Referências inválidas retornam 400; chaves inexistentes retornam
404. Leituras de metadados preservam ID e CRN de uma vinculação excluída. A
chave de dados permanece em cache por `kms_data_key_reuse_period_seconds`;
envios e recebimentos podem continuar nessa janela após desativar a chave.
Reduzir o período aumenta as chamadas ao KMS.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://queue.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
tags:
- name: Queues
description: Ciclo de vida e atributos das filas
- name: Messages
description: Envio, recebimento e confirmação de mensagens
paths:
/v1/queues/{queue_id}/messages:
parameters:
- $ref: '#/components/parameters/QueueId'
get:
tags:
- Messages
summary: Inspecionar mensagens de uma fila
description: >-
Lê sem conceder mensagens: não incrementa `receive_count`, não oculta
mensagens dos consumidores e não retorna recibos. Requer
`queue:PeekMessages` para permitir inspeção sem autorizar o consumo da
fila.
operationId: peekMessages
parameters:
- name: crn
in: query
description: >-
CRN exato da mensagem nesta fila. CRNs de outro escopo retornam uma
página vazia antes da paginação; CRNs malformados retornam 400.
schema:
type: string
example: >-
crn:queue:sa-saopaulo-1:acme:queue/orders/message/019400aa-bbbb-7ccc-8ddd-eeeeffff0000
- $ref: '#/components/parameters/Visibility'
- $ref: '#/components/parameters/Marker'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Lista paginada de mensagens.
content:
application/json:
schema:
$ref: '#/components/schemas/PeekResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
QueueId:
name: queue_id
in: path
required: true
schema:
type: string
format: uuid
example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
Visibility:
name: visibility
in: query
description: >-
Restringe a inspeção: `available` pode ser recebida agora; `in_flight`
está concedida; `delayed` ainda não foi entregue e seu atraso não
terminou.
schema:
type: string
enum:
- available
- in_flight
- delayed
example: available
Marker:
name: marker
in: query
description: ID do último item da página anterior.
schema:
type: string
format: uuid
example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
Limit:
name: limit
in: query
description: >-
Número máximo de itens a devolver. Um valor maior é fixado ao máximo em
vez de rejeitado, então page until `meta.has_more` é false.
schema:
type: integer
default: 50
minimum: 1
maximum: 200
example: 50
schemas:
PeekResponse:
type: object
required:
- messages
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
meta:
$ref: '#/components/schemas/PaginationMeta'
Message:
type: object
description: >-
Mensagem retornada pela inspeção. Não inclui recibo, pois a inspeção não
concede mensagens.
required:
- id
- crn
- queue_id
- visibility
- receive_count
- enqueued_at
- visible_at
- expires_at
properties:
id:
type: string
format: uuid
example: 019400aa-bbbb-7ccc-8ddd-eeeeffff0000
crn:
type: string
example: >-
crn:queue:sa-saopaulo-1:acme:queue/orders/message/019400aa-bbbb-7ccc-8ddd-eeeeffff0000
queue_id:
type: string
format: uuid
example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
body:
type: string
description: >-
Ausente quando não foi possível descriptografar o corpo; os demais
campos continuam disponíveis.
example: '{"order_id":"A-1001"}'
attributes:
$ref: '#/components/schemas/MessageAttributes'
visibility:
type: string
enum:
- available
- in_flight
- delayed
example: available
receive_count:
type: integer
example: 0
body_bytes:
type: integer
description: Tamanho em texto simples, incluído em max_message_bytes da fila.
example: 24
message_group_id:
type: string
example: customer-42
enqueued_at:
type: string
format: date-time
example: '2026-01-18T11:45:00Z'
visible_at:
type: string
format: date-time
example: '2026-01-18T11:45:00Z'
expires_at:
type: string
format: date-time
description: Quando a retenção descarta esta mensagem.
example: '2026-01-22T11:45:00Z'
first_received_at:
type: string
format: date-time
nullable: true
example: '2026-01-18T11:46:10Z'
PaginationMeta:
type: object
properties:
total:
type: integer
description: Número total de itens
example: 150
limit:
type: integer
description: Número de itens por página
example: 20
marker:
type: string
description: >-
Cursor opaco para a próxima página. Passe-o de volta como o
parâmetro de consulta `marker`; trate-o como um token, não um valor
para analisar.
example: 550e8400-e29b-41d4-a716-446655440000
has_more:
type: boolean
description: Se há mais itens
example: true
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
MessageAttributes:
type: object
description: >-
Atributos tipados enviados com o corpo. Até 20, com valores de até 1024
caracteres. Valores `Binary` usam base64 padrão. A fila valida o tipo
declarado sem converter valores.
additionalProperties:
type: object
required:
- type
- value
properties:
type:
type: string
enum:
- String
- Number
- Binary
example: String
value:
type: string
example: critical
example:
severity:
type: String
value: critical
attempt:
type: Number
value: '2'
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
Forbidden:
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: Página não encontrada
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
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.