Create an API key and connect your system

The API lets your system (an ERP, a spreadsheet, an n8n, Make or Zapier automation) ask Hades for what it already knows: contacts, meetings with their analysis, deals and pipelines. It is part of the Oracle plan and up. The owner or a manager creates and revokes keys, in Integrations. Each system gets its own key, and you can revoke it whenever you want.

Create the key

1. Click your photo (or your initials) at the bottom of the left menu and choose Integrations.
2. Scroll to the API and MCP section.
3. In Key name, write what it is for, for example ERP, n8n or Claude. It is only so you recognize it later.
4. Tick the extra permissions only if your system needs them (see the section below). With nothing ticked, the key only reads.
5. Click Create key.
6. The key shows up once, starting with hdk_. Click Copy, paste it somewhere safe in your system and click I've saved it.

Use the key

Send the key in the Authorization header on every request. This is the simplest check (replace YOUR-ADDRESS with the base address the screen shows for your account):

curl https://YOUR-ADDRESS/api/v1 \
  -H "Authorization: Bearer hdk_..."

The response says which company the key belongs to and what it can do. The routes that exist today:

• GET /api/v1/clientes — the contacts. Accepts busca, criado_desde, limite and pagina.
• GET /api/v1/clientes/{id} — the full record: contact data, meetings, deals and proposals.
• GET /api/v1/reunioes — the meetings with summary and outcome. Accepts desde, ate and contato_id.
• GET /api/v1/reunioes/{id} — the full analysis of one meeting.
• GET /api/v1/negocios — the deals. Accepts pipeline_id, etapa and contato_id.
• GET /api/v1/pipelines — the pipelines and the stages of each one (use it to learn the stage names).
• POST /api/v1/clientes — creates a contact (only with the write permission).
• PATCH /api/v1/negocios/{id} — changes the stage and/or the value of a deal (only with the write permission).

Lists come 50 at a time by default, and the maximum is 100 per page (use limite and pagina). Dates are YYYY-MM-DD and money comes in cents.

The key's permissions

• Read — always on. Reads contacts, meetings, deals and pipelines.
• Can read meeting transcripts — off by default. The transcript is what your customer said: turn it on only if your system needs it. Without this permission, asking for ?transcricao=1 returns a 403 error.
• Can create contacts and move deals — off by default. With it, the key creates contacts (POST /api/v1/clientes) and changes the stage or value of a deal (PATCH /api/v1/negocios/{id}). Nothing is ever deleted, and every write is logged in the Latest writes through the API and MCP list at the bottom of the section.

Creating a contact with a phone number or e-mail that already exists in your account does not create a duplicate: the response returns the contact that was already there. Moving a deal follows the same rules as the Deals screen: the stage must exist in that deal's pipeline, and a stage that records the sale on the pixel asks for the value. See the deals board.

Limits

• Up to 60 requests per minute per key (the API and MCP count together). The limit resets every minute.
• Up to 30 writes every 10 minutes per key.
• The key only sees your company. Asking for an id that belongs to another account answers "not found".
• The key never deletes anything and does not touch plans, billing or the team.

If you get an error

• 401 — the key is missing, wrong or was revoked. Check the Authorization: Bearer hdk_... header.
• 402 — the company's plan does not include the API. It is part of Oracle and up. See what each plan includes.
• 403 — the key lacks the permission this request needs (transcript or write). Create another key with the permission ticked.
• 404 — that id was not found in this account.
• 400 — a parameter is wrong; the response says which one.
• 422 — on a write: the stage does not exist in the deal's pipeline, or the stage requires a value.
• 429 — you went over the request limit. The response carries Retry-After with the seconds to wait.
• 503 — Hades could not check right now. Try again in a moment; nothing was saved.

Revoke

In Integrations, on the key's row, click Revoke and confirm. The system using that key loses access immediately, and it cannot be undone. Revoking is always possible, even if the company changes plans.

Want Hades to notify your system when something happens, without you asking? See receive notifications in your system. Want to connect an AI assistant? See connect an AI assistant (MCP).