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

# Create a link

> Make a link that lets someone call a private voice agent until it expires or runs out of calls.

Make one link per person or visitor, then send them its `url`, or put it in your page: the `url` plus `&embed=1` in an iframe, or the `token` in the widget's `data-token`. See [Private agents](https://docs.talking-avatar.dev/voice-agents/private-agents.md).

The agent should be [private](https://docs.talking-avatar.dev/voice-agents/private-agents.md#make-an-agent-private). Public agents take calls from anyone with their share link, without a token.

**Authorization** `string` *required*

`Bearer tav_…`, your API key.

**agentId** `string` *required*

The voice agent's ID.

**name** `string`

Who or what it's for, shown in the dashboard. Up to 120 characters.

**expiresAt** `string`

When it stops working, as an ISO 8601 date-time (for example `2026-11-02T09:00:00Z`). Must be in the future and at most a year away. Default: 24 hours from now.

**maxUses** `integer`

How many calls it may start, from 1 to 100,000. Use `1` for a one-time link. Default: any number until it expires.

### Response

**data** `object`

**link**

**id** `string`

The link's ID, for deleting it

**name** `string | null`

Who or what it's for

**token** `string`

The link's secret

**url** `string`

The agent's call page with the token: send this

**expires\_at** `string`

When it stops working (ISO 8601)

**max\_uses** `integer | null`

How many calls it may start; `null` for any number

**uses** `integer`

How many calls it has started (`0`)

**created\_at** `string`

When it was made (ISO 8601)

```bash cURL theme={null}
curl -X POST https://backend.talking-avatar.dev/api/talking-avatar/voice-agents/AGENT_ID/links \
  -H "Authorization: Bearer $TALKING_AVATAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Interview with Jane", "expiresAt": "2026-11-02T09:00:00Z", "maxUses": 1}'
```

```js Node.js (SDK) theme={null}
import { createAgentLink } from "@interviewflowai/talking-avatar/server";

const link = await createAgentLink({
  apiKey: process.env.TALKING_AVATAR_API_KEY,
  agentId: "AGENT_ID",
  name: "Interview with Jane",
  expiresAt: "2026-11-02T09:00:00Z",
  maxUses: 1,
});
```

```python Python theme={null}
import os, requests

response = requests.post(
    "https://backend.talking-avatar.dev/api/talking-avatar/voice-agents/AGENT_ID/links",
    headers={"Authorization": f"Bearer {os.environ['TALKING_AVATAR_API_KEY']}"},
    json={"name": "Interview with Jane", "expiresAt": "2026-11-02T09:00:00Z", "maxUses": 1},
)
response.raise_for_status()
link = response.json()["data"]
```

```json 201 theme={null}
{
  "data": {
    "id": "6f2c1b0e-4d7a-4a51-9a3e-2b8c7d1e9f40",
    "name": "Interview with Jane",
    "token": "q3N1dGh4YkVwV2Zz…",
    "url": "https://app.talking-avatar.dev/agent/AGENT_ID?token=q3N1dGh4YkVwV2Zz…",
    "expires_at": "2026-11-02T09:00:00+00:00",
    "max_uses": 1,
    "uses": 0,
    "created_at": "2026-10-26T10:15:00+00:00"
  },
  "code": 201,
  "message": "Link created"
}
```

```json 400 theme={null}
{ "code": 400, "message": "expiresAt must be in the future, and within a year" }
```

```json 404 theme={null}
{ "code": 404, "message": "Voice agent not found" }
```


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