Getting started

From zero to your first authenticated request in 30 seconds. This walk-through uses curl because it has nothing to install, but the same flow works from any language. See the reference for code samples.

Prerequisites

You need three things:

  • An active Hablame organization.
  • An API key from your organization dashboard (a string starting with hk_).
  • curl, or any HTTP client of your choice.

1. Issue an API key

API keys are minted from the Hablame dashboard. When you create a key, the dashboard shows the full token once; copy it into a password manager or secret store immediately. Hablame stores only a hash on the server; if you lose the plaintext we cannot recover it. Issue a new one.

!

Treat the token like a password. Never commit it to source control, never paste it into chat tools, never include it in URLs.

2. Make your first request

The utilities/ping endpoint is the simplest one. It runs the full auth pipeline and reports back what the API knows about your key, perfect for confirming everything is wired correctly before moving to a real module endpoint.

curl 
$ curl -H 'Authorization: Bearer hk_YOUR_API_KEY' \
       https://developers.hablame.co/api/v6/utilities/ping

A successful call returns HTTP 200 and a JSON body that looks like this:

response.json 
{
  "success": true,
  "data": {
    "pong":       true,
    "apiVersion": "v6",
    "account": { "id": 10000003, "status": "active" }
  },
  "meta": {
    "requestId":      "b9b1704baffab21150213c02fd853975",
    "responseTimeMs": 4.24
  }
}

3. Read the envelope

Every response, success or error, is wrapped in the same envelope: { success, data | error, meta }. Branch your client on success and never on HTTP status alone. The envelope guide covers the exact contract.

4. Move to a real endpoint

Once /api/v6/utilities/ping answers 200, the rest of v6 follows the same pattern: Bearer auth, same envelope, same rate-limit headers. Browse the interactive reference to see every endpoint, parameter and example payload, and to try requests directly from the page.

Common pitfalls

SymptomLikely cause
401 AUTH_REQUIRED You forgot the Authorization header, or used Basic instead of Bearer.
401 AUTH_INVALID_KEY Typo in the token, wrong key copied, or the key has been rotated/expired.
404 NOT_FOUND The Host header is not on the allowlist. Make sure you're calling developers.hablame.co, not an IP directly.
429 RATE_TPS_EXCEEDED You hit the per-endpoint quota (ping is 20 req/min). Honor Retry-After.
i

Every response carries a meta.requestId. Quote it when you open a support ticket: it lets ops jump straight to your request in the logs.

Next steps

  • Authentication: token lifecycle, rotation, and what to do if a key is compromised.
  • Response envelope: full contract and how to branch your client.
  • Rate limiting: the two-tier model, headers and backoff strategy.
  • Reference: every endpoint with a live Try-It panel.