Name
List files
Your organization’s files, newest first, paginated by cursor.
HTTP method and path
/https:
What happens when you run it
- Read only: it does not change your organization’s data.
- The call is not charged.
What it does
Lists the stored files and the ones being deleted, newest first. It paginates by cursor: if next is not null, pass it as cursor for the next page with the same filters. A cursor that was altered, belongs to another organization, uses other filters or is more than 24 hours old answers 400 INVALID_CURSOR: go back to the first page.
Availability and prerequisites
- Published and available in the production API v6.
- Every path starts at
https:./ / developers. hablame. co - You need a Hablame API key to call it.
Authentication and permissions
- Send your API key in the
Authorizationheader with the Bearer scheme.
Who can call it: An API key with the storage service enabled.
Limits and operational notes
Usage limit: 10 requests per second.
- The six Storage queries (summary, usage, list, detail, retention and pricing) share this per-organization quota: it is not a per-endpoint quota.
Path parameters
This endpoint has no path parameters.
Query parameters
| Name | Type | Description and rules |
|---|---|---|
serviceOptional | string | Code of the service that stored the files (the Example: |
scopeOptional | string | Code of the file type within the service (the Example: |
fromOptional | string | Only those stored from this instant (ISO-8601; without a zone, Colombia time). |
toOptional | string | Only those stored before this instant. |
limitOptional | integer | Files per page. Default value: |
cursorOptional | string | The |
HTTP headers
| Name | Type | Description and rules |
|---|---|---|
AuthorizationRequired | string | Your API key with the Bearer scheme. Example: |
Request body
This endpoint takes no request body.
Successful responses
200
A page of files.
{
"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
}
}The example values are illustrative.
Response fields
| Name | Type | Description and rules |
|---|---|---|
successAlways present | boolean | |
dataAlways present | object | |
data.Always present | array<object> | |
data.Always present | string | File identifier. Example: |
data.Always present | string | Original name, if the service stored it. May come as |
data.Always present | string | Service that stored it. |
data.Always present | string | File type within the service. |
data.Always present | integer | Size in bytes. |
data.Always present | string | MIME type. |
data.Always present | string | When it was stored (ISO-8601, Colombia time, with milliseconds). May come as Format: |
data.Always present | string | When it is deleted under the current retention time, or May come as Format: |
data.Always present | string |
Allowed values: |
data.Always present | boolean | Whether its file type allows deleting it from the portal before it expires. |
data.Always present | string | Cursor of the next page, or May come as |
metaAlways present | object | Response metadata. |
meta.Always present | string | Unique request identifier (16 hexadecimal characters). It matches the Example: |
meta.Always present | string | IP the API saw your request come from. Useful if your API key only accepts certain networks. Example: |
meta.Always present | string | Date and time the response was built (ISO 8601 with offset). Format: |
meta.Always present | number | Time (ms) the server took to process the request. Example: |
Error codes
Every error response has the same shape: success set to false and an error object whose code says what happened. They are grouped here by kind, with the codes this endpoint can return.
Shape of an error response
| Name | Type | Description and rules |
|---|---|---|
successAlways present | boolean | Fixed value: |
metaAlways present | object | Response metadata. |
meta.Always present | string | Unique request identifier (16 hexadecimal characters). It matches the Example: |
meta.Always present | string | IP the API saw your request come from. Useful if your API key only accepts certain networks. Example: |
meta.Always present | string | Date and time the response was built (ISO 8601 with offset). Format: |
meta.Always present | number | Time (ms) the server took to process the request. Example: |
errorAlways present | object | |
error.Always present | string | Stable UPPER_SNAKE_CASE identifier. Clients branch on this value. Example: |
error. | integer | Legacy v5 numeric code, only when a bridge exists. Omitted for codes born in v6. Example: |
error.Always present | string | URL to the error documentation. Format: |
error.Always present | string | Human readable text, in English. It is for the developer log, not the end user: do not parse it. |
error.Always present | array<object> | Structured context (validation issues, affected resource). Empty array when there is no extra context. |
Validation
- 400A parameter is not valid.
A query parameter is not valid.
The page cursor no longer works.
Authentication
- 401Invalid or missing credentials.
No Bearer token was sent, and every call requires one.
Message the API returns: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
The API key is not recognized: wrong format, revoked or expired.
Message the API returns: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.
Permissions
- 403The API key does not have the Storage service (
storage), cannot be used from the request network, or the organization is not active.
The key is not allowed to use the service behind this endpoint.
Message the API returns: This API key is not authorized to use the requested service.
The key only works from certain networks and your IP is not one of them.
Message the API returns: 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.
Your organization is suspended or closed.
Message the API returns: The organization associated with this API key is not active. Please contact support.
Usage limits
- 429Request limit exceeded.
You exceeded your organization quota for this endpoint.
Message the API returns: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.
Resource not found
This endpoint does not declare responses of this kind.
Internal errors and availability
- 503Storage is not responding right now. Retry after
Retry-After.
Generic 503: a service we depend on is not responding.
Other responses
This endpoint does not declare responses of this kind.
Special considerations
Files require a key with Storage
Files may be call recordings, audio or documents of your organization. Any API key with the Storage service (storage) can see them, and only the owner of your organization creates keys. Without the service, the key gets 403 AUTH_SERVICE_NOT_ALLOWED here and on every other Storage endpoint.
Read-only; storage never pauses
Your files are stored continuously and never pause, even without balance. To query them over the API, the API key needs the Storage service (storage): with it, the key sees everything (summary, usage, files, downloads, retention and pricing), and without it each of these endpoints answers 403 AUTH_SERVICE_NOT_ALLOWED. The API is read-only: the retention time is changed from the customer portal (Storage → Retention) and a file is deleted there or when it expires. Any method other than GET answers 405.