> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 24. Public API

> Starting a call programmatically, when the trigger is an event in your CRM rather than a list.

# A call from your system: the public API

> [!NOTE]
>
> **Module goal:** start a call programmatically, when the trigger is an event in your CRM rather than a list.

![The API keys section: the key list and a quick reference on the /v1 endpoints](https://mintcdn.com/hubtalk/6Gty-jrmcpO6_h1R/images/tutorial/tut-50-api-keys_en.webp?fit=max\&auto=format\&n=6Gty-jrmcpO6_h1R\&q=85\&s=19a3bdec3546d2145490b6b492b66c0e)

API keys — no keys yet. A key's secret is shown once, on creation. Next to the list is a quick reference on the endpoints, headers and the rate limit.

The public API is for when your system initiates the call: a customer left a request on the website, a status changed in the CRM, an order arrived. The key endpoints:

| Method and path | What for |
| - | - |
| `POST /v1/calls/phone` | an outbound phone call: agent, number, variables |
| `POST /v1/calls/web` | a web call: a token for the browser or the SDK on your website |
| `GET /v1/calls` | a list of calls with filters and a cursor |
| `GET /v1/calls/{id}` | the call object: status, transcript, analytics, recording |
| `POST /v1/calls/{id}/end` | end an active call |

The key is passed in `Authorization: Bearer …`, and each key has its own requests-per-minute limit (exceeding it returns `429` with a `Retry-After` header). The `Idempotency-Key` header on call creation requests (`POST /v1/calls/phone` and `/v1/calls/web`) protects against duplicates on retries: a repeat with the same key within 24 hours does not create a second call but returns the one already created — a must if the request is sent by a queue with automatic retries.

Call variables are passed in the request body — these are the same `{{var}}` you use in the nodes. Results arrive by webhooks from [module 16](https://docs.hubtalk.ai/v4/tutorial/recording-webhooks.md), so there is no need to poll the status separately.

> [!NOTE]
>
> **A call from a website: the SDK and the widget**
>
> For web calls there is the browser SDK `@hubtalk-ai/web-sdk` on npm. Your server calls `POST /v1/calls/web` with the key, and the page passes the session it gets to the SDK — the key never reaches the browser. The package also has a ready-made widget: a button in the corner of the page and a call panel with the agent's state and a timer. Its styles apply only inside the widget and do not recolor your page.
>
> How to connect it: [Calls from your website](https://docs.hubtalk.ai/v4/web-api/web-call.md).

> [!TIP]
>
> **Show an agent without integrating anything**
>
> If the task is not "embed it in a product" but "let a person talk to the agent today", you don't need the API at all: a published agent has a **Share demo link…** item in the **⋯** menu of its row in the agent list (in the editor — **Share** in the **⋯** menu on the toolbar). It issues a [demo link](https://docs.hubtalk.ai/v4/platform/demo-links.md) with an expiry and a call cap. The recipient opens it in a browser and talks — no account and no key. This is a third kind of secret you hand over, so treat the link itself as a credential.

> [!WARNING]
>
> **Pitfall: the secret is shown once**
>
> After the creation window is closed, the secret is not shown anywhere again — only its prefix. Lost it — revoke the key and create a new one. And don't put the key in the frontend: for the browser there is the web call with a one-time token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.