> ## 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.
# Inspeccionar mensajes de una cola
> Lee sin conceder mensajes: no incrementa `receive_count`, no oculta mensajes a los consumidores y no devuelve recibos. Requiere `queue:PeekMessages` para permitir la inspección sin autorizar el consumo de la cola.
Requiere la acción IAM **`queue:PeekMessages`**. Consulte [QUEUE permisos](/es/queue/permissions) para la lista completa, el alcance de cada acción y un ejemplo de política.
## OpenAPI
````yaml /es/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: >-
Colas duraderas con entrega al menos una vez. Recibir un mensaje concede una
reserva temporal: `ReceiveMessage` lo oculta durante el timeout de
visibilidad y devuelve un recibo. Elimine el mensaje con ese recibo antes de
que venza para evitar la reentrega. Cada recepción genera un recibo nuevo;
los recibos vencidos devuelven `QUEUE_RECEIPT_HANDLE_EXPIRED`.
Las colas estándar tienen orden de mejor esfuerzo. Las colas FIFO terminan
en `.fifo`, mantienen el orden por `message_group_id` y deduplican
`message_deduplication_id` durante cinco minutos. Los grupos distintos
pueden procesarse en paralelo. El tipo es inmutable. `wait_time_seconds`
permite esperar hasta 20 segundos por mensajes.
Los cuerpos se cifran en reposo. `kms_key` acepta UUID, nombre en la cuenta
o CRN completo de una clave simétrica habilitada en la misma cuenta y
región. Las referencias inválidas devuelven 400; las claves inexistentes
devuelven 404. Las lecturas de metadatos conservan ID y CRN de una
vinculación eliminada. La clave de datos permanece en caché durante
`kms_data_key_reuse_period_seconds`; los envíos y recepciones pueden
continuar durante esa ventana tras desactivar la clave. Reducirla aumenta
las llamadas a 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: Punto final de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de región
security:
- BearerAuth: []
tags:
- name: Queues
description: Ciclo de vida y atributos de las colas
- name: Messages
description: Envío, recepción y confirmación de mensajes
paths:
/v1/queues/{queue_id}/messages:
parameters:
- $ref: '#/components/parameters/QueueId'
get:
tags:
- Messages
summary: Inspeccionar mensajes de una cola
description: >-
Lee sin conceder mensajes: no incrementa `receive_count`, no oculta
mensajes a los consumidores y no devuelve recibos. Requiere
`queue:PeekMessages` para permitir la inspección sin autorizar el
consumo de la cola.
operationId: peekMessages
parameters:
- name: crn
in: query
description: >-
CRN exacto del mensaje en esta cola. Los CRN de otro ámbito
devuelven una página vacía antes de paginar; los CRN malformados
devuelven 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 mensajes.
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 la inspección: `available` puede recibirse ahora; `in_flight`
está concedido; `delayed` aún no se ha entregado y su retraso no ha
terminado.
schema:
type: string
enum:
- available
- in_flight
- delayed
example: available
Marker:
name: marker
in: query
description: ID del último elemento de la 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 artículos a devolver. Un valor mayor se sujeta al
máximo en lugar de ser rechazado, por lo que page until `meta.has_more`
es 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: >-
Mensaje devuelto por la inspección. No incluye recibo, ya que la
inspección no concede mensajes.
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 cuando no se pudo descifrar el cuerpo; los demás campos
siguen disponibles.
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: >-
Tamaño en texto sin cifrar, incluido en max_message_bytes de la
cola.
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: Cuándo la retención descarta este mensaje.
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 artículos
example: 150
limit:
type: integer
description: Número de artículos por página
example: 20
marker:
type: string
description: >-
Cursor opaco para la página siguiente. Pasalo de vuelta como el
parámetro de consulta `marker`; trátalo como un token, no como un
valor para analizar.
example: 550e8400-e29b-41d4-a716-446655440000
has_more:
type: boolean
description: Si hay más artículos
example: true
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de error que identifica el tipo de error
example: INVALID_INPUT
message:
type: string
description: Mensaje de error legible por el ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores no sensibles opcionales para la interpolación de errores
localizados, codificados por código de error. Nunca presente por
errores del servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuración
example: 550e8400-e29b-41d4-a716-446655440000
MessageAttributes:
type: object
description: >-
Atributos tipados enviados con el cuerpo. Hasta 20, con valores de hasta
1024 caracteres. Los valores `Binary` usan base64 estándar. La cola
valida el tipo declarado sin convertir 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: Se requiere autenticación o el token no es vá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: Permisos 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: No se encontró el recurso
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: >+
Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
`. Esta es la forma recomendada de autenticación.
Obtén el token intercambiando el par de claves de acceso de una cuenta
de servicio en `POST /v1/oauth/token` con
`grant_type=client_credentials`. Es el flujo estándar de credenciales de
cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar
el token por ti.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Los tokens duran una hora por defecto. El mismo par de claves de acceso
también sirve como credencial AWS SigV4 para el endpoint de objetos
compatible con S3, que solo acepta ese método de autenticación.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.