Getting started

From zero to your first authenticated request in 30 seconds. This guide uses curl because it needs nothing installed, but the same flow works from any language.

3 min read

Prerequisites

You need three things:

An active Hablame organization.
An API key issued from the customer portal: a string that starts with hk_.
curl, or any HTTP client you prefer.

1. Issue an API key

API keys are created from the customer portal. When you create one, the portal shows you the full token only once. Copy it into a password manager or your secret store right away. Hablame stores only a hash: if you lose the original value it cannot be recovered, and you have to issue a new one.

Treat the token like a password. Never commit it to a repository, never paste it into a chat, never put it in a URL.

2. Make your first request

The utilities/ping endpoint is the simplest one. It runs the full authentication pipeline and returns what the API knows about your key, perfect to confirm everything is wired correctly before moving to a real service endpoint.

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

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

response

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

3. Read the envelope

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

4. Move to a real endpoint

Once /api/v6/utilities/ping returns 200, the rest of v6 follows the same pattern: Bearer authentication, the same envelope, the same limit headers. Browse the reference to see every endpoint, its parameters and examples, and to run requests right from the page.

Common mistakes

Symptom	Likely cause
`401 AUTH_REQUIRED`	You forgot the `Authorization` header, or used `Basic` instead of `Bearer`.
`401 AUTH_INVALID_KEY`	A typo in the token, you copied the wrong key, or the key was rotated or expired.
`404 NOT_FOUND`	Confirm you are calling `developers.hablame.co` and not a raw IP address.
`429 RATE_TPS_EXCEEDED`	You hit the endpoint quota (ping allows 20 requests per minute). Respect `Retry-After`.

Every response carries a meta.requestId. Quote it when you open a support ticket: with that id we find your exact request.

Next steps

Authentication

Token lifecycle, rotation, and what to do if a key is compromised.

Response envelope

The full contract and how to branch your client without guessing shapes.

Usage limits

The two-layer model, the headers and the retry strategy.

Reference

Every endpoint with parameters, errors and a live Try-It panel.