{ "openapi": "3.1.0", "info": { "title": "Hablame API", "version": "6.0.0", "summary": "Operator REST API: number lookup, URL shortener, text to speech, calls, account and catalogs.", "description": "The Hablame API v6 authenticates with Bearer tokens, returns every response inside the uniform `{ success, data | error, meta }` envelope and reports usage limits through the standard `RateLimit-*` headers.\n\nThis specification is generated from the same source as the documentation published on the portal.\n\nEvery operation declares its limit and scope twice: `x-limit`/`x-access` are the canonical names, and `x-tps`/`x-scope` keep the shape they had in the previous specification so tooling that already read them does not break.", "contact": { "name": "Hablame developer support", "email": "developers@hablame.co", "url": "https://developers.hablame.co/docs" } }, "servers": [ { "url": "https://developers.hablame.co", "description": "Production" }, { "url": "https://qa-developers.hablame.co", "description": "QA / staging" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Utilities", "description": "Diagnostic endpoints, available to any API key. Use them to verify your credentials are wired correctly." }, { "name": "Tools", "description": "General-purpose catalogs you can consume from your app. Available to any API key." }, { "name": "Number Insight", "description": "Resolves a phone number: country, line type, current carrier (porting-aware in Colombia) and area. One by one or in batches." }, { "name": "URL Shortener", "description": "Create and manage short links on your domains, and read their click analytics." }, { "name": "Text-to-Speech", "description": "Turn text into audio with natural voices, automatically reuse an identical audio already generated, and check the state of each request." }, { "name": "Call Blasting", "description": "Outbound voice calls with pre-recorded audio or text-to-speech, with configurable retries and per-attempt status." }, { "name": "Account", "description": "Billing summary for the organization: balance or credit, spending limits and movements. Sensitive financial data." }, { "name": "Organization", "description": "Organization profile, cost centers and users. Includes personal data." }, { "name": "Platform", "description": "Operational status of the services and a catalog of what your account has enabled." } ], "paths": { "/api/v6/utilities/ping": { "get": { "operationId": "utilities.ping", "tags": [ "Utilities" ], "summary": "Ping", "description": "Returns the caller state: it confirms the API key is valid and shows the key facts the API knows about the requester.\n\nUse it as a smoke test after configuring your credentials. A `200` means your integration is ready to call the rest of the endpoints.\n\nDetails about the organization, the cost center and the enabled services do **not** travel in this response: they live in `/api/v6/account/organization`, `/api/v6/account/cost-centers` and `/api/v6/catalog/services`.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 20 requests per minute.", "x-tps": { "limit": 20, "period": 60, "endpointId": "utilities.ping" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 20, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "responses": { "200": { "description": "The key is valid.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingSuccess" }, "example": { "success": true, "data": { "pong": true, "apiVersion": "v6", "client": { "ip": "203.0.113.45" } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 4.24 } } } } }, "401": { "description": "Invalid or missing credentials. The `error.code` tells you the specific reason.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthCostCenterDisabled": { "$ref": "#/components/examples/AuthCostCenterDisabled" } } } } }, "403": { "description": "Credentials are valid, but the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait the time reported in `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateDdosExceeded": { "$ref": "#/components/examples/RateDdosExceeded" }, "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } }, "503": { "description": "Service temporarily unavailable. Retry after the window reported in `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "InfraDbConnectionError": { "$ref": "#/components/examples/InfraDbConnectionError" }, "InfraCacheUnavailable": { "$ref": "#/components/examples/InfraCacheUnavailable" } } } } }, "504": { "description": "Timed out while processing the request. Safe to retry.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "InfraDbQueryTimeout": { "$ref": "#/components/examples/InfraDbQueryTimeout" } } } } } } } }, "/api/v6/tools/countries": { "get": { "operationId": "tools.countries.list", "tags": [ "Tools" ], "summary": "List countries", "description": "Returns the full country catalog the API knows about, with ISO code, calling code, mobile country code (MCC) and names in English and Spanish. Use it to render country pickers, autodetect a country from a phone prefix, or resolve MCCs.\n\nThe catalog rarely changes. The response includes `Cache-Control: public, max-age=3600` so your client and any intermediate CDN can amortize the traffic.\n\nNames are provided only in English (`en`) and Spanish (`es`). Any other `lang` value falls back to English.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "tools.countries.list" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "parameters": [ { "name": "lang", "in": "query", "required": false, "description": "ISO-639-1 code. When specified, each country returns a flat `name` in that locale instead of the full `names` map.", "schema": { "type": "string", "enum": [ "en", "es" ], "example": "es", "description": "ISO-639-1 code. When specified, each country returns a flat `name` in that locale instead of the full `names` map." } }, { "name": "callingCode", "in": "query", "required": false, "description": "Filters countries by E.164 calling code (for example `57` for Colombia). An optional leading `+` is accepted.", "schema": { "type": "string", "example": "57", "description": "Filters countries by E.164 calling code (for example `57` for Colombia). An optional leading `+` is accepted." } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match on the country name in the requested locale. Minimum 2 characters.", "schema": { "type": "string", "example": "col", "minLength": 2, "description": "Case-insensitive substring match on the country name in the requested locale. Minimum 2 characters." } } ], "responses": { "200": { "description": "Country catalog.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesListSuccess" }, "example": { "success": true, "data": [ { "code": "CO", "code3": "COL", "callingCode": "57", "mcc": "732", "flag": "https://flagcdn.com/co.svg", "names": { "en": "Colombia", "es": "Colombia" } }, { "code": "MX", "code3": "MEX", "callingCode": "52", "mcc": "334", "flag": "https://flagcdn.com/mx.svg", "names": { "en": "Mexico", "es": "México" } } ], "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-05-23T02:00:00+00:00", "responseTimeMs": 4.12 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateDdosExceeded": { "$ref": "#/components/examples/RateDdosExceeded" }, "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } }, "503": { "description": "Service temporarily unavailable.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v6/tools/countries/{code}": { "get": { "operationId": "tools.countries.get", "tags": [ "Tools" ], "summary": "Get a country", "description": "Returns one country by its ISO 3166-1 alpha-2 code (2 letters, case-insensitive).\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "tools.countries.get" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "parameters": [ { "name": "code", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 country code (`CO`, `MX`, `US`...). Case-insensitive.", "schema": { "type": "string", "example": "CO", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (`CO`, `MX`, `US`...). Case-insensitive." } }, { "name": "lang", "in": "query", "required": false, "description": "ISO-639-1 locale. Returns a flat `name` in that locale instead of the full `names` map.", "schema": { "type": "string", "enum": [ "en", "es" ], "example": "es", "description": "ISO-639-1 locale. Returns a flat `name` in that locale instead of the full `names` map." } } ], "responses": { "200": { "description": "Country data.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountrySingleSuccess" }, "example": { "success": true, "data": { "code": "CO", "code3": "COL", "callingCode": "57", "mcc": "732", "flag": "https://flagcdn.com/co.svg", "name": "Colombia" }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-05-23T02:00:00+00:00", "responseTimeMs": 2.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "404": { "description": "No country exists with that code.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "CountryNotFound": { "$ref": "#/components/examples/CountryNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/numberinsight/{number}": { "get": { "operationId": "numberinsight.lookup", "tags": [ "Number Insight" ], "summary": "Single number lookup", "description": "Resolves a phone number: country, line type, carrier (porting-aware in Colombia), area and, for Colombia, the routing NRN.\n\nThe response shape is identical for Colombia and international numbers: fields that do not apply come back as `null`, so your client needs a single parsing branch.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 60, "period": 60, "endpointId": "numberinsight.lookup" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "parameters": [ { "name": "number", "in": "path", "required": true, "description": "Number in E.164 (`+5491123456789`), E.164 without `+` (`5491123456789`) or Colombian national format (10 digits).", "schema": { "type": "string", "example": "3001234567", "minLength": 6, "maxLength": 32, "description": "Number in E.164 (`+5491123456789`), E.164 without `+` (`5491123456789`) or Colombian national format (10 digits)." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 1, "maxLength": 255, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency)." } } ], "responses": { "200": { "description": "Number resolved. Non-applicable fields come back `null`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberInsightSuccess" }, "example": { "success": true, "data": { "phoneNumber": { "e164": "+573001234567", "national": "3001234567", "raw": "3001234567" }, "valid": true, "country": { "iso2": "CO", "callingCode": "57", "name": "Colombia", "mcc": "732" }, "lineType": "mobile", "numberType": "mobile", "ported": true, "operator": { "name": "Tigo", "brand": "Tigo", "mnc": "103", "nrn": "103" }, "area": null, "timezone": null, "portability": { "donorOperator": { "name": "Claro", "brand": "Claro" }, "initialOperator": { "name": "Claro", "brand": "Claro" }, "activatedAt": "2024-08-12", "processedAt": "2024-08-11T14:32:00Z", "sourceDate": "2024-08-11" }, "zone": { "id": "103", "name": "Tigo" } }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-18T09:00:00+00:00", "responseTimeMs": 2.1 } } } } }, "400": { "description": "Invalid idempotency key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyInvalid": { "$ref": "#/components/examples/IdempotencyKeyInvalid" } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "403": { "description": "The account cannot run this lookup.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" } } } } }, "409": { "description": "A request with the same idempotency key is still in progress.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyInProgress": { "$ref": "#/components/examples/IdempotencyInProgress" } } } } }, "422": { "description": "The idempotency key was reused with a different body.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyReused": { "$ref": "#/components/examples/IdempotencyKeyReused" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } }, "503": { "description": "The lookup service is refreshing. Retry in a few seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "InfraCacheUnavailable": { "$ref": "#/components/examples/InfraCacheUnavailable" } } } } } } } }, "/api/v6/numberinsight/batch": { "post": { "operationId": "numberinsight.batch", "tags": [ "Number Insight" ], "summary": "Batch lookup", "description": "Processes many numbers in a single request. There are two modes, chosen by the `Content-Type`.\n\nWhen the asynchronous job finishes, the `numberinsight.batch.completed` event is dispatched and the NDJSON result becomes available through a temporary download URL exposed by the status endpoint.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 10 requests per minute.\n- Synchronous mode: up to 500 numbers per request.\n- Asynchronous mode: plain UTF-8 text file, one number per line, each line at most 64 characters.\n- A job result stays available for about 90 days from creation.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 10, "period": 60, "endpointId": "numberinsight.batch" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 10, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 1, "maxLength": 255, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 500, "description": "Numbers to resolve. Same format as the single lookup." } }, "required": [ "numbers" ] }, "example": { "numbers": [ "3001234567", "6017430000", "+5491123456789" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Plain UTF-8 text file, one number per line (each line at most 64 characters)." }, "webhookUrl": { "type": "string", "format": "uri", "description": "Optional URL to receive the `numberinsight.batch.completed` event when the job finishes." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Synchronous mode: resolved inline.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberInsightBatchSyncSuccess" }, "example": { "success": true, "data": { "results": [ { "phoneNumber": { "e164": "+573001234567", "national": "3001234567", "raw": "3001234567" }, "valid": true, "country": { "iso2": "CO", "callingCode": "57", "name": "Colombia", "mcc": "732" }, "lineType": "mobile", "numberType": "mobile", "ported": false, "operator": { "name": "Tigo", "brand": "Tigo", "mnc": "103", "nrn": "103" }, "area": null, "timezone": null, "portability": null, "zone": { "id": "103", "name": "Tigo" } } ] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "202": { "description": "Asynchronous mode: job accepted and queued.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberInsightBatchQueuedSuccess" }, "example": { "success": true, "data": { "jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1", "status": "queued", "count": 12450, "expiresAt": "2026-09-15T14:00:00Z" }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "400": { "description": "Missing `numbers` in synchronous mode, malformed body, or an idempotency key that does not match the format.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyInvalid": { "$ref": "#/components/examples/IdempotencyKeyInvalid" } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "409": { "description": "A request with the same idempotency key is still in progress.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyInProgress": { "$ref": "#/components/examples/IdempotencyInProgress" } } } } }, "413": { "description": "The synchronous batch exceeded 500 numbers: use the asynchronous mode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The asynchronous file is invalid (not text, lines longer than 64 characters, or empty), or the idempotency key was reused with a different body.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyReused": { "$ref": "#/components/examples/IdempotencyKeyReused" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } }, "503": { "description": "The lookup service is refreshing. Retry in a few seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "InfraCacheUnavailable": { "$ref": "#/components/examples/InfraCacheUnavailable" } } } } } } } }, "/api/v6/numberinsight/batch/{jobId}": { "get": { "operationId": "numberinsight.batch.status", "tags": [ "Number Insight" ], "summary": "Batch job status", "description": "Returns the state of a job created with `POST /api/v6/numberinsight/batch`. When `status` is `done`, the response includes `download.url`, a temporary download URL valid for 60 minutes with the resulting NDJSON.\n\nThe job stays available for about 90 days from creation. After that it returns `404`.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "numberinsight.batch.status" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "UUID returned at job creation.", "schema": { "type": "string", "format": "uuid", "example": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1", "description": "UUID returned at job creation." } } ], "responses": { "200": { "description": "Job state.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberInsightBatchJobSuccess" }, "example": { "success": true, "data": { "jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1", "status": "done", "count": 12450, "processed": 12450, "createdAt": "2026-06-18T09:00:00Z", "expiresAt": "2026-09-15T14:00:00Z", "download": { "url": "https://developers.hablame.co/api/v6/numberinsight/downloads/4e2c8b91.ndjson?expires=1789000000&signature=...", "format": "ndjson" } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "400": { "description": "Empty `jobId`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "404": { "description": "Job not found, owned by another account, expired or already purged.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/urlshortener/links": { "post": { "operationId": "urlshortener.create", "tags": [ "URL Shortener" ], "summary": "Create a short link", "description": "Creates a short link on one of your domains. The code is generated automatically (base36, 7 characters) unless you pass your own `alias`. Codes are unique **per domain**: the same alias can exist on two different domains.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 35 requests per second.\n- The destination URL allows up to 2048 characters.\n- Destinations pointing to private or reserved hosts are rejected.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 35, "period": 1, "endpointId": "urlshortener.create" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 35, "windowSeconds": 1 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "minLength": 1, "maxLength": 255, "description": "Optional idempotency key (1 to 255 characters from `A-Za-z0-9_-`). Repeating the same operation with the same key returns the original response without running it again. See the [idempotency guide](/docs/idempotency)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/landing?utm_source=sms", "description": "Destination URL. Absolute `http` or `https`, max 2048 characters. Private or reserved hosts are rejected." }, "domain": { "type": "string", "example": "go.acme.co", "description": "Domain to publish on. Must be available to your account (see `GET /api/v6/urlshortener/domains`). Defaults to your default domain." }, "alias": { "type": "string", "example": "spring-sale", "pattern": "^[a-z0-9_-]{3,32}$", "description": "Optional custom code (3 to 32 characters: lowercase letters, digits, `-` and `_`). Must be free on the domain and not a reserved word." }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-12-31T23:59:59Z", "description": "Optional expiry in ISO-8601, always in the future. After that date the link returns `410`." } }, "required": [ "url" ] }, "example": { "url": "https://example.com/landing?utm_source=sms", "domain": "go.acme.co", "alias": "spring-sale" } } } }, "responses": { "201": { "description": "Link created. In the extreme case where the immediate re-read fails, `data` carries only `code` and `domain`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSuccess" }, "example": { "success": true, "data": { "id": 1024, "code": "a1b2c3d", "domain": "go.acme.co", "shortUrl": "https://go.acme.co/a1b2c3d", "longUrl": "https://example.com/landing?utm_source=sms", "alias": false, "active": true, "expiresAt": null, "createdAt": "2026-06-01T15:04:05Z", "clicks": 0, "uniqueClicks": 0, "lastClickAt": null }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T15:04:05+00:00", "responseTimeMs": 7.2 } } } } }, "400": { "description": "Invalid input (destination URL, alias, expiry or domain), or a malformed idempotency key.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyInvalid": { "$ref": "#/components/examples/IdempotencyKeyInvalid" }, "UrlInvalid": { "$ref": "#/components/examples/UrlInvalid" }, "UrlSchemeNotAllowed": { "$ref": "#/components/examples/UrlSchemeNotAllowed" }, "UrlTooLong": { "$ref": "#/components/examples/UrlTooLong" }, "UrlBlockedHost": { "$ref": "#/components/examples/UrlBlockedHost" }, "AliasInvalid": { "$ref": "#/components/examples/AliasInvalid" }, "ExpiresAtInvalid": { "$ref": "#/components/examples/ExpiresAtInvalid" }, "DomainNotAllowed": { "$ref": "#/components/examples/DomainNotAllowed" } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The organization is read-only, or cannot create the link.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" } } } } }, "409": { "description": "The alias is already taken on this domain, or a request with the same idempotency key is still in progress.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyInProgress": { "$ref": "#/components/examples/IdempotencyInProgress" }, "AliasTaken": { "$ref": "#/components/examples/AliasTaken" }, "AliasReserved": { "$ref": "#/components/examples/AliasReserved" } } } } }, "422": { "description": "The idempotency key was reused with a different body.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "IdempotencyKeyReused": { "$ref": "#/components/examples/IdempotencyKeyReused" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } }, "get": { "operationId": "urlshortener.list", "tags": [ "URL Shortener" ], "summary": "List short links", "description": "Lists your short links, newest first, with click counters already consolidated on each item.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 30 requests per minute.\n- Up to 100 items per page.", "x-tps": { "limit": 30, "period": 60, "endpointId": "urlshortener.list" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "default": 1, "minimum": 1, "description": "1-based page number." } }, { "name": "perPage", "in": "query", "required": false, "description": "Items per page (max 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "Items per page (max 100)." } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active state.", "schema": { "type": "boolean", "description": "Filter by active state." } }, { "name": "domain", "in": "query", "required": false, "description": "Filter by domain.", "schema": { "type": "string", "description": "Filter by domain." } }, { "name": "search", "in": "query", "required": false, "description": "Substring match on the code or the destination URL (minimum 2 characters).", "schema": { "type": "string", "minLength": 2, "description": "Substring match on the code or the destination URL (minimum 2 characters)." } } ], "responses": { "200": { "description": "Page of links.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkListSuccess" }, "example": { "success": true, "data": { "items": [ { "id": 1024, "code": "a1b2c3d", "domain": "go.acme.co", "shortUrl": "https://go.acme.co/a1b2c3d", "longUrl": "https://example.com/landing", "active": true, "expiresAt": null, "createdAt": "2026-06-01T15:04:05Z", "clicks": 128, "uniqueClicks": 96, "lastClickAt": "2026-06-01T18:22:10Z" } ], "page": 1, "perPage": 20, "total": 1, "hasMore": false }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T18:30:00+00:00", "responseTimeMs": 5.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/urlshortener/domains": { "get": { "operationId": "urlshortener.domains", "tags": [ "URL Shortener" ], "summary": "List available domains", "description": "Lists the domains your account can publish short links on: platform-wide domains plus your own, with the default one first.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 30 requests per minute.", "x-tps": { "limit": 30, "period": 60, "endpointId": "urlshortener.domains" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "urlshortener" }, "responses": { "200": { "description": "Available domains.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsListSuccess" }, "example": { "success": true, "data": [ { "domain": "go.acme.co", "isDefault": true, "verified": true, "global": false }, { "domain": "hbl.li", "isDefault": false, "verified": true, "global": true } ], "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T18:30:00+00:00", "responseTimeMs": 2 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/urlshortener/links/{domain}/{code}": { "get": { "operationId": "urlshortener.get", "tags": [ "URL Shortener" ], "summary": "Get a short link", "description": "Returns one short link you own. A link belonging to another account returns `404`: its existence is not disclosed.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "urlshortener.get" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain of the link.", "schema": { "type": "string", "example": "go.acme.co", "description": "Domain of the link." } }, { "name": "code", "in": "path", "required": true, "description": "Short code or alias (lowercase).", "schema": { "type": "string", "example": "a1b2c3d", "description": "Short code or alias (lowercase)." } } ], "responses": { "200": { "description": "The link.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSuccess" }, "example": { "success": true, "data": { "id": 1024, "code": "a1b2c3d", "domain": "go.acme.co", "shortUrl": "https://go.acme.co/a1b2c3d", "longUrl": "https://example.com/landing?utm_source=sms", "alias": false, "active": true, "expiresAt": null, "createdAt": "2026-06-01T15:04:05Z", "clicks": 0, "uniqueClicks": 0, "lastClickAt": null }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T15:04:05+00:00", "responseTimeMs": 7.2 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No link with that domain and code.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "LinkNotFound": { "$ref": "#/components/examples/LinkNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } }, "patch": { "operationId": "urlshortener.update", "tags": [ "URL Shortener" ], "summary": "Update a short link", "description": "Updates the `active` state, the `expiresAt` date (send `null` to clear it) or the destination `longUrl`, which is revalidated. The code or alias is immutable. At least one field is required.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 35 requests per second.", "x-tps": { "limit": 35, "period": 1, "endpointId": "urlshortener.update" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 35, "windowSeconds": 1 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain of the link.", "schema": { "type": "string", "example": "go.acme.co", "description": "Domain of the link." } }, { "name": "code", "in": "path", "required": true, "description": "Short code or alias (lowercase).", "schema": { "type": "string", "example": "a1b2c3d", "description": "Short code or alias (lowercase)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Enables or disables the link." }, "expiresAt": { "type": "string", "format": "date-time", "description": "New expiry, or `null` to clear it." }, "longUrl": { "type": "string", "format": "uri", "description": "New destination URL. Revalidated as on creation." } } }, "example": { "active": false } } } }, "responses": { "200": { "description": "Link updated.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSuccess" }, "example": { "success": true, "data": { "id": 1024, "code": "a1b2c3d", "domain": "go.acme.co", "shortUrl": "https://go.acme.co/a1b2c3d", "longUrl": "https://example.com/landing?utm_source=sms", "alias": false, "active": true, "expiresAt": null, "createdAt": "2026-06-01T15:04:05Z", "clicks": 0, "uniqueClicks": 0, "lastClickAt": null }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T15:04:05+00:00", "responseTimeMs": 7.2 } } } } }, "400": { "description": "Nothing to update, or an invalid field.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "UrlInvalid": { "$ref": "#/components/examples/UrlInvalid" }, "UrlSchemeNotAllowed": { "$ref": "#/components/examples/UrlSchemeNotAllowed" }, "UrlTooLong": { "$ref": "#/components/examples/UrlTooLong" }, "UrlBlockedHost": { "$ref": "#/components/examples/UrlBlockedHost" }, "ExpiresAtInvalid": { "$ref": "#/components/examples/ExpiresAtInvalid" }, "NothingToUpdate": { "$ref": "#/components/examples/NothingToUpdate" } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No link with that domain and code.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "LinkNotFound": { "$ref": "#/components/examples/LinkNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } }, "delete": { "operationId": "urlshortener.delete", "tags": [ "URL Shortener" ], "summary": "Delete a short link", "description": "A **hard** delete: the link and all of its analytics (daily, hourly and per-dimension visits) are removed in the same transaction. There is no way to recover it; if you need to keep the numbers, export them first with the statistics endpoint.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 35 requests per second.", "x-tps": { "limit": 35, "period": 1, "endpointId": "urlshortener.delete" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 35, "windowSeconds": 1 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain of the link.", "schema": { "type": "string", "example": "go.acme.co", "description": "Domain of the link." } }, { "name": "code", "in": "path", "required": true, "description": "Short code or alias (lowercase).", "schema": { "type": "string", "example": "a1b2c3d", "description": "Short code or alias (lowercase)." } } ], "responses": { "200": { "description": "Link deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedSuccess" }, "example": { "success": true, "data": { "deleted": "a1b2c3d", "domain": "go.acme.co" }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T18:30:00+00:00", "responseTimeMs": 3 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No link with that domain and code.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "LinkNotFound": { "$ref": "#/components/examples/LinkNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/urlshortener/links/{domain}/{code}/stats": { "get": { "operationId": "urlshortener.stats", "tags": [ "URL Shortener" ], "summary": "Link statistics", "description": "Click analytics for one link: totals, a time series and top-N breakdowns by dimension. Day and hour buckets are computed in `America/Bogota`.\n\n## Scope and limits\n\n- Access: API key with the `urlshortener` service enabled.\n- Limit: 120 requests per minute.\n- Hourly granularity is only available for ranges of 31 days or less, within the last 90 days.", "x-tps": { "limit": 120, "period": 60, "endpointId": "urlshortener.stats" }, "x-scope": { "type": "service", "value": "urlshortener" }, "x-limit": { "requests": 120, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "urlshortener" }, "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain of the link.", "schema": { "type": "string", "example": "go.acme.co", "description": "Domain of the link." } }, { "name": "code", "in": "path", "required": true, "description": "Short code or alias (lowercase).", "schema": { "type": "string", "example": "a1b2c3d", "description": "Short code or alias (lowercase)." } }, { "name": "range", "in": "query", "required": false, "description": "Preset window. Ignored when you send `from` or `to`.", "schema": { "type": "string", "enum": [ "last_24h", "last_7d", "last_30d", "last_90d", "this_month", "last_month", "ytd", "all_time" ], "default": "last_30d", "description": "Preset window. Ignored when you send `from` or `to`." } }, { "name": "from", "in": "query", "required": false, "description": "Start of a custom window (ISO-8601).", "schema": { "type": "string", "format": "date-time", "description": "Start of a custom window (ISO-8601)." } }, { "name": "to", "in": "query", "required": false, "description": "End of the custom window (ISO-8601). Defaults to now.", "schema": { "type": "string", "format": "date-time", "description": "End of the custom window (ISO-8601). Defaults to now." } }, { "name": "granularity", "in": "query", "required": false, "description": "Automatic when omitted.", "schema": { "type": "string", "enum": [ "hour", "day" ], "description": "Automatic when omitted." } }, { "name": "dimensions", "in": "query", "required": false, "description": "Comma-separated breakdown dimensions: `country`, `subdivision`, `city`, `device`, `os`, `browser`, `referrer`.", "schema": { "type": "string", "example": "country,device,referrer", "description": "Comma-separated breakdown dimensions: `country`, `subdivision`, `city`, `device`, `os`, `browser`, `referrer`." } } ], "responses": { "200": { "description": "Link analytics.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkStatsSuccess" }, "example": { "success": true, "data": { "code": "a1b2c3d", "domain": "go.acme.co", "range": { "from": "2026-05-03T00:00:00-05:00", "to": "2026-06-01T18:30:00-05:00", "granularity": "day" }, "totals": { "clicks": 128, "uniqueClicks": 96, "firstClickAt": "2026-05-04T12:00:00Z", "lastClickAt": "2026-06-01T18:22:10Z" }, "series": [ { "ts": "2026-05-04", "clicks": 40, "uniqueClicks": 31 } ], "breakdowns": { "country": [ { "key": "CO", "clicks": 90 }, { "key": "__other", "clicks": 38 } ], "device": [ { "key": "mobile", "clicks": 110 } ] } }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-01T18:30:00+00:00", "responseTimeMs": 9.4 } } } } }, "400": { "description": "Invalid range or granularity.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "StatsRangeInvalid": { "$ref": "#/components/examples/StatsRangeInvalid" } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No link with that domain and code.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "LinkNotFound": { "$ref": "#/components/examples/LinkNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/tts/synthesize": { "post": { "operationId": "tts.synthesize", "tags": [ "Text-to-Speech" ], "summary": "Synthesize text to speech", "description": "Turns a text into an audio file and returns its reference. Synthesis is **synchronous**: the response arrives once the audio is ready.\n\nThe voice is chosen with `voice`, using a `code` from the catalog (see `GET /api/v6/tts/voices`). Text allows up to 4000 characters per request.\n\nThe same text with the same voice is reused automatically: if you already generated that audio, the response arrives with `cached: true` and without processing it again.\n\n## Scope and limits\n\n- Access: API key with the `tts` service enabled.\n- Limit: 60 requests per minute.\n- Up to 4000 characters of text per request.\n- Audio lifetime ranges from 1 hour to 1 year; the default is 30 days.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 60, "period": 60, "endpointId": "tts.synthesize" }, "x-scope": { "type": "service", "value": "tts" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "tts" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "example": "Hola, te llamamos de Acme para confirmar tu cita.", "minLength": 1, "maxLength": 4000, "description": "Text to synthesize. Between 1 and 4000 characters." }, "voice": { "type": "string", "example": "es-us-female-2", "description": "Voice code from the catalog (see `GET /api/v6/tts/voices`)." }, "speakingRate": { "type": "number", "default": 1, "minimum": 0.25, "maximum": 4, "description": "Speaking rate, from 0.25 to 4.0. Defaults to 1.0." }, "format": { "type": "string", "enum": [ "wav" ], "description": "Audio format. Only `wav` for now." }, "ttlSeconds": { "type": "integer", "default": 2592000, "minimum": 3600, "maximum": 31536000, "description": "Audio lifetime in seconds (minimum 1 hour, maximum 1 year). Set when the audio is created; reusing an already-generated audio keeps its original lifetime." } }, "required": [ "text", "voice" ] }, "example": { "text": "Hola, te llamamos de Acme para confirmar tu cita.", "voice": "es-us-female-2", "speakingRate": 1 } } } }, "responses": { "201": { "description": "Audio ready, freshly generated or reused.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsSynthesizeSuccess" }, "example": { "success": true, "data": { "id": "01J9Z4M7K2QABCDEF5GHTV3WXY", "status": "completed", "cached": false, "charCount": 49, "durationMs": 3120, "voice": "es-us-female-2", "cost": "12.500000", "currency": "COP", "audioUrl": "https://storage.hablame.co/tts/9f2c...e1.wav?Expires=...&Signature=..." }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 412.5 } } } } }, "400": { "description": "Invalid input: empty or too long text, unknown voice, or an out-of-range parameter.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "402": { "description": "Insufficient balance to generate the audio.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The API key does not have the `tts` service enabled, or a spending limit prevents generation.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/tts/synthesis/{id}": { "get": { "operationId": "tts.synthesis.get", "tags": [ "Text-to-Speech" ], "summary": "Synthesis status", "description": "Reads the metadata of a synthesis request by its `id`, the one returned by `POST /api/v6/tts/synthesize`. You can only access requests from your own organization.\n\n## Scope and limits\n\n- Access: API key with the `tts` service enabled.\n- Limit: 120 requests per minute.", "x-tps": { "limit": 120, "period": 60, "endpointId": "tts.synthesis.get" }, "x-scope": { "type": "service", "value": "tts" }, "x-limit": { "requests": 120, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "tts" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Synthesis identifier returned when synthesizing.", "schema": { "type": "string", "example": "01J9Z4M7K2QABCDEF5GHTV3WXY", "description": "Synthesis identifier returned when synthesizing." } } ], "responses": { "200": { "description": "Synthesis metadata.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsSynthesisSuccess" }, "example": { "success": true, "data": { "id": "01J9Z4M7K2QABCDEF5GHTV3WXY", "status": "completed", "cached": false, "charCount": 49, "durationMs": 3120, "language": "es-US", "voice": "es-us-female-2", "tier": "intermediate", "cost": "12.500000", "currency": "COP", "audioUrl": "https://storage.hablame.co/tts/9f2c...e1.wav?Expires=...&Signature=...", "reference": null, "errorCode": null, "createdAt": "2026-06-23 15:04:05" }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:06:10+00:00", "responseTimeMs": 2.3 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No synthesis exists with that id for your organization.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/tts/voices": { "get": { "operationId": "tts.voices.list", "tags": [ "Text-to-Speech" ], "summary": "List available voices", "description": "Returns the voice catalog for synthesis. Each voice carries a stable `code` you send in the `voice` field when synthesizing. The catalog rarely changes, so caching it on your side is worth it.\n\n## Scope and limits\n\n- Access: API key with the `tts` service enabled.\n- Limit: 120 requests per minute.", "x-tps": { "limit": 120, "period": 60, "endpointId": "tts.voices.list" }, "x-scope": { "type": "service", "value": "tts" }, "x-limit": { "requests": 120, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "tts" }, "parameters": [ { "name": "language", "in": "query", "required": false, "description": "Filter by language and region (BCP-47), for example `es-US` or `en-US`.", "schema": { "type": "string", "example": "es-US", "description": "Filter by language and region (BCP-47), for example `es-US` or `en-US`." } }, { "name": "tier", "in": "query", "required": false, "description": "Filter by voice quality level.", "schema": { "type": "string", "enum": [ "basic", "intermediate", "advanced" ], "description": "Filter by voice quality level." } }, { "name": "gender", "in": "query", "required": false, "description": "Filter by voice gender.", "schema": { "type": "string", "enum": [ "female", "male" ], "description": "Filter by voice gender." } } ], "responses": { "200": { "description": "Voice catalog, filtered when parameters were sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicesListSuccess" }, "example": { "success": true, "data": { "voices": [ { "code": "es-us-female-2", "name": "Valentina · Español Latinoamérica", "language": "es-US", "accent": "Español Latinoamérica", "gender": "female", "tier": "intermediate", "sampleRate": 8000 }, { "code": "en-us-female-1", "name": "Emma · Inglés (EE. UU.)", "language": "en-US", "accent": "Inglés (EE. UU.)", "gender": "female", "tier": "basic", "sampleRate": 8000 } ] }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 1.4 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key does not have the `tts` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/callblasting/calls": { "post": { "operationId": "callblasting.calls.create", "tags": [ "Call Blasting" ], "summary": "Call with generated voice", "description": "Sends a call that plays a text-to-speech audio. The audio is synthesized when the process is created and reused if it already existed, at no extra charge.\n\nThe voice is always chosen by catalog code (`voice`). Pre-recorded audio has its own endpoint: `POST /api/v6/callblasting/calls/audio`.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 60 requests per minute.\n- Up to 4000 characters of text per call.\n- Up to 5 attempts per call.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 60, "period": 60, "endpointId": "callblasting.calls.create" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "example": "573001234567", "description": "Destination number in international format, digits only (7 to 18)." }, "text": { "type": "string", "example": "Hola, te llamamos de Acme para confirmar tu cita del jueves.", "minLength": 1, "maxLength": 4000, "description": "Text to synthesize (1 to 4000 characters)." }, "voice": { "type": "string", "example": "es-us-female-1", "description": "Voice code from the catalog (see `GET /api/v6/callblasting/voices`)." }, "callerId": { "type": "string", "example": "6015551234", "description": "Number shown to the person receiving the call." }, "clientReference": { "type": "string", "example": "campania-abril-0012", "maxLength": 128, "description": "Your own reference to correlate the call (max 128 characters)." }, "repeat": { "type": "integer", "default": 2, "minimum": 1, "maximum": 5, "description": "Times the message is played." }, "recordingTtlSec": { "type": "integer", "example": 86400, "description": "Recording retention in seconds. Defaults to 24 hours; minimum 24 hours, maximum 1 year." }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "default": 2, "minimum": 1, "maximum": 5, "description": "Number of attempts." }, "minIntervalSec": { "type": "integer", "default": 300, "minimum": 300, "maximum": 900, "description": "Minimum wait between attempts, in seconds." }, "minSuccessSec": { "type": "integer", "default": 5, "minimum": 1, "maximum": 30, "description": "Minimum duration for the call to count as successful, in seconds." } }, "description": "Retry tuning. Which states are retried is a fixed service policy; here you only tune the limits." } }, "required": [ "to", "text", "voice" ] }, "example": { "to": "573001234567", "text": "Hola, te llamamos de Acme para confirmar tu cita del jueves.", "voice": "es-us-female-1", "clientReference": "campania-abril-0012", "repeat": 2 } } } }, "responses": { "202": { "description": "Call queued.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallQueuedSuccess" }, "example": { "success": true, "data": { "id": "cb_9f2c0e2a1d8b", "to": "573001234567", "status": "queued", "clientReference": "campania-abril-0012" }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 412.5 } } } } }, "400": { "description": "Invalid number, missing text, or unknown voice.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "402": { "description": "Insufficient balance to generate the call audio.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "The API key does not have the `callblasting` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/callblasting/calls/audio": { "post": { "operationId": "callblasting.calls.audio", "tags": [ "Call Blasting" ], "summary": "Call with pre-recorded audio", "description": "Sends a call that plays a pre-recorded audio. There are two ways to do it.\n\nThe rest of the fields are the same as in the text-to-speech send.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 60 requests per minute.\n- The audio file allows up to 20 MB.\n- Supports `Idempotency-Key`.", "x-tps": { "limit": 60, "period": 60, "endpointId": "callblasting.calls.audio" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "example": "573001234567", "description": "Destination number in international format, digits only." }, "audioId": { "type": "string", "example": "01J9Z4M7K2QABCDEF5GHTV3WXY", "description": "Id of an already uploaded audio." }, "callerId": { "type": "string", "example": "6015551234", "description": "Number shown to the person receiving the call." }, "clientReference": { "type": "string", "example": "campania-abril-0012", "maxLength": 128, "description": "Your own reference to correlate the call (max 128 characters)." }, "repeat": { "type": "integer", "default": 2, "minimum": 1, "maximum": 5, "description": "Times the message is played." }, "recordingTtlSec": { "type": "integer", "example": 86400, "description": "Recording retention in seconds. Defaults to 24 hours; minimum 24 hours, maximum 1 year." }, "retry": { "type": "object", "properties": { "maxAttempts": { "type": "integer", "default": 2, "minimum": 1, "maximum": 5, "description": "Number of attempts." }, "minIntervalSec": { "type": "integer", "default": 300, "minimum": 300, "maximum": 900, "description": "Minimum wait between attempts, in seconds." }, "minSuccessSec": { "type": "integer", "default": 5, "minimum": 1, "maximum": 30, "description": "Minimum duration for the call to count as successful, in seconds." } }, "description": "Retry tuning. Which states are retried is a fixed service policy; here you only tune the limits." } }, "required": [ "to", "audioId" ] }, "example": { "to": "573001234567", "audioId": "01J9Z4M7K2QABCDEF5GHTV3WXY", "clientReference": "campania-abril-0012" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "to": { "type": "string", "example": "573001234567", "description": "Destination number in international format." }, "file": { "type": "string", "format": "binary", "description": "Audio file (wav, mp3, ogg or m4a; max 20 MB)." }, "callerId": { "type": "string", "description": "Number shown to the person receiving the call." }, "clientReference": { "type": "string", "description": "Your own reference to correlate the call." }, "repeat": { "type": "integer", "description": "Times the message is played." }, "recordingTtlSec": { "type": "integer", "description": "Recording retention in seconds." } }, "required": [ "to", "file" ] } } } }, "responses": { "202": { "description": "Call queued.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Status": { "$ref": "#/components/headers/Idempotency-Status" }, "Idempotency-Replayed": { "$ref": "#/components/headers/Idempotency-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioCallQueuedSuccess" }, "example": { "success": true, "data": { "id": "cb_9f2c0e2a1d8b", "to": "573001234567", "status": "queued", "audioId": "01J9Z4M7K2QABCDEF5GHTV3WXY", "clientReference": "campania-abril-0012" }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 22.7 } } } } }, "400": { "description": "Invalid number, missing audio (`file` or `audioId`), unsupported format or invalid audio.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key does not have the `callblasting` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" } } } } }, "404": { "description": "No audio exists with that `audioId` for your organization.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "The audio is empty or exceeds the maximum allowed size.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/callblasting/calls/{id}": { "get": { "operationId": "callblasting.calls.get", "tags": [ "Call Blasting" ], "summary": "Call status", "description": "Returns a call status and the history of its attempts: whether it was answered, duration, hangup cause, recording and dialed digits. You can only access calls from your organization.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 120 requests per minute.", "x-tps": { "limit": 120, "period": 60, "endpointId": "callblasting.calls.get" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 120, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call id returned when it was created.", "schema": { "type": "string", "example": "cb_9f2c0e2a1d8b", "description": "Call id returned when it was created." } } ], "responses": { "200": { "description": "Call status and its attempts.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallSuccess" }, "example": { "success": true, "data": { "id": "cb_9f2c0e2a1d8b", "to": "573001234567", "clientReference": "campania-abril-0012", "status": "success", "attemptsCount": 1, "attempts": [ { "attempt": 1, "status": "completed", "answered": true, "audioPlayed": true, "durationTotal": 18, "durationAir": 12, "hangupCause": 16, "causeText": "Normal Clearing", "recorded": false, "dtmf": null, "startedAt": "2026-06-23 15:04:06", "answeredAt": "2026-06-23 15:04:09", "endedAt": "2026-06-23 15:04:21" } ], "createdAt": "2026-06-23 15:04:05" }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:05:00+00:00", "responseTimeMs": 3.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "404": { "description": "No call exists with that id for your organization.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/callblasting/audios": { "post": { "operationId": "callblasting.audios.upload", "tags": [ "Call Blasting" ], "summary": "Upload a pre-recorded audio", "description": "Uploads a pre-recorded audio that stays in your catalog to reuse across as many calls as you want. Accepts `wav`, `mp3`, `ogg` and `m4a`, up to 20 MB, and we prepare it for the voice network.\n\nReturns an `id` you later send as `audioId` when creating a call. Uploading the same audio twice returns the same `id`: nothing is duplicated.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 30 requests per minute.\n- Accepted formats: wav, mp3, ogg and m4a. Up to 20 MB.", "x-tps": { "limit": 30, "period": 60, "endpointId": "callblasting.audios.upload" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Audio file (wav, mp3, ogg or m4a; max 20 MB)." }, "name": { "type": "string", "example": "Bienvenida campaña abril", "maxLength": 120, "description": "Optional label to identify the audio (max 120 characters)." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Audio uploaded, or reused if it already existed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioUploadSuccess" }, "example": { "success": true, "data": { "id": "01J9Z4M7K2QABCDEF5GHTV3WXY", "durationMs": 4200, "format": "mp3", "sizeBytes": 67200, "cached": false }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 180.4 } } } } }, "400": { "description": "Missing file, unsupported format, or the audio could not be processed.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key does not have the `callblasting` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountReadOnly": { "$ref": "#/components/examples/AccountReadOnly" } } } } }, "413": { "description": "The audio is empty or exceeds the maximum allowed size.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } }, "get": { "operationId": "callblasting.audios.list", "tags": [ "Call Blasting" ], "summary": "List pre-recorded audios", "description": "Returns your organization pre-recorded audios, with their `id` (the one you send as `audioId`), name, source format, duration and size.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "callblasting.audios.list" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "responses": { "200": { "description": "Audio catalog.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudiosListSuccess" }, "example": { "success": true, "data": { "audios": [ { "id": "01J9Z4M7K2QABCDEF5GHTV3WXY", "name": "Bienvenida campaña abril", "originalName": "bienvenida.mp3", "format": "mp3", "durationMs": 4200, "sizeBytes": 67200, "createdAt": "2026-06-23 15:04:05" } ] }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 1.9 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key does not have the `callblasting` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/callblasting/voices": { "get": { "operationId": "callblasting.voices.list", "tags": [ "Call Blasting" ], "summary": "List available voices", "description": "Returns the catalog of voices available for Call Blasting text-to-speech. Each voice carries a stable `code` you then send in the `voice` field when creating a call with `text`.\n\nThe catalog rarely changes, so caching it on your side is worth it.\n\n## Scope and limits\n\n- Access: API key with the `callblasting` service enabled.\n- Limit: 120 requests per minute.", "x-tps": { "limit": 120, "period": 60, "endpointId": "callblasting.voices.list" }, "x-scope": { "type": "service", "value": "callblasting" }, "x-limit": { "requests": 120, "windowSeconds": 60 }, "x-access": { "kind": "service", "value": "callblasting" }, "parameters": [ { "name": "language", "in": "query", "required": false, "description": "Filter by language and region (BCP-47), for example `es-US` or `en-US`.", "schema": { "type": "string", "example": "es-US", "description": "Filter by language and region (BCP-47), for example `es-US` or `en-US`." } }, { "name": "tier", "in": "query", "required": false, "description": "Filter by voice quality level.", "schema": { "type": "string", "enum": [ "basic", "intermediate", "advanced" ], "description": "Filter by voice quality level." } }, { "name": "gender", "in": "query", "required": false, "description": "Filter by voice gender.", "schema": { "type": "string", "enum": [ "female", "male" ], "description": "Filter by voice gender." } } ], "responses": { "200": { "description": "Voice catalog, filtered when parameters were sent.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicesListSuccess" }, "example": { "success": true, "data": { "voices": [ { "code": "es-us-female-2", "name": "Valentina · Español Latinoamérica", "language": "es-US", "accent": "Español Latinoamérica", "gender": "female", "tier": "intermediate", "sampleRate": 8000 }, { "code": "es-us-male-7", "name": "Nicolás · Español Latinoamérica", "language": "es-US", "accent": "Español Latinoamérica", "gender": "male", "tier": "advanced", "sampleRate": 8000 } ] }, "meta": { "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6", "timestamp": "2026-06-23T15:04:05+00:00", "responseTimeMs": 1.4 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key does not have the `callblasting` service enabled.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/billing": { "get": { "operationId": "account.billing", "tags": [ "Account" ], "summary": "Billing summary", "description": "Returns the core billing facts for the organization that owns the API key: mode (prepaid or postpaid), currency, available balance in prepaid or remaining credit in postpaid. The detail — limits, payments and adjustments — lives in `/api/v6/account/limits`, `/api/v6/account/payments` and `/api/v6/account/adjustments`.\n\nThe `available` field is computed exactly like the live spend engine: prepaid `balance − consumed`; postpaid `creditLimit − consumed`. All amounts are decimal strings with 6 decimals, in the account `currency`.\n\n## Scope and limits\n\n- Access: API key with the `account` capability granted.\n- Limit: 20 requests per minute.", "x-tps": { "limit": 20, "period": 60, "endpointId": "account.billing" }, "x-scope": { "type": "capability", "value": "account" }, "x-limit": { "requests": 20, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "account" }, "responses": { "200": { "description": "Billing summary.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummarySuccess" }, "example": { "success": true, "data": { "account": { "id": 10000003, "displayName": "Acme S.A.S.", "currency": "COP", "status": "active" }, "billing": { "mode": "prepaid", "currency": "COP", "period": "2026-06", "available": "108500.000000", "balance": "108500.000000", "consumed": "0.000000", "reserve": "0.000000", "creditLimit": "0.000000" } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 6.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait for `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/usage": { "get": { "operationId": "account.usage", "tags": [ "Account" ], "summary": "Usage by scope", "description": "Account usage broken down by scope (organization, cost center, user, API key or service) for a period. The `total` field is the `org:0` usage, that is the grand total. Amounts carry 6 decimals.\n\n## Scope and limits\n\n- Access: API key with the `account` capability granted.\n- Limit: 20 requests per minute.", "x-tps": { "limit": 20, "period": 60, "endpointId": "account.usage" }, "x-scope": { "type": "capability", "value": "account" }, "x-limit": { "requests": 20, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "account" }, "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Period in `YYYY-MM` format. Defaults to the current month.", "schema": { "type": "string", "example": "2026-06", "description": "Period in `YYYY-MM` format. Defaults to the current month." } } ], "responses": { "200": { "description": "Period usage.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSuccess" }, "example": { "success": true, "data": { "period": "2026-06", "total": "108.000000", "scopes": [ { "scopeType": "org", "scopeRef": "0", "consumed": "108.000000" }, { "scopeType": "cost_center", "scopeRef": "17", "consumed": "108.000000" }, { "scopeType": "service", "scopeRef": "urlshortener", "consumed": "108.000000" } ] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait for `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/payments": { "get": { "operationId": "account.payments", "tags": [ "Account" ], "summary": "Payments history", "description": "Payments history: prepaid top-ups and postpaid invoice payments come from the same source. The `kind` field distinguishes `recharge` from `invoice_payment`. Amounts carry 6 decimals.\n\nPagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.\n\n## Scope and limits\n\n- Access: API key with the `account` capability granted.\n- Limit: 30 requests per minute.\n- Pagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.", "x-tps": { "limit": 30, "period": 60, "endpointId": "account.payments" }, "x-scope": { "type": "capability", "value": "account" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "account" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items to return (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "How many items to return (1 to 100)." } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start from.", "schema": { "type": "integer", "default": 0, "description": "Where to start from." } }, { "name": "status", "in": "query", "required": false, "description": "Optional status filter.", "schema": { "type": "string", "description": "Optional status filter." } } ], "responses": { "200": { "description": "Page of payments.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsListSuccess" }, "example": { "success": true, "data": { "items": [ { "reference": "HBL-3WWG4VEH92", "kind": "recharge", "amount": "50000.000000", "currency": "COP", "status": "approved", "method": "new_card", "processor": "epayco", "createdAt": "2026-05-18 12:30:00", "approvedAt": "2026-05-18 12:31:15", "expiresAt": null } ], "pagination": { "limit": 20, "offset": 0, "returned": 1, "hasMore": false } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait for `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/adjustments": { "get": { "operationId": "account.adjustments", "tags": [ "Account" ], "summary": "Balance adjustments", "description": "Manual balance adjustments for the account. Hablame manages them with dual approval (whoever records an adjustment is not the one who approves it). Amounts carry 6 decimals.\n\nPagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.\n\n## Scope and limits\n\n- Access: API key with the `account` capability granted.\n- Limit: 30 requests per minute.\n- Pagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.", "x-tps": { "limit": 30, "period": 60, "endpointId": "account.adjustments" }, "x-scope": { "type": "capability", "value": "account" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "account" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items to return (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "How many items to return (1 to 100)." } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start from.", "schema": { "type": "integer", "default": 0, "description": "Where to start from." } }, { "name": "status", "in": "query", "required": false, "description": "Optional status filter.", "schema": { "type": "string", "description": "Optional status filter." } } ], "responses": { "200": { "description": "Page of adjustments.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentsListSuccess" }, "example": { "success": true, "data": { "items": [ { "reference": "ADJ-20260602-6f0cf241", "direction": "debit", "amount": "10000.000000", "currency": "COP", "category": "manual", "status": "approved", "effectiveDate": "2026-06-02", "reason": "ajuste inicial", "createdAt": "2026-06-02 10:00:00" } ], "pagination": { "limit": 20, "offset": 0, "returned": 1, "hasMore": false } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait for `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/limits": { "get": { "operationId": "account.limits", "tags": [ "Account" ], "summary": "Spending limits", "description": "Active spending limits for the account, by scope. This is a read-only endpoint: limits are configured from the customer portal. Amounts carry 6 decimals and `thresholds` are the percentages at which an alert fires.\n\n## Scope and limits\n\n- Access: API key with the `account` capability granted.\n- Limit: 30 requests per minute.", "x-tps": { "limit": 30, "period": 60, "endpointId": "account.limits" }, "x-scope": { "type": "capability", "value": "account" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "account" }, "responses": { "200": { "description": "Active limits.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitsListSuccess" }, "example": { "success": true, "data": { "items": [ { "scopeType": "org", "scopeRef": "0", "amount": "1000000.000000", "period": "monthly", "thresholds": [ 80, 95 ] } ] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded. Wait for `Retry-After`.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/organization": { "get": { "operationId": "account.organization", "tags": [ "Organization" ], "summary": "Organization", "description": "Profile of the organization that owns the API key: identity and configuration. It does not include balance or credit; that lives in [Billing summary](/docs/reference/account/billing).\n\n## Scope and limits\n\n- Access: API key with the `directory` capability granted.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "account.organization" }, "x-scope": { "type": "capability", "value": "directory" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "directory" }, "responses": { "200": { "description": "Organization profile.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSuccess" }, "example": { "success": true, "data": { "id": 10000003, "displayName": "Acme S.A.S.", "currency": "COP", "billingMode": "prepaid", "status": "active", "blocks": { "general": false, "collections": false, "security": false }, "onboardedAt": "2026-05-14 11:31:56" }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/cost-centers": { "get": { "operationId": "account.costCenters", "tags": [ "Organization" ], "summary": "Cost centers", "description": "Cost centers of the organization. Every API key is bound to one, and that is where usage attribution comes from.\n\n## Scope and limits\n\n- Access: API key with the `directory` capability granted.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "account.costCenters" }, "x-scope": { "type": "capability", "value": "directory" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "directory" }, "responses": { "200": { "description": "Cost centers.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostCentersListSuccess" }, "example": { "success": true, "data": { "items": [ { "id": 17, "code": "1607230448", "name": "Centro de costos general", "status": "active", "isDefault": true } ] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/account/users": { "get": { "operationId": "account.users", "tags": [ "Organization" ], "summary": "Users", "description": "Organization users (members), with their role, cost center and status. It contains personal data: treat it as such in your own systems.\n\nPagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.\n\n## Scope and limits\n\n- Access: API key with the `directory` capability granted.\n- Limit: 30 requests per minute.\n- Pagination with `limit` (default 20, max 100) and `offset` (default 0). The response carries `data.items` and `data.pagination`.", "x-tps": { "limit": 30, "period": 60, "endpointId": "account.users" }, "x-scope": { "type": "capability", "value": "directory" }, "x-limit": { "requests": 30, "windowSeconds": 60 }, "x-access": { "kind": "capability", "value": "directory" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items to return (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "How many items to return (1 to 100)." } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start from.", "schema": { "type": "integer", "default": 0, "description": "Where to start from." } }, { "name": "status", "in": "query", "required": false, "description": "Optional status filter.", "schema": { "type": "string", "description": "Optional status filter." } } ], "responses": { "200": { "description": "Page of users.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersListSuccess" }, "example": { "success": true, "data": { "items": [ { "userId": 10000, "firstName": "Diego", "lastName": "Pérez", "email": "dev@acme.co", "roles": [ "owner" ], "costCenterId": 17, "status": "active", "joinedAt": "2026-05-14 11:31:56", "lastUsedAt": "2026-06-02 09:00:00" } ], "pagination": { "limit": 20, "offset": 0, "returned": 1, "hasMore": false } }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" }, "AuthServiceNotAllowed": { "$ref": "#/components/examples/AuthServiceNotAllowed" } } } } }, "403": { "description": "The API key lacks the required capability, or the organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" }, "AccountConfigNotFound": { "$ref": "#/components/examples/AccountConfigNotFound" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/status": { "get": { "operationId": "platform.status", "tags": [ "Platform" ], "summary": "Service status", "description": "Operational status of Hablame services in a compact form, meant to be integrated into your own monitoring. When there is no data for a component, its `status` arrives as `unknown`.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "platform.status" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "responses": { "200": { "description": "Service status.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStatusSuccess" }, "example": { "success": true, "data": { "status": "operational", "updatedAt": "2026-06-02T19:40:00+00:00", "stale": false, "components": [ { "name": "API", "status": "operational" } ], "incidents": [], "maintenance": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "403": { "description": "The organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } }, "/api/v6/catalog/services": { "get": { "operationId": "catalog.services", "tags": [ "Platform" ], "summary": "Service catalog", "description": "Catalog of the live platform services, with an `enabled` flag telling whether this account has access to each one. Useful to build menus or validations in your own interface without hardcoding the list.\n\n## Scope and limits\n\n- Access: Any valid API key.\n- Limit: 60 requests per minute.", "x-tps": { "limit": 60, "period": 60, "endpointId": "catalog.services" }, "x-scope": { "type": "universal" }, "x-limit": { "requests": 60, "windowSeconds": 60 }, "x-access": { "kind": "universal" }, "responses": { "200": { "description": "Service catalog.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesListSuccess" }, "example": { "success": true, "data": { "items": [ { "code": "sms", "name": "SMS", "description": "Mensajería de texto", "icon": "chat", "enabled": true } ] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-02T19:43:59+00:00", "responseTimeMs": 4.1 } } } } }, "401": { "description": "Invalid or missing credentials.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AuthRequired": { "$ref": "#/components/examples/AuthRequired" }, "AuthInvalidKey": { "$ref": "#/components/examples/AuthInvalidKey" } } } } }, "403": { "description": "The organization cannot run the request.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "AccountNotActive": { "$ref": "#/components/examples/AccountNotActive" }, "AccountBlocked": { "$ref": "#/components/examples/AccountBlocked" } } } } }, "429": { "description": "Request limit exceeded.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "RateTpsExceeded": { "$ref": "#/components/examples/RateTpsExceeded" } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your API key in the `Authorization` header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nAPI keys are shown only at creation time. Store them in a secret manager." } }, "schemas": { "Envelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "success", "meta" ], "description": "The part shared by every response: `success` and `meta` are always there, on success and on error." }, "Meta": { "type": "object", "properties": { "requestId": { "type": "string", "example": "b9b1704baffab21150213c02fd853975", "description": "Unique request identifier. Quote it when contacting support." }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-06-04T19:43:59+00:00", "description": "Date and time the response was built (ISO 8601 with offset)." }, "responseTimeMs": { "type": "number", "example": 4.24, "description": "Time (ms) the server took to process the request." }, "warnings": { "type": "object", "additionalProperties": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "description": "Non-fatal warnings, keyed by name. Present only when there is at least one." } }, "required": [ "requestId", "timestamp", "responseTimeMs" ], "description": "Response metadata." }, "Error": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_REQUIRED", "description": "Stable UPPER_SNAKE_CASE identifier. Clients branch on this value." }, "legacyCode": { "type": "integer", "example": 40002, "description": "Legacy v5 numeric code, only when a bridge exists. Omitted for codes born in v6." }, "type": { "type": "string", "format": "uri", "example": "https://developers.hablame.co/docs/v6/errors/auth-required", "description": "URL to the error documentation." }, "message": { "type": "string", "description": "Human readable text, in English. It is for the developer log, not the end user: do not parse it." }, "details": { "type": "array", "items": { "type": "object" }, "description": "Structured context (validation issues, affected resource). Empty array when there is no extra context." } }, "required": [ "code", "type", "message", "details" ] }, "ErrorEnvelope": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "success", "error" ] } ], "description": "Error response. Every 4xx or 5xx response has this shape." }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer", "description": "How many items this page carries." }, "hasMore": { "type": "boolean", "description": "`true` when there are more items after this page." } }, "required": [ "limit", "offset", "returned", "hasMore" ], "description": "Limit/offset pagination. `hasMore` saves you from counting the total." }, "Country": { "type": "object", "properties": { "code": { "type": "string", "example": "CO", "description": "ISO 3166-1 alpha-2 (2 uppercase letters)." }, "code3": { "type": "string", "example": "COL", "description": "ISO 3166-1 alpha-3." }, "callingCode": { "type": "string", "example": "57", "description": "E.164 calling code, without `+`. A string so leading zeros survive." }, "mcc": { "type": "string", "example": "732", "description": "Mobile Country Code (E.212)." }, "flag": { "type": "string", "format": "uri", "description": "Flag URL (SVG)." }, "names": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Country name per language (`en`, `es`). Present only when `?lang` is NOT sent; a language with no name loaded is absent." }, "name": { "type": "string", "description": "Country name in the requested `lang`. Present only when `?lang` is sent." } }, "required": [ "code", "code3", "callingCode", "mcc", "flag" ] }, "NumberInsightCountry": { "type": "object", "properties": { "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "callingCode": { "type": "string", "description": "E.164 calling code, without `+`." }, "name": { "type": "string" }, "mcc": { "type": "string", "description": "Mobile Country Code (E.212)." } }, "required": [ "iso2", "callingCode", "name", "mcc" ] }, "NumberInsightOperator": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ], "description": "Commercial brand. `null` for international numbers." }, "mnc": { "type": [ "string", "null" ], "description": "Mobile Network Code. Always `null` when the line is neither `mobile` nor `m2m`." }, "nrn": { "type": [ "string", "null" ], "description": "Routing number (Colombia). `null` for international numbers." } }, "required": [ "name", "brand", "mnc", "nrn" ] }, "NumberInsight": { "type": "object", "properties": { "phoneNumber": { "type": "object", "properties": { "e164": { "type": [ "string", "null" ], "description": "E.164 form, with `+`." }, "national": { "type": [ "string", "null" ] }, "raw": { "type": "string", "description": "The number exactly as you sent it." } }, "required": [ "e164", "national", "raw" ] }, "valid": { "type": "boolean" }, "country": { "oneOf": [ { "$ref": "#/components/schemas/NumberInsightCountry" }, { "type": "null" } ] }, "lineType": { "type": [ "string", "null" ], "description": "Line type (`mobile`, `landline`, `m2m`…). `null` when it could not be determined." }, "numberType": { "type": [ "string", "null" ] }, "ported": { "type": [ "boolean", "null" ], "description": "Whether the number was ported. Colombia only; `null` for international numbers." }, "operator": { "oneOf": [ { "$ref": "#/components/schemas/NumberInsightOperator" }, { "type": "null" } ] }, "area": { "type": [ "object", "null" ], "properties": { "region": { "type": [ "string", "null" ] }, "municipality": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "daneCode": { "type": [ "string", "null" ], "description": "DANE municipality code. Only filled for Colombian landline numbering." } }, "required": [ "region", "municipality", "department", "daneCode" ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone. Only resolved for international numbers; `null` for Colombia." }, "portability": { "type": [ "object", "null" ], "properties": { "donorOperator": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] } }, "required": [ "name", "brand" ] }, "initialOperator": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] } }, "required": [ "name", "brand" ] }, "activatedAt": { "type": [ "string", "null" ], "description": "Date the porting was activated." }, "processedAt": { "type": [ "string", "null" ] }, "sourceDate": { "type": [ "string", "null" ] } }, "required": [ "donorOperator", "initialOperator", "activatedAt", "processedAt", "sourceDate" ], "description": "Portability history. Colombia only, and only when the number was ported." }, "zone": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "Stable zone for the number (operator NRN for mobile, DANE municipality for landline). `null` for international numbers and for landlines with no DANE." } }, "required": [ "phoneNumber", "valid", "country", "lineType", "numberType", "ported", "operator", "area", "timezone", "portability", "zone" ] }, "Link": { "type": "object", "properties": { "id": { "type": "integer", "description": "Stable numeric link id." }, "code": { "type": "string", "description": "Short code or alias (lowercase). Unique per domain." }, "domain": { "type": "string" }, "shortUrl": { "type": "string", "format": "uri", "description": "Full short URL (`https://{domain}/{code}`)." }, "longUrl": { "type": "string", "format": "uri", "description": "Destination URL." }, "alias": { "type": "boolean", "description": "`true` when the code was chosen by the user. Only travels in the detail: the list response omits this field." }, "active": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "clicks": { "type": "integer", "description": "Total visits (denormalized; refreshed by the drain cron)." }, "uniqueClicks": { "type": "integer" }, "lastClickAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "code", "domain", "shortUrl", "longUrl", "active", "createdAt", "clicks", "uniqueClicks" ] }, "Domain": { "type": "object", "properties": { "domain": { "type": "string" }, "isDefault": { "type": "boolean" }, "verified": { "type": "boolean" }, "global": { "type": "boolean", "description": "`true` for platform-wide domains, `false` for your account own domains." } }, "required": [ "domain", "isDefault", "verified", "global" ] }, "Voice": { "type": "object", "properties": { "code": { "type": "string", "description": "Voice code; this is what you send in `voice`." }, "name": { "type": "string" }, "language": { "type": "string", "example": "es-US", "description": "Language and region (BCP-47)." }, "accent": { "type": "string" }, "gender": { "type": "string", "enum": [ "female", "male" ] }, "tier": { "type": "string", "enum": [ "basic", "intermediate", "advanced" ] }, "sampleRate": { "type": "integer", "description": "Sample rate in Hz." } }, "required": [ "code", "name", "language", "accent", "gender", "tier", "sampleRate" ] }, "CallAttempt": { "type": "object", "properties": { "attempt": { "type": "integer", "description": "Attempt number, starting at 1." }, "status": { "type": "string", "enum": [ "originating", "answered", "completed", "busy", "rejected", "no_answer", "failed" ], "description": "Attempt status. `originating` and `answered` are transient." }, "answered": { "type": "boolean" }, "audioPlayed": { "type": "boolean" }, "durationTotal": { "type": [ "integer", "null" ], "description": "Total attempt duration, in seconds." }, "durationAir": { "type": [ "integer", "null" ], "description": "Talk-time duration, in seconds." }, "hangupCause": { "type": [ "integer", "null" ], "description": "Hangup cause code (SIP/Asterisk)." }, "causeText": { "type": [ "string", "null" ] }, "recorded": { "type": "boolean" }, "dtmf": { "type": [ "string", "null" ], "description": "Digits pressed by the person who answered." }, "startedAt": { "type": [ "string", "null" ], "example": "2026-06-23 15:04:06", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." }, "answeredAt": { "type": [ "string", "null" ], "example": "2026-06-23 15:04:06", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." }, "endedAt": { "type": [ "string", "null" ], "example": "2026-06-23 15:04:06", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "attempt", "status", "answered", "audioPlayed", "durationTotal", "durationAir", "hangupCause", "causeText", "recorded", "dtmf", "startedAt", "answeredAt", "endedAt" ] }, "Call": { "type": "object", "properties": { "id": { "type": "string", "description": "Call identifier (`cb_…`)." }, "to": { "type": "string", "description": "Destination in international format, digits only." }, "clientReference": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "success", "no_answer", "busy", "failed", "rejected", "voicemail", "canceled" ], "description": "Consolidated call status." }, "attemptsCount": { "type": "integer" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/CallAttempt" } }, "createdAt": { "type": "string", "description": "Creation date and time, as stored by the database." } }, "required": [ "id", "to", "clientReference", "status", "attemptsCount", "attempts", "createdAt" ] }, "CallAudio": { "type": "object", "properties": { "id": { "type": "string", "description": "Audio identifier (ULID)." }, "name": { "type": [ "string", "null" ] }, "originalName": { "type": [ "string", "null" ] }, "format": { "type": "string", "enum": [ "wav", "mp3", "ogg", "m4a" ], "description": "Format of the file you uploaded (not the internal normalized one)." }, "durationMs": { "type": [ "integer", "null" ] }, "sizeBytes": { "type": "integer", "description": "Size of the normalized audio." }, "createdAt": { "type": "string", "description": "Creation date and time, as stored by the database." } }, "required": [ "id", "name", "originalName", "format", "durationMs", "sizeBytes", "createdAt" ] }, "Payment": { "type": "object", "properties": { "reference": { "type": "string", "description": "Payment reference." }, "kind": { "type": "string", "enum": [ "recharge", "invoice_payment" ], "description": "Prepaid top-up or postpaid invoice payment." }, "amount": { "type": "string", "example": "108500.000000", "description": "Decimal amount with 6 decimals, in the account currency." }, "currency": { "type": "string" }, "status": { "type": "string", "description": "Payment status (`approved`, `pending`…)." }, "method": { "type": "string" }, "processor": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "example": "2026-05-18 12:30:00", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." }, "approvedAt": { "type": [ "string", "null" ], "example": "2026-05-18 12:30:00", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." }, "expiresAt": { "type": [ "string", "null" ], "example": "2026-05-18 12:30:00", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "reference", "kind", "amount", "currency", "status", "method", "processor", "createdAt", "approvedAt", "expiresAt" ] }, "Adjustment": { "type": "object", "properties": { "reference": { "type": "string" }, "direction": { "type": "string", "description": "Adjustment direction (`debit`, `credit`)." }, "amount": { "type": "string", "example": "108500.000000", "description": "Decimal amount with 6 decimals, in the account currency." }, "currency": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date", "description": "Date the adjustment takes effect (`YYYY-MM-DD`)." }, "reason": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "example": "2026-05-18 12:30:00", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "reference", "direction", "amount", "currency", "category", "status", "effectiveDate", "reason", "createdAt" ] }, "SpendLimit": { "type": "object", "properties": { "scopeType": { "type": "string", "description": "Limit scope (`org`, `cost_center`, `api_key`, `service`, `user`)." }, "scopeRef": { "type": "string", "description": "Identifier within the scope." }, "amount": { "type": "string", "example": "108500.000000", "description": "Decimal amount with 6 decimals, in the account currency." }, "period": { "type": "string", "description": "Limit periodicity (e.g. `monthly`)." }, "thresholds": { "type": "array", "items": { "type": "number" }, "description": "Consumption percentages at which an alert fires." } }, "required": [ "scopeType", "scopeRef", "amount", "period", "thresholds" ] }, "UsageScope": { "type": "object", "properties": { "scopeType": { "type": "string" }, "scopeRef": { "type": "string" }, "consumed": { "type": "string", "example": "108500.000000", "description": "Decimal amount with 6 decimals, in the account currency." } }, "required": [ "scopeType", "scopeRef", "consumed" ] }, "CostCenter": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "code", "name", "status", "isDefault" ] }, "AccountUser": { "type": "object", "properties": { "userId": { "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "User roles. A user can hold more than one." }, "costCenterId": { "type": "integer" }, "status": { "type": "string" }, "joinedAt": { "type": [ "string", "null" ], "example": "2026-05-14 11:31:56", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." }, "lastUsedAt": { "type": [ "string", "null" ], "example": "2026-05-14 11:31:56", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "userId", "firstName", "lastName", "email", "roles", "costCenterId", "status", "joinedAt", "lastUsedAt" ], "description": "Organization member. Contains personal data." }, "StatusComponent": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded", "partial_outage", "major_outage", "maintenance", "down", "unknown" ] } }, "required": [ "name", "status" ] }, "Service": { "type": "object", "properties": { "code": { "type": "string", "description": "Service code (`sms`, `tts`…)." }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "enabled": { "type": "boolean", "description": "`true` when this account has access to the service." } }, "required": [ "code", "name", "description", "icon", "enabled" ] }, "PingSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "pong": { "type": "boolean", "const": true, "description": "Always `true` when the caller is correctly authenticated." }, "apiVersion": { "type": "string", "const": "v6", "description": "API version that served the request." }, "client": { "type": "object", "properties": { "ip": { "type": "string", "example": "203.0.113.45", "description": "Public IP the call originated from." } }, "required": [ "ip" ], "description": "Caller facts the API observes." } }, "required": [ "pong", "apiVersion", "client" ] } } } ] }, "CountriesListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } ] }, "CountrySingleSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Country" } } } ] }, "NumberInsightSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/NumberInsight" } } } ] }, "NumberInsightBatchSyncSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NumberInsight" }, "description": "One result per submitted number, in the same order (duplicates are resolved again)." } }, "required": [ "results" ] } } } ] }, "NumberInsightBatchQueuedSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "queued" }, "count": { "type": "integer", "description": "Numbers accepted into the job." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the job and its result are purged." } }, "required": [ "jobId", "status", "count", "expiresAt" ] } } } ] }, "NumberInsightBatchJobSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "processing", "done", "failed" ] }, "count": { "type": "integer" }, "processed": { "type": "integer", "description": "Numbers resolved so far." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "download": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "format": { "type": "string", "example": "ndjson" } }, "required": [ "url", "format" ], "description": "Only when `status` is `done` and the file is still available. The URL is signed and temporary." }, "error": { "type": "string", "description": "Failure reason. Only when `status` is `failed`. It is a string inside `data`, not the error envelope." } }, "required": [ "jobId", "status", "count", "processed", "createdAt", "expiresAt" ] } } } ] }, "LinkSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Link" } } } ] }, "LinkListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Link" }, "description": "Links on this page. List rows do not carry `alias`." }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "perPage", "total", "hasMore" ] } } } ] }, "DomainsListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } ] }, "DeletedSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "string", "description": "Code of the deleted link." }, "domain": { "type": "string" } }, "required": [ "deleted", "domain" ] } } } ] }, "LinkStatsSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "domain": { "type": "string" }, "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "granularity": { "type": "string", "enum": [ "hour", "day" ] } }, "required": [ "from", "to", "granularity" ] }, "totals": { "type": "object", "properties": { "clicks": { "type": "integer" }, "uniqueClicks": { "type": "integer" }, "firstClickAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastClickAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "clicks", "uniqueClicks", "firstClickAt", "lastClickAt" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "example": "2026-05-04", "description": "Bucket stamp in `America/Bogota`: `YYYY-MM-DD` with `day` granularity, `YYYY-MM-DD HH:00:00` (local time, no zone) with `hour` granularity." }, "clicks": { "type": "integer" }, "uniqueClicks": { "type": "integer" } }, "required": [ "ts", "clicks", "uniqueClicks" ] } }, "breakdowns": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Bucket value, or `__other` for the long tail beyond the top-N." }, "clicks": { "type": "integer" } }, "required": [ "key", "clicks" ] } }, "description": "One top-N array per dimension requested in `dimensions`." } }, "required": [ "code", "domain", "range", "totals", "series", "breakdowns" ] } } } ] }, "TtsSynthesizeSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Synthesis identifier (ULID)." }, "status": { "type": "string", "const": "completed", "description": "Always `completed`: synthesis is synchronous, a failure returns an HTTP error." }, "cached": { "type": "boolean", "description": "`true` when an already generated audio was reused." }, "charCount": { "type": "integer" }, "durationMs": { "type": [ "integer", "null" ] }, "voice": { "type": "string", "description": "Catalog voice code that was used." }, "cost": { "type": "string", "example": "12.500000", "description": "Generation cost: decimal with 6 decimals, as a string." }, "currency": { "type": "string" }, "audioUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Signed, temporary audio URL. `null` when it could not be signed." } }, "required": [ "id", "status", "cached", "charCount", "durationMs", "voice", "cost", "currency", "audioUrl" ] } } } ] }, "TtsSynthesisSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "There are no intermediate states: synthesis is synchronous." }, "cached": { "type": "boolean" }, "charCount": { "type": "integer" }, "durationMs": { "type": [ "integer", "null" ] }, "language": { "type": "string", "example": "es-US" }, "voice": { "type": [ "string", "null" ] }, "tier": { "type": "string", "enum": [ "basic", "intermediate", "advanced" ] }, "cost": { "type": "string", "example": "12.500000", "description": "Decimal with 6 decimals, as a string." }, "currency": { "type": [ "string", "null" ] }, "audioUrl": { "type": [ "string", "null" ], "format": "uri" }, "reference": { "type": [ "string", "null" ], "description": "External reference of the record. Always `null` for syntheses created through this API." }, "errorCode": { "type": [ "string", "null" ], "description": "Failure reason when `status` is `failed`. Not a closed set: it can carry provider text." }, "createdAt": { "type": "string", "example": "2026-06-23 15:04:05", "description": "UTC date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "id", "status", "cached", "charCount", "durationMs", "language", "voice", "tier", "cost", "currency", "audioUrl", "reference", "errorCode", "createdAt" ] } } } ] }, "VoicesListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } } }, "required": [ "voices" ] } } } ] }, "CallQueuedSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Call identifier (`cb_…`); use it to look the call up." }, "to": { "type": "string" }, "status": { "type": "string", "const": "queued", "description": "Always `queued`: the call has just entered the queue." }, "clientReference": { "type": [ "string", "null" ] } }, "required": [ "id", "to", "status", "clientReference" ] } } } ] }, "AudioCallQueuedSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "to": { "type": "string" }, "status": { "type": "string", "const": "queued" }, "audioId": { "type": "string", "description": "Audio that will be played: the one you uploaded or the `audioId` you sent." }, "clientReference": { "type": [ "string", "null" ] } }, "required": [ "id", "to", "status", "audioId", "clientReference" ] } } } ] }, "CallSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/Call" } } } ] }, "AudioUploadSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Audio identifier; this is what you send as `audioId`." }, "durationMs": { "type": [ "integer", "null" ] }, "format": { "type": "string", "enum": [ "wav", "mp3", "ogg", "m4a" ], "description": "Format of the file you uploaded." }, "sizeBytes": { "type": "integer", "description": "Size of the normalized audio." }, "cached": { "type": "boolean", "description": "`true` when the audio already existed and was reused instead of creating another." } }, "required": [ "id", "durationMs", "format", "sizeBytes", "cached" ] } } } ] }, "AudiosListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "audios": { "type": "array", "items": { "$ref": "#/components/schemas/CallAudio" } } }, "required": [ "audios" ] } } } ] }, "BillingSummarySuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "integer" }, "displayName": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217 (COP, USD, EUR)." }, "status": { "type": "string" } }, "required": [ "id", "displayName", "currency", "status" ] }, "billing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "currency": { "type": "string" }, "period": { "type": "string", "example": "2026-06", "description": "Calendar month `YYYY-MM`." }, "available": { "type": "string", "example": "108500.000000", "description": "Available: prepaid `balance − consumed`; postpaid `creditLimit − consumed`." }, "balance": { "type": "string", "example": "108500.000000", "description": "Consolidated credit side (top-ups ± adjustments, carried across months). Prepaid." }, "consumed": { "type": "string", "example": "108500.000000", "description": "Period consumption (consolidated + what is live so far)." }, "reserve": { "type": "string", "example": "108500.000000", "description": "Prepaid safety reserve." }, "creditLimit": { "type": "string", "example": "108500.000000", "description": "Monthly credit cap (postpaid; `0.000000` in prepaid)." } }, "required": [ "mode", "currency", "period", "available", "balance", "consumed", "reserve", "creditLimit" ], "description": "Balance summary. Every amount is a decimal string with 6 decimals, in `currency`." } }, "required": [ "account", "billing" ] } } } ] }, "UsageSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-06", "description": "Period `YYYY-MM`." }, "total": { "type": "string", "example": "108500.000000", "description": "Grand total for the period (the `org:0` usage)." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/UsageScope" }, "description": "Breakdown by scope. May come back empty." } }, "required": [ "period", "total", "scopes" ] } } } ] }, "PaymentsListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ] } } } ] }, "AdjustmentsListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ] } } } ] }, "LimitsListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpendLimit" } } }, "required": [ "items" ] } } } ] }, "OrganizationSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "displayName": { "type": "string" }, "currency": { "type": "string", "description": "ISO 4217." }, "billingMode": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "status": { "type": "string" }, "blocks": { "type": "object", "properties": { "general": { "type": "boolean" }, "collections": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [ "general", "collections", "security" ], "description": "Active blocks on the organization." }, "onboardedAt": { "type": [ "string", "null" ], "example": "2026-05-14 11:31:56", "description": "Date and time as `YYYY-MM-DD HH:MM:SS` (no zone; not ISO-8601)." } }, "required": [ "id", "displayName", "currency", "billingMode", "status", "blocks", "onboardedAt" ] } } } ] }, "CostCentersListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CostCenter" } } }, "required": [ "items" ] } } } ] }, "UsersListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccountUser" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "items", "pagination" ] } } } ] }, "PlatformStatusSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "partial_outage", "major_outage", "maintenance", "down", "unknown" ], "description": "Aggregated platform status." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last sample was taken. `null` while there is no data." }, "stale": { "type": "boolean", "description": "`true` when the data is stale and could not be refreshed." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/StatusComponent" } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "description": "Text from the status provider, not normalized." }, "startedAt": { "type": "string", "description": "Text from the status provider; the format is not guaranteed." } }, "required": [ "name", "status", "startedAt" ] } }, "maintenance": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "startsAt": { "type": "string", "description": "Text from the status provider; the format is not guaranteed." }, "endsAt": { "type": "string", "description": "Text from the status provider; the format is not guaranteed." } }, "required": [ "name", "startsAt", "endsAt" ] } } }, "required": [ "status", "updatedAt", "stale", "components", "incidents", "maintenance" ] } } } ] }, "ServicesListSuccess": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } }, "required": [ "items" ] } } } ] } }, "headers": { "RateLimit-Limit": { "description": "Quota for the active window.", "schema": { "type": "integer", "example": 20 } }, "RateLimit-Remaining": { "description": "Requests left in the active window.", "schema": { "type": "integer", "example": 19 } }, "RateLimit-Reset": { "description": "Seconds until the window resets. It is NOT a Unix timestamp.", "schema": { "type": "integer", "example": 31 } }, "RateLimit-Policy": { "description": "Active per-endpoint limit policy.", "schema": { "type": "string", "example": "20;w=60;name=\"endpoint\"" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 31 } }, "Idempotency-Status": { "description": "Only when you sent `Idempotency-Key`: `created` when the operation ran, `replayed` when the stored response was returned.", "schema": { "type": "string", "enum": [ "created", "replayed" ] } }, "Idempotency-Replayed": { "description": "Present and `true` only when the response is a stored replay.", "schema": { "type": "string", "enum": [ "true" ] } } }, "examples": { "AuthRequired": { "summary": "No Bearer token was sent, and every call requires one. (AUTH_REQUIRED)", "value": { "success": false, "error": { "code": "AUTH_REQUIRED", "legacyCode": 40002, "type": "https://developers.hablame.co/docs/v6/errors/auth-required", "message": "Authentication is required. Send your API key as `Authorization: Bearer `.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AuthInvalidKey": { "summary": "The API key is not recognized: wrong format, revoked or expired. (AUTH_INVALID_KEY)", "value": { "success": false, "error": { "code": "AUTH_INVALID_KEY", "legacyCode": 40003, "type": "https://developers.hablame.co/docs/v6/errors/auth-invalid-key", "message": "The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AuthCostCenterDisabled": { "summary": "The cost center bound to the key is disabled. (AUTH_COST_CENTER_DISABLED)", "value": { "success": false, "error": { "code": "AUTH_COST_CENTER_DISABLED", "type": "https://developers.hablame.co/docs/v6/errors/auth-cost-center-disabled", "message": "The cost center linked to this API key is disabled.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AuthServiceNotAllowed": { "summary": "The key is not allowed to use the service behind this endpoint. (AUTH_SERVICE_NOT_ALLOWED)", "value": { "success": false, "error": { "code": "AUTH_SERVICE_NOT_ALLOWED", "type": "https://developers.hablame.co/docs/v6/errors/auth-service-not-allowed", "message": "This API key is not authorized to use the requested service.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AuthSourceIpUnknown": { "summary": "Reserved: kept only as a bridge from v5. (AUTH_SOURCE_IP_UNKNOWN)", "value": { "success": false, "error": { "code": "AUTH_SOURCE_IP_UNKNOWN", "legacyCode": 40015, "type": "https://developers.hablame.co/docs/v6/errors/auth-source-ip-unknown", "message": "Internal error has occurred, the source IP could not be discovered.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AccountNotActive": { "summary": "Your organization is suspended or closed. (ACCOUNT_NOT_ACTIVE)", "value": { "success": false, "error": { "code": "ACCOUNT_NOT_ACTIVE", "type": "https://developers.hablame.co/docs/v6/errors/account-not-active", "message": "The organization associated with this API key is not active. Please contact support.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AccountBlocked": { "summary": "A full block is active: every call is rejected. (ACCOUNT_BLOCKED)", "value": { "success": false, "error": { "code": "ACCOUNT_BLOCKED", "type": "https://developers.hablame.co/docs/v6/errors/account-blocked", "message": "The organization is currently blocked. Please contact support.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AccountReadOnly": { "summary": "Read-only mode: only GET, HEAD and OPTIONS pass. (ACCOUNT_READ_ONLY)", "value": { "success": false, "error": { "code": "ACCOUNT_READ_ONLY", "type": "https://developers.hablame.co/docs/v6/errors/account-read-only", "message": "The organization is in read-only mode. Only safe HTTP methods (GET, HEAD, OPTIONS) are permitted.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AccountConfigNotFound": { "summary": "We could not load the organization behind your key. (ACCOUNT_CONFIG_NOT_FOUND)", "value": { "success": false, "error": { "code": "ACCOUNT_CONFIG_NOT_FOUND", "legacyCode": 4002, "type": "https://developers.hablame.co/docs/v6/errors/account-config-not-found", "message": "Organization configuration could not be loaded. Please contact support.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "RateDdosExceeded": { "summary": "Unusually high volume from your source IP. (RATE_DDOS_EXCEEDED)", "value": { "success": false, "error": { "code": "RATE_DDOS_EXCEEDED", "legacyCode": 40001, "type": "https://developers.hablame.co/docs/v6/errors/rate-ddos-exceeded", "message": "Too many requests from this IP within a short window. Please wait before retrying.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "RateTpsExceeded": { "summary": "You exceeded your organization quota for this endpoint. (RATE_TPS_EXCEEDED)", "value": { "success": false, "error": { "code": "RATE_TPS_EXCEEDED", "legacyCode": 40001, "type": "https://developers.hablame.co/docs/v6/errors/rate-tps-exceeded", "message": "You have exceeded the allowed request rate for this endpoint. Please wait before retrying.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "IdempotencyKeyInvalid": { "summary": "The idempotency key does not match the format. (IDEMPOTENCY_KEY_INVALID)", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_INVALID", "type": "https://developers.hablame.co/docs/v6/errors/idempotency-key-invalid", "message": "The `Idempotency-Key` header is invalid. Use 1-255 characters limited to letters, digits, hyphen or underscore.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "IdempotencyInProgress": { "summary": "The first request with that key is still in progress. (IDEMPOTENCY_IN_PROGRESS)", "value": { "success": false, "error": { "code": "IDEMPOTENCY_IN_PROGRESS", "type": "https://developers.hablame.co/docs/v6/errors/idempotency-in-progress", "message": "A request with this `Idempotency-Key` is still being processed. Please retry shortly.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "IdempotencyKeyReused": { "summary": "The key already exists, but with a different body. (IDEMPOTENCY_KEY_REUSED)", "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REUSED", "type": "https://developers.hablame.co/docs/v6/errors/idempotency-key-reused", "message": "This `Idempotency-Key` was already used with a different request body. Use a new key for a different operation.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "UrlInvalid": { "summary": "The destination URL is malformed. (URL_INVALID)", "value": { "success": false, "error": { "code": "URL_INVALID", "type": "https://developers.hablame.co/docs/v6/errors/url-invalid", "message": "The destination URL is not valid. Provide an absolute `http`/`https` URL with a host.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "UrlSchemeNotAllowed": { "summary": "Only http/https destinations are allowed. (URL_SCHEME_NOT_ALLOWED)", "value": { "success": false, "error": { "code": "URL_SCHEME_NOT_ALLOWED", "type": "https://developers.hablame.co/docs/v6/errors/url-scheme-not-allowed", "message": "Only `http` and `https` destination URLs are allowed.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "UrlTooLong": { "summary": "The destination URL exceeds the maximum length. (URL_TOO_LONG)", "value": { "success": false, "error": { "code": "URL_TOO_LONG", "type": "https://developers.hablame.co/docs/v6/errors/url-too-long", "message": "The destination URL exceeds the maximum allowed length.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "UrlBlockedHost": { "summary": "The destination host is private or reserved. (URL_BLOCKED_HOST)", "value": { "success": false, "error": { "code": "URL_BLOCKED_HOST", "type": "https://developers.hablame.co/docs/v6/errors/url-blocked-host", "message": "The destination host is not allowed (private, reserved, or loopback addresses are blocked).", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AliasInvalid": { "summary": "The custom alias doesn't match the allowed format. (ALIAS_INVALID)", "value": { "success": false, "error": { "code": "ALIAS_INVALID", "type": "https://developers.hablame.co/docs/v6/errors/alias-invalid", "message": "The alias must be 3-32 characters of lowercase letters, digits, hyphen or underscore.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AliasTaken": { "summary": "The alias is already used on this domain. (ALIAS_TAKEN)", "value": { "success": false, "error": { "code": "ALIAS_TAKEN", "type": "https://developers.hablame.co/docs/v6/errors/alias-taken", "message": "That alias is already in use on this domain.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "AliasReserved": { "summary": "The alias is a reserved word. (ALIAS_RESERVED)", "value": { "success": false, "error": { "code": "ALIAS_RESERVED", "type": "https://developers.hablame.co/docs/v6/errors/alias-reserved", "message": "That alias is reserved and cannot be used.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "ExpiresAtInvalid": { "summary": "expiresAt must be a future ISO date-time. (EXPIRES_AT_INVALID)", "value": { "success": false, "error": { "code": "EXPIRES_AT_INVALID", "type": "https://developers.hablame.co/docs/v6/errors/expires-at-invalid", "message": "`expiresAt` must be a future ISO-8601 date-time.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "LinkNotFound": { "summary": "No link with that domain and code. (LINK_NOT_FOUND)", "value": { "success": false, "error": { "code": "LINK_NOT_FOUND", "type": "https://developers.hablame.co/docs/v6/errors/link-not-found", "message": "No short link was found for that domain and code.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "NothingToUpdate": { "summary": "No updatable fields were sent. (NOTHING_TO_UPDATE)", "value": { "success": false, "error": { "code": "NOTHING_TO_UPDATE", "type": "https://developers.hablame.co/docs/v6/errors/nothing-to-update", "message": "No updatable fields were provided.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "CodeGenerationFailed": { "summary": "Could not allocate a unique code. (CODE_GENERATION_FAILED)", "value": { "success": false, "error": { "code": "CODE_GENERATION_FAILED", "type": "https://developers.hablame.co/docs/v6/errors/code-generation-failed", "message": "Could not generate a unique short code. Please retry.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "StatsRangeInvalid": { "summary": "The stats range or granularity is invalid. (STATS_RANGE_INVALID)", "value": { "success": false, "error": { "code": "STATS_RANGE_INVALID", "type": "https://developers.hablame.co/docs/v6/errors/stats-range-invalid", "message": "The requested statistics range or granularity is invalid.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "DomainNotAllowed": { "summary": "The chosen domain isn't available to your account. (DOMAIN_NOT_ALLOWED)", "value": { "success": false, "error": { "code": "DOMAIN_NOT_ALLOWED", "type": "https://developers.hablame.co/docs/v6/errors/domain-not-allowed", "message": "The requested domain is not available for this account.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "CountryNotFound": { "summary": "No country exists with that code. (COUNTRY_NOT_FOUND)", "value": { "success": false, "error": { "code": "COUNTRY_NOT_FOUND", "type": "https://developers.hablame.co/docs/v6/errors/country-not-found", "message": "No country was found with the supplied code. Use the ISO 3166-1 alpha-2 form (e.g. `CO`, `US`).", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "InfraDbConnectionError": { "summary": "An internal service was momentarily unreachable. (INFRA_DB_CONNECTION_ERROR)", "value": { "success": false, "error": { "code": "INFRA_DB_CONNECTION_ERROR", "legacyCode": 40011, "type": "https://developers.hablame.co/docs/v6/errors/infra-db-connection-error", "message": "Could not establish connection to the database. Please retry; if the error persists, contact support.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "InfraCacheUnavailable": { "summary": "An internal component is temporarily unavailable. (INFRA_CACHE_UNAVAILABLE)", "value": { "success": false, "error": { "code": "INFRA_CACHE_UNAVAILABLE", "type": "https://developers.hablame.co/docs/v6/errors/infra-cache-unavailable", "message": "A backing cache is temporarily unavailable. Please retry shortly.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "InfraDbQueryTimeout": { "summary": "An internal query took too long and was cut off. (INFRA_DB_QUERY_TIMEOUT)", "value": { "success": false, "error": { "code": "INFRA_DB_QUERY_TIMEOUT", "type": "https://developers.hablame.co/docs/v6/errors/infra-db-query-timeout", "message": "The upstream database took too long to respond. Please retry shortly.", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } }, "InternalServerError": { "summary": "Something went wrong on our side. (INTERNAL_SERVER_ERROR)", "value": { "success": false, "error": { "code": "INTERNAL_SERVER_ERROR", "type": "https://developers.hablame.co/docs/v6/errors/internal-server-error", "message": "Internal Server Error", "details": [] }, "meta": { "requestId": "b9b1704baffab21150213c02fd853975", "timestamp": "2026-06-04T19:43:59+00:00", "responseTimeMs": 0.8 } } } }, "x-errorCatalog": [ { "code": "AUTH_REQUIRED", "status": 401, "domain": "auth", "legacyCode": 40002, "summary": "No Bearer token was sent, and every call requires one.", "url": "https://developers.hablame.co/en/docs/errors#auth-required" }, { "code": "AUTH_INVALID_KEY", "status": 401, "domain": "auth", "legacyCode": 40003, "summary": "The API key is not recognized: wrong format, revoked or expired.", "url": "https://developers.hablame.co/en/docs/errors#auth-invalid-key" }, { "code": "AUTH_COST_CENTER_DISABLED", "status": 401, "domain": "auth", "summary": "The cost center bound to the key is disabled.", "url": "https://developers.hablame.co/en/docs/errors#auth-cost-center-disabled" }, { "code": "AUTH_SERVICE_NOT_ALLOWED", "status": 401, "domain": "auth", "summary": "The key is not allowed to use the service behind this endpoint.", "url": "https://developers.hablame.co/en/docs/errors#auth-service-not-allowed" }, { "code": "AUTH_SOURCE_IP_UNKNOWN", "status": 400, "domain": "auth", "legacyCode": 40015, "summary": "Reserved: kept only as a bridge from v5.", "url": "https://developers.hablame.co/en/docs/errors#auth-source-ip-unknown" }, { "code": "ACCOUNT_NOT_ACTIVE", "status": 403, "domain": "account", "summary": "Your organization is suspended or closed.", "url": "https://developers.hablame.co/en/docs/errors#account-not-active" }, { "code": "ACCOUNT_BLOCKED", "status": 403, "domain": "account", "summary": "A full block is active: every call is rejected.", "url": "https://developers.hablame.co/en/docs/errors#account-blocked" }, { "code": "ACCOUNT_READ_ONLY", "status": 403, "domain": "account", "summary": "Read-only mode: only GET, HEAD and OPTIONS pass.", "url": "https://developers.hablame.co/en/docs/errors#account-read-only" }, { "code": "ACCOUNT_CONFIG_NOT_FOUND", "status": 403, "domain": "account", "legacyCode": 4002, "summary": "We could not load the organization behind your key.", "url": "https://developers.hablame.co/en/docs/errors#account-config-not-found" }, { "code": "RATE_DDOS_EXCEEDED", "status": 429, "domain": "rate", "legacyCode": 40001, "summary": "Unusually high volume from your source IP.", "url": "https://developers.hablame.co/en/docs/errors#rate-ddos-exceeded" }, { "code": "RATE_TPS_EXCEEDED", "status": 429, "domain": "rate", "legacyCode": 40001, "summary": "You exceeded your organization quota for this endpoint.", "url": "https://developers.hablame.co/en/docs/errors#rate-tps-exceeded" }, { "code": "IDEMPOTENCY_KEY_INVALID", "status": 400, "domain": "idempotency", "summary": "The idempotency key does not match the format.", "url": "https://developers.hablame.co/en/docs/errors#idempotency-key-invalid" }, { "code": "IDEMPOTENCY_IN_PROGRESS", "status": 409, "domain": "idempotency", "summary": "The first request with that key is still in progress.", "url": "https://developers.hablame.co/en/docs/errors#idempotency-in-progress" }, { "code": "IDEMPOTENCY_KEY_REUSED", "status": 422, "domain": "idempotency", "summary": "The key already exists, but with a different body.", "url": "https://developers.hablame.co/en/docs/errors#idempotency-key-reused" }, { "code": "URL_INVALID", "status": 400, "domain": "urlshortener", "summary": "The destination URL is malformed.", "url": "https://developers.hablame.co/en/docs/errors#url-invalid" }, { "code": "URL_SCHEME_NOT_ALLOWED", "status": 400, "domain": "urlshortener", "summary": "Only http/https destinations are allowed.", "url": "https://developers.hablame.co/en/docs/errors#url-scheme-not-allowed" }, { "code": "URL_TOO_LONG", "status": 400, "domain": "urlshortener", "summary": "The destination URL exceeds the maximum length.", "url": "https://developers.hablame.co/en/docs/errors#url-too-long" }, { "code": "URL_BLOCKED_HOST", "status": 400, "domain": "urlshortener", "summary": "The destination host is private or reserved.", "url": "https://developers.hablame.co/en/docs/errors#url-blocked-host" }, { "code": "ALIAS_INVALID", "status": 400, "domain": "urlshortener", "summary": "The custom alias doesn't match the allowed format.", "url": "https://developers.hablame.co/en/docs/errors#alias-invalid" }, { "code": "ALIAS_TAKEN", "status": 409, "domain": "urlshortener", "summary": "The alias is already used on this domain.", "url": "https://developers.hablame.co/en/docs/errors#alias-taken" }, { "code": "ALIAS_RESERVED", "status": 409, "domain": "urlshortener", "summary": "The alias is a reserved word.", "url": "https://developers.hablame.co/en/docs/errors#alias-reserved" }, { "code": "EXPIRES_AT_INVALID", "status": 400, "domain": "urlshortener", "summary": "expiresAt must be a future ISO date-time.", "url": "https://developers.hablame.co/en/docs/errors#expires-at-invalid" }, { "code": "LINK_NOT_FOUND", "status": 404, "domain": "urlshortener", "summary": "No link with that domain and code.", "url": "https://developers.hablame.co/en/docs/errors#link-not-found" }, { "code": "NOTHING_TO_UPDATE", "status": 400, "domain": "urlshortener", "summary": "No updatable fields were sent.", "url": "https://developers.hablame.co/en/docs/errors#nothing-to-update" }, { "code": "CODE_GENERATION_FAILED", "status": 500, "domain": "urlshortener", "summary": "Could not allocate a unique code.", "url": "https://developers.hablame.co/en/docs/errors#code-generation-failed" }, { "code": "STATS_RANGE_INVALID", "status": 400, "domain": "urlshortener", "summary": "The stats range or granularity is invalid.", "url": "https://developers.hablame.co/en/docs/errors#stats-range-invalid" }, { "code": "DOMAIN_NOT_ALLOWED", "status": 400, "domain": "urlshortener", "summary": "The chosen domain isn't available to your account.", "url": "https://developers.hablame.co/en/docs/errors#domain-not-allowed" }, { "code": "COUNTRY_NOT_FOUND", "status": 404, "domain": "tools", "summary": "No country exists with that code.", "url": "https://developers.hablame.co/en/docs/errors#country-not-found" }, { "code": "INFRA_DB_CONNECTION_ERROR", "status": 503, "domain": "infra", "legacyCode": 40011, "summary": "An internal service was momentarily unreachable.", "url": "https://developers.hablame.co/en/docs/errors#infra-db-connection-error" }, { "code": "INFRA_CACHE_UNAVAILABLE", "status": 503, "domain": "infra", "summary": "An internal component is temporarily unavailable.", "url": "https://developers.hablame.co/en/docs/errors#infra-cache-unavailable" }, { "code": "INFRA_DB_QUERY_TIMEOUT", "status": 504, "domain": "infra", "summary": "An internal query took too long and was cut off.", "url": "https://developers.hablame.co/en/docs/errors#infra-db-query-timeout" }, { "code": "BAD_REQUEST", "status": 400, "domain": "generic", "summary": "We could not parse your request.", "url": "https://developers.hablame.co/en/docs/errors#bad-request" }, { "code": "UNAUTHORIZED", "status": 401, "domain": "generic", "summary": "Generic 401: prefer the `AUTH_*` codes when present.", "url": "https://developers.hablame.co/en/docs/errors#unauthorized" }, { "code": "FORBIDDEN", "status": 403, "domain": "generic", "summary": "Generic 403: fallback when no `ACCOUNT_*` applies.", "url": "https://developers.hablame.co/en/docs/errors#forbidden" }, { "code": "NOT_FOUND", "status": 404, "domain": "generic", "summary": "The path you requested does not exist in this API.", "url": "https://developers.hablame.co/en/docs/errors#not-found" }, { "code": "METHOD_NOT_ALLOWED", "status": 405, "domain": "generic", "summary": "The path exists but does not accept this HTTP method.", "url": "https://developers.hablame.co/en/docs/errors#method-not-allowed" }, { "code": "TOO_MANY_REQUESTS", "status": 429, "domain": "generic", "summary": "Generic 429: prefer the `RATE_*` codes when present.", "url": "https://developers.hablame.co/en/docs/errors#too-many-requests" }, { "code": "INTERNAL_SERVER_ERROR", "status": 500, "domain": "generic", "summary": "Something went wrong on our side.", "url": "https://developers.hablame.co/en/docs/errors#internal-server-error" }, { "code": "SERVICE_UNAVAILABLE", "status": 503, "domain": "generic", "summary": "Generic 503: a service we depend on is not responding.", "url": "https://developers.hablame.co/en/docs/errors#service-unavailable" }, { "code": "GATEWAY_TIMEOUT", "status": 504, "domain": "generic", "summary": "Generic 504: a service we depend on took too long.", "url": "https://developers.hablame.co/en/docs/errors#gateway-timeout" } ] } }