Nombre
Listar archivos
Los archivos de tu organización, del más reciente al más antiguo, paginados por cursor.
Método HTTP y ruta
/https:
Qué pasa al ejecutarlo
- Solo consulta: no cambia datos de tu organización.
- La llamada no se cobra.
Qué hace
Lista los archivos guardados y los que se están eliminando, del más reciente al más antiguo. Pagina por cursor: si next no es null, pásalo como cursor para la página siguiente con los mismos filtros. Un cursor alterado, de otra organización, con otros filtros o de hace más de 24 horas responde 400 INVALID_CURSOR: vuelve a la primera página.
Disponibilidad y requisitos previos
- Publicado y disponible en la API v6 de producción.
- Todas las rutas parten de
https:./ / developers. hablame. co - Necesitas una API key de Hablame para llamarlo.
Autenticación y permisos
- Envía tu API key en la cabecera
Authorizationcon el esquema Bearer.
Quién puede llamarlo: Una API key con el servicio storage habilitado.
Límites y consideraciones operativas
Límite de uso: 10 solicitudes por segundo.
- Las seis consultas de Almacenamiento (resumen, consumo, listado, detalle, conservación y tarifa) comparten este cupo por organización: no es un cupo por endpoint.
Parámetros de ruta
Este endpoint no tiene parámetros de ruta.
Parámetros de consulta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
serviceOpcional | string | Código del servicio que guardó los archivos (el Ejemplo: |
scopeOpcional | string | Código del tipo de archivo dentro del servicio (el Ejemplo: |
fromOpcional | string | Solo los guardados desde este instante (ISO-8601; sin zona, hora de Colombia). |
toOpcional | string | Solo los guardados antes de este instante. |
limitOpcional | integer | Archivos por página. Valor por omisión: |
cursorOpcional | string | El |
Encabezados HTTP
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
AuthorizationObligatorio | string | Tu API key con el esquema Bearer. Ejemplo: |
Cuerpo de la petición
Este endpoint no recibe cuerpo en la petición.
Respuestas satisfactorias
200
Una página de archivos.
{
"success": true,
"data": {
"objects": [
{
"id": "obj_01JABCDEFGHJKMNPQRSTVWXYZ0",
"name": "llamada-3001234567.wav",
"service": "callblasting",
"scope": "recordings",
"size": 482113,
"contentType": "audio/wav",
"storedAt": "2026-10-18T10:00:00.000-05:00",
"expiresAt": "2026-11-17T10:00:00.000-05:00",
"status": "available",
"deletable": false
}
],
"next": "c1.t3b9X0k..."
},
"meta": {
"requestId": "5d0f3a9c7b2e41a8",
"clientIp": "203.0.113.10",
"timestamp": "2026-10-19T15:30:00+00:00",
"responseTimeMs": 12.4
}
}Los valores del ejemplo son ilustrativos.
Campos de la respuesta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
successSiempre presente | boolean | |
dataSiempre presente | object | |
data.Siempre presente | array<object> | |
data.Siempre presente | string | Identificador del archivo. Ejemplo: |
data.Siempre presente | string | Nombre original, si el servicio lo guardó. Puede llegar en |
data.Siempre presente | string | Servicio que lo guardó. |
data.Siempre presente | string | Tipo de archivo dentro del servicio. |
data.Siempre presente | integer | Tamaño en bytes. |
data.Siempre presente | string | Tipo MIME. |
data.Siempre presente | string | Cuándo quedó guardado (ISO-8601, hora de Colombia, con milisegundos). Puede llegar en Formato: |
data.Siempre presente | string | Cuándo se elimina según el tiempo de conservación vigente, o Puede llegar en Formato: |
data.Siempre presente | string |
Valores permitidos: |
data.Siempre presente | boolean | Si su tipo de archivo permite eliminarlo desde el portal antes de que venza. |
data.Siempre presente | string | Cursor de la página siguiente, o Puede llegar en |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
Códigos de error
Todas las respuestas de error tienen la misma forma: success en false y un objeto error cuyo code dice qué pasó. Aquí están agrupadas por tipo, con los códigos que este endpoint puede devolver.
Forma de una respuesta de error
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
successSiempre presente | boolean | Valor fijo: |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
errorSiempre presente | object | |
error.Siempre presente | string | Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo: |
error. | integer | Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo: |
error.Siempre presente | string | URL a la documentación del error. Formato: |
error.Siempre presente | string | Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees. |
error.Siempre presente | array<object> | Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra. |
Validación
- 400Un parámetro no es válido.
Un parámetro de la consulta no es válido.
El cursor de la página ya no sirve.
Autenticación
- 401Credenciales inválidas o faltantes.
No se envió un token Bearer y cada llamada lo requiere.
Mensaje que devuelve la API: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
La clave de API no se reconoce: formato equivocado, revocada o vencida.
Mensaje que devuelve la API: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.
Permisos
- 403La API key no tiene el servicio Almacenamiento (
storage), no se puede usar desde la red de la petición, o la organización no está activa.
La clave no tiene permitido el servicio detrás de este endpoint.
Mensaje que devuelve la API: This API key is not authorized to use the requested service.
La clave solo funciona desde ciertas redes y tu IP no está entre ellas.
Mensaje que devuelve la API: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
Tu organización está suspendida o cerrada.
Mensaje que devuelve la API: The organization associated with this API key is not active. Please contact support.
Límites de uso
- 429Se excedió el límite de solicitudes.
Excediste el cupo de tu organización para este endpoint.
Mensaje que devuelve la API: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.
Recurso inexistente
Este endpoint no declara respuestas de este tipo.
Errores internos y disponibilidad
- 503Almacenamiento no responde en este momento. Reintenta tras
Retry-After.
503 genérico: un servicio del que dependemos no responde.
Otras respuestas
Este endpoint no declara respuestas de este tipo.
Consideraciones especiales
Los archivos piden una key con Almacenamiento
Los archivos pueden ser grabaciones de llamadas, audios o documentos de tu organización. Los ve cualquier API key con el servicio Almacenamiento (storage), y solo el propietario de tu organización crea las keys. Sin el servicio, la key recibe 403 AUTH_SERVICE_NOT_ALLOWED aquí y en las demás rutas de Almacenamiento.
Solo consulta; el almacenamiento nunca se pausa
Tus archivos se guardan de forma continua y nunca se pausan, aunque no tengas saldo. Para consultarlos por API, la API key necesita el servicio Almacenamiento (storage): con él ve todo (resumen, consumo, archivos, descargas, conservación y tarifa) y sin él cada una de estas rutas responde 403 AUTH_SERVICE_NOT_ALLOWED. La API es solo de consulta: el tiempo de conservación se cambia desde el portal de clientes (Almacenamiento → Conservación) y un archivo se elimina desde ahí o cuando vence. Cualquier método que no sea GET responde 405.