---
title: "Agents API Reference | Linkbreakers"
description: "AI chat personas you build (a role, a tone, guardrails and knowledge documents) and plug into a link's Chat Bot step, where they talk to your visitors."
canonical: "https://linkbreakers.com/help/api/agents"
---

# Agents

AI chat personas you build (a role, a tone, guardrails and knowledge documents) and plug into a link's Chat Bot step, where they talk to your visitors.

10 entries on this page

## The agent object

A chat persona the workspace builds and plugs into workflow steps.

`createdAt` string (date-time) 

Read-only

When the agent was created.

`customRules` string

Free-text rules the agent never breaks, on top of the guardrails.

`emojiEnabled` boolean

Whether the agent may use emoji.

`guardrails` array of enum

The preset rules the agent never breaks.

`id` string 

Read-only

The unique identifier of the agent (UUID).

`instructions` string

Free-text instructions that refine the role: who the business is, what matters to it.

`knowledgeDocumentCount` integer (int32) 

Read-only

How many knowledge documents the agent has.

`knowledgeDocuments` array of object 

Read-only

The agent's knowledge documents. Getting one agent returns them with their content; listing agents leaves them out.

6 child attributes

`agentId` string 

Read-only

The agent the document belongs to (UUID).

`content` string

The document's Markdown content.

`createdAt` string (date-time) 

Read-only

When the document was created.

`id` string 

Read-only

The unique identifier of the document (UUID).

`title` string

The document's title.

`updatedAt` string (date-time) 

Read-only

When the document was last updated.

`language` string

ISO 639-1 code of the language the agent always speaks. Empty matches the visitor's language.

`name` string

The agent's name, shown to the workspace and used by the agent to introduce itself.

`questionHandling` enum

What the agent does when a visitor asks it something.

Allowed values

* `AGENT_QUESTION_HANDLING_ANSWER_AND_STEER` Answers, then brings the conversation back to its goal.
* `AGENT_QUESTION_HANDLING_ANSWER_BRIEFLY` One-line answers, then back to the goal.
* `AGENT_QUESTION_HANDLING_COLLECT_ONLY` Politely declines questions and only collects.
* `AGENT_QUESTION_HANDLING_FREE_CONVERSATION` Talks freely and collects along the way.
* `AGENT_QUESTION_HANDLING_UNSPECIFIED` Not set. Defaults to AGENT\_QUESTION\_HANDLING\_ANSWER\_AND\_STEER on create, keeps the value on update.

`replyLength` enum

How long the agent's messages are.

Allowed values

* `AGENT_REPLY_LENGTH_SHORT` One or two sentences.
* `AGENT_REPLY_LENGTH_MEDIUM` A short paragraph.
* `AGENT_REPLY_LENGTH_DETAILED` As long as the answer needs.
* `AGENT_REPLY_LENGTH_UNSPECIFIED` Not set. Defaults to AGENT\_REPLY\_LENGTH\_SHORT on create, keeps the value on update.

`role` enum

The job the agent does.

Allowed values

* `AGENT_ROLE_LEAD_QUALIFIER` Qualifies leads: learns who the visitor is and what they need.
* `AGENT_ROLE_EVENT_CONCIERGE` Welcomes event attendees and answers practical questions.
* `AGENT_ROLE_FEEDBACK_COLLECTOR` Collects feedback about an experience.
* `AGENT_ROLE_PRODUCT_EXPERT` Presents a product and answers questions about it.
* `AGENT_ROLE_SUPPORT_FAQ` Answers frequent support questions.
* `AGENT_ROLE_CUSTOM` No preset role: the agent follows its instructions only.
* `AGENT_ROLE_UNSPECIFIED` Not set. Defaults to AGENT\_ROLE\_CUSTOM on create, keeps the value on update.

`styleNotes` string

Free-text notes that refine the tone.

`tone` enum

How the agent sounds.

Allowed values

* `AGENT_TONE_FRIENDLY` Warm and approachable.
* `AGENT_TONE_PROFESSIONAL` Polished and businesslike.
* `AGENT_TONE_PLAYFUL` Light and fun.
* `AGENT_TONE_CONCISE` Straight to the point.
* `AGENT_TONE_ENTHUSIASTIC` Energetic and upbeat.
* `AGENT_TONE_UNSPECIFIED` Not set. Defaults to AGENT\_TONE\_FRIENDLY on create, keeps the value on update.

`updatedAt` string (date-time) 

Read-only

When the agent was last updated.

`usages` array of object 

Read-only

The workflow steps that talk through this agent. An agent in use cannot be deleted.

3 child attributes

`linkId` string

The link the step belongs to (UUID).

`linkName` string

The link's name, or its short link when it has none.

`workflowStepId` string

The chat bot step (UUID).

`workspaceId` string 

Read-only

The workspace the agent belongs to (UUID).

Example agent

```json
{
  "createdAt": "2026-03-14T09:30:00Z",
  "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
  "emojiEnabled": true,
  "guardrails": [
    "AGENT_GUARDRAIL_STAY_ON_TOPIC",
    "AGENT_GUARDRAIL_NO_COMMITMENTS"
  ],
  "id": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
  "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon.",
  "knowledgeDocumentCount": 3,
  "knowledgeDocuments": [
    {
      "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
      "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
      "createdAt": "2026-03-14T09:30:00Z",
      "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
      "title": "Opening hours and prices",
      "updatedAt": "2026-03-18T16:05:00Z"
    }
  ],
  "language": "fr",
  "name": "Front desk",
  "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
  "replyLength": "AGENT_REPLY_LENGTH_SHORT",
  "role": "AGENT_ROLE_SUPPORT_FAQ",
  "styleNotes": "Address visitors informally.",
  "tone": "AGENT_TONE_FRIENDLY",
  "updatedAt": "2026-03-18T16:05:00Z",
  "usages": [
    {
      "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "linkName": "Spring menu",
      "workflowStepId": "987fcdeb-a321-45e6-b789-123456789012"
    }
  ],
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}
```

### Response

200

`guardrails` array of object

The guardrails.

4 child attributes

`defaultEnabled` boolean

Whether new agents get this guardrail by default.

`description` string

What the guardrail prevents.

`label` string

Short name shown in the picker.

`value` enum

The guardrail.

Allowed values

* `AGENT_GUARDRAIL_STAY_ON_TOPIC` Stays on the business's topics.
* `AGENT_GUARDRAIL_KNOWLEDGE_ONLY` Answers only from its knowledge.
* `AGENT_GUARDRAIL_NO_COMMITMENTS` Makes no promises.
* `AGENT_GUARDRAIL_NO_COMPETITORS` Does not discuss competitors.
* `AGENT_GUARDRAIL_NO_PROFESSIONAL_ADVICE` Gives no legal, medical or financial advice.
* `AGENT_GUARDRAIL_DECLINE_OFFENSIVE` Declines offensive requests politely.
* `AGENT_GUARDRAIL_UNSPECIFIED` Not a guardrail. Rejected.

`limits` object

The limits agent settings and knowledge must stay within.

11 child attributes

`chatBotDefaultExchanges` integer (int32)

Messages a chat bot step allows when it does not say.

`chatBotMaxExchanges` integer (int32)

Most messages a chat bot step can allow a visitor.

`chatBotMaxObjectives` integer (int32)

Most objectives a chat bot step can have.

`chatBotMinExchanges` integer (int32)

Fewest messages a chat bot step can allow a visitor.

`customRulesMaxLength` integer (int32)

Longest custom rules, in characters.

`instructionsMaxLength` integer (int32)

Longest instructions, in characters.

`knowledgeMaxDocuments` integer (int32)

Most knowledge documents an agent can have.

`knowledgeMaxTotalCharacters` integer (int32)

Most characters an agent's knowledge documents can hold together.

`knowledgeTitleMaxLength` integer (int32)

Longest knowledge document title, in characters.

`nameMaxLength` integer (int32)

Longest name, in characters.

`styleNotesMaxLength` integer (int32)

Longest style notes, in characters.

`questionHandlings` array of object

The ways to handle visitor questions.

3 child attributes

`description` string

What the agent does with questions.

`label` string

Short name shown in the picker.

`value` enum

The question handling.

Allowed values

* `AGENT_QUESTION_HANDLING_ANSWER_AND_STEER` Answers, then brings the conversation back to its goal.
* `AGENT_QUESTION_HANDLING_ANSWER_BRIEFLY` One-line answers, then back to the goal.
* `AGENT_QUESTION_HANDLING_COLLECT_ONLY` Politely declines questions and only collects.
* `AGENT_QUESTION_HANDLING_FREE_CONVERSATION` Talks freely and collects along the way.
* `AGENT_QUESTION_HANDLING_UNSPECIFIED` Not set. Defaults to AGENT\_QUESTION\_HANDLING\_ANSWER\_AND\_STEER on create, keeps the value on update.

`replyLengths` array of object

The reply lengths.

3 child attributes

`description` string

How long the replies are.

`label` string

Short name shown in the picker.

`value` enum

The reply length.

Allowed values

* `AGENT_REPLY_LENGTH_SHORT` One or two sentences.
* `AGENT_REPLY_LENGTH_MEDIUM` A short paragraph.
* `AGENT_REPLY_LENGTH_DETAILED` As long as the answer needs.
* `AGENT_REPLY_LENGTH_UNSPECIFIED` Not set. Defaults to AGENT\_REPLY\_LENGTH\_SHORT on create, keeps the value on update.

`roles` array of object

The roles.

3 child attributes

`description` string

What the role does.

`label` string

Short name shown in the picker.

`value` enum

The role.

Allowed values

* `AGENT_ROLE_LEAD_QUALIFIER` Qualifies leads: learns who the visitor is and what they need.
* `AGENT_ROLE_EVENT_CONCIERGE` Welcomes event attendees and answers practical questions.
* `AGENT_ROLE_FEEDBACK_COLLECTOR` Collects feedback about an experience.
* `AGENT_ROLE_PRODUCT_EXPERT` Presents a product and answers questions about it.
* `AGENT_ROLE_SUPPORT_FAQ` Answers frequent support questions.
* `AGENT_ROLE_CUSTOM` No preset role: the agent follows its instructions only.
* `AGENT_ROLE_UNSPECIFIED` Not set. Defaults to AGENT\_ROLE\_CUSTOM on create, keeps the value on update.

`tones` array of object

The tones.

3 child attributes

`description` string

What the tone sounds like.

`label` string

Short name shown in the picker.

`value` enum

The tone.

Allowed values

* `AGENT_TONE_FRIENDLY` Warm and approachable.
* `AGENT_TONE_PROFESSIONAL` Polished and businesslike.
* `AGENT_TONE_PLAYFUL` Light and fun.
* `AGENT_TONE_CONCISE` Straight to the point.
* `AGENT_TONE_ENTHUSIASTIC` Energetic and upbeat.
* `AGENT_TONE_UNSPECIFIED` Not set. Defaults to AGENT\_TONE\_FRIENDLY on create, keeps the value on update.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/agent-presets" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "guardrails": [
    {
      "defaultEnabled": true,
      "description": "Never promises prices, discounts, delivery dates or anything binding.",
      "label": "No promises",
      "value": "AGENT_GUARDRAIL_NO_COMMITMENTS"
    }
  ],
  "limits": {
    "chatBotDefaultExchanges": 15,
    "chatBotMaxExchanges": 30,
    "chatBotMaxObjectives": 10,
    "chatBotMinExchanges": 3,
    "customRulesMaxLength": 2000,
    "instructionsMaxLength": 4000,
    "knowledgeMaxDocuments": 20,
    "knowledgeMaxTotalCharacters": 50000,
    "knowledgeTitleMaxLength": 120,
    "nameMaxLength": 80,
    "styleNotesMaxLength": 1000
  },
  "questionHandlings": [
    {
      "description": "Answers questions from its knowledge, then brings the conversation back to its goal.",
      "label": "Answer, then steer back",
      "value": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER"
    }
  ],
  "replyLengths": [
    {
      "description": "One or two sentences, ideal on a phone.",
      "label": "Short",
      "value": "AGENT_REPLY_LENGTH_SHORT"
    }
  ],
  "roles": [
    {
      "description": "Answers frequent questions and helps visitors solve simple problems.",
      "label": "Support FAQ",
      "value": "AGENT_ROLE_SUPPORT_FAQ"
    }
  ],
  "tones": [
    {
      "description": "Warm and approachable, like a helpful host.",
      "label": "Friendly",
      "value": "AGENT_TONE_FRIENDLY"
    }
  ]
}
```

### Parameters

`pageSize` integer (int64) 

query

Maximum number of agents to return. Defaults to 50.

`pageToken` string 

query

Token from a previous response's nextPageToken.

`cursor` string 

query

Opaque cursor from the previous page's nextPageToken. Same as pageToken; when both are sent, pageToken wins.

### Response

200

`agents` array of object

The agents, without their knowledge documents.

Fields: [The agent object](#agents-object).

`nextPageToken` string

Token for the next page. Empty on the last page.

`totalCount` integer (int64)

How many agents the workspace has. Set on the last page only.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/agents" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "agents": [
    {
      "createdAt": "2026-03-14T09:30:00Z",
      "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
      "emojiEnabled": true,
      "guardrails": [
        "AGENT_GUARDRAIL_STAY_ON_TOPIC",
        "AGENT_GUARDRAIL_NO_COMMITMENTS"
      ],
      "id": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
      "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon.",
      "knowledgeDocumentCount": 3,
      "knowledgeDocuments": [
        {
          "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
          "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
          "createdAt": "2026-03-14T09:30:00Z",
          "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
          "title": "Opening hours and prices",
          "updatedAt": "2026-03-18T16:05:00Z"
        }
      ],
      "language": "fr",
      "name": "Front desk",
      "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
      "replyLength": "AGENT_REPLY_LENGTH_SHORT",
      "role": "AGENT_ROLE_SUPPORT_FAQ",
      "styleNotes": "Address visitors informally.",
      "tone": "AGENT_TONE_FRIENDLY",
      "updatedAt": "2026-03-18T16:05:00Z",
      "usages": [
        {
          "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
          "linkName": "Spring menu",
          "workflowStepId": "987fcdeb-a321-45e6-b789-123456789012"
        }
      ],
      "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjI1fQ",
  "totalCount": 3
}
```

### Parameters

`id` string 

path

Required

The agent's ID (UUID).

### Response

200

`agent` object

The agent, with its knowledge documents and their content.

Fields: [The agent object](#agents-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/agents/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "agent": {
    "createdAt": "2026-03-14T09:30:00Z",
    "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
    "emojiEnabled": true,
    "guardrails": [
      "AGENT_GUARDRAIL_STAY_ON_TOPIC",
      "AGENT_GUARDRAIL_NO_COMMITMENTS"
    ],
    "id": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
    "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon.",
    "knowledgeDocumentCount": 3,
    "knowledgeDocuments": [
      {
        "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
        "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
        "createdAt": "2026-03-14T09:30:00Z",
        "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
        "title": "Opening hours and prices",
        "updatedAt": "2026-03-18T16:05:00Z"
      }
    ],
    "language": "fr",
    "name": "Front desk",
    "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
    "replyLength": "AGENT_REPLY_LENGTH_SHORT",
    "role": "AGENT_ROLE_SUPPORT_FAQ",
    "styleNotes": "Address visitors informally.",
    "tone": "AGENT_TONE_FRIENDLY",
    "updatedAt": "2026-03-18T16:05:00Z",
    "usages": [
      {
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "linkName": "Spring menu",
        "workflowStepId": "987fcdeb-a321-45e6-b789-123456789012"
      }
    ],
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`customRules` string

Free-text rules the agent never breaks.

`emojiEnabled` boolean

Whether the agent may use emoji. Off when unset.

`guardrails` array of enum

The preset rules the agent never breaks. Leave empty for the defaults.

`instructions` string

Free-text instructions that refine the role.

`language` string

ISO 639-1 code of the language the agent always speaks. Empty matches the visitor's language.

`name` string 

Required

The agent's name.

`questionHandling` enum

What the agent does when a visitor asks it something.

Allowed values

* `AGENT_QUESTION_HANDLING_ANSWER_AND_STEER` Answers, then brings the conversation back to its goal.
* `AGENT_QUESTION_HANDLING_ANSWER_BRIEFLY` One-line answers, then back to the goal.
* `AGENT_QUESTION_HANDLING_COLLECT_ONLY` Politely declines questions and only collects.
* `AGENT_QUESTION_HANDLING_FREE_CONVERSATION` Talks freely and collects along the way.
* `AGENT_QUESTION_HANDLING_UNSPECIFIED` Not set. Defaults to AGENT\_QUESTION\_HANDLING\_ANSWER\_AND\_STEER on create, keeps the value on update.

`replyLength` enum

How long the agent's messages are.

Allowed values

* `AGENT_REPLY_LENGTH_SHORT` One or two sentences.
* `AGENT_REPLY_LENGTH_MEDIUM` A short paragraph.
* `AGENT_REPLY_LENGTH_DETAILED` As long as the answer needs.
* `AGENT_REPLY_LENGTH_UNSPECIFIED` Not set. Defaults to AGENT\_REPLY\_LENGTH\_SHORT on create, keeps the value on update.

`role` enum

The job the agent does.

Allowed values

* `AGENT_ROLE_LEAD_QUALIFIER` Qualifies leads: learns who the visitor is and what they need.
* `AGENT_ROLE_EVENT_CONCIERGE` Welcomes event attendees and answers practical questions.
* `AGENT_ROLE_FEEDBACK_COLLECTOR` Collects feedback about an experience.
* `AGENT_ROLE_PRODUCT_EXPERT` Presents a product and answers questions about it.
* `AGENT_ROLE_SUPPORT_FAQ` Answers frequent support questions.
* `AGENT_ROLE_CUSTOM` No preset role: the agent follows its instructions only.
* `AGENT_ROLE_UNSPECIFIED` Not set. Defaults to AGENT\_ROLE\_CUSTOM on create, keeps the value on update.

`styleNotes` string

Free-text notes that refine the tone.

`tone` enum

How the agent sounds.

Allowed values

* `AGENT_TONE_FRIENDLY` Warm and approachable.
* `AGENT_TONE_PROFESSIONAL` Polished and businesslike.
* `AGENT_TONE_PLAYFUL` Light and fun.
* `AGENT_TONE_CONCISE` Straight to the point.
* `AGENT_TONE_ENTHUSIASTIC` Energetic and upbeat.
* `AGENT_TONE_UNSPECIFIED` Not set. Defaults to AGENT\_TONE\_FRIENDLY on create, keeps the value on update.

### Response

200

`agent` object

The created agent.

Fields: [The agent object](#agents-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/agents" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
  "emojiEnabled": true,
  "guardrails": [
    "AGENT_GUARDRAIL_STAY_ON_TOPIC",
    "AGENT_GUARDRAIL_NO_COMMITMENTS"
  ],
  "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon. Help guests with the restaurant'\''s spring menu.",
  "language": "fr",
  "name": "Front desk",
  "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
  "replyLength": "AGENT_REPLY_LENGTH_SHORT",
  "role": "AGENT_ROLE_SUPPORT_FAQ",
  "styleNotes": "Address visitors informally.",
  "tone": "AGENT_TONE_FRIENDLY"
}'
```

Response 200

```json
{
  "agent": {
    "createdAt": "2026-03-14T09:30:00Z",
    "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
    "emojiEnabled": true,
    "guardrails": [
      "AGENT_GUARDRAIL_STAY_ON_TOPIC",
      "AGENT_GUARDRAIL_NO_COMMITMENTS"
    ],
    "id": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
    "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon.",
    "knowledgeDocumentCount": 3,
    "knowledgeDocuments": [
      {
        "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
        "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
        "createdAt": "2026-03-14T09:30:00Z",
        "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
        "title": "Opening hours and prices",
        "updatedAt": "2026-03-18T16:05:00Z"
      }
    ],
    "language": "fr",
    "name": "Front desk",
    "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
    "replyLength": "AGENT_REPLY_LENGTH_SHORT",
    "role": "AGENT_ROLE_SUPPORT_FAQ",
    "styleNotes": "Address visitors informally.",
    "tone": "AGENT_TONE_FRIENDLY",
    "updatedAt": "2026-03-18T16:05:00Z",
    "usages": [
      {
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "linkName": "Spring menu",
        "workflowStepId": "987fcdeb-a321-45e6-b789-123456789012"
      }
    ],
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`agentId` string 

path

Required

The agent's ID (UUID).

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`content` string 

Required

The document's Markdown content.

`title` string 

Required

The document's title.

### Response

200

`document` object

The created document.

6 child attributes

`agentId` string 

Read-only

The agent the document belongs to (UUID).

`content` string

The document's Markdown content.

`createdAt` string (date-time) 

Read-only

When the document was created.

`id` string 

Read-only

The unique identifier of the document (UUID).

`title` string

The document's title.

`updatedAt` string (date-time) 

Read-only

When the document was last updated.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/agents/{agentId}/knowledge-documents" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "content": "# Restaurant\n\nOpen every day from 12pm to 2:30pm and 7pm to 10:30pm.",
  "title": "Restaurant opening hours"
}'
```

Response 200

```json
{
  "document": {
    "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
    "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
    "createdAt": "2026-03-14T09:30:00Z",
    "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
    "title": "Opening hours and prices",
    "updatedAt": "2026-03-18T16:05:00Z"
  }
}
```

### Parameters

`agentId` string 

path

Required

The agent's ID (UUID).

`id` string 

path

Required

The document's ID (UUID).

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`content` string

New Markdown content.

`title` string

New title.

### Response

200

`document` object

The updated document.

6 child attributes

`agentId` string 

Read-only

The agent the document belongs to (UUID).

`content` string

The document's Markdown content.

`createdAt` string (date-time) 

Read-only

When the document was created.

`id` string 

Read-only

The unique identifier of the document (UUID).

`title` string

The document's title.

`updatedAt` string (date-time) 

Read-only

When the document was last updated.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/agents/{agentId}/knowledge-documents/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "content": "# Restaurant\n\nOpen every day from 12pm to 2:30pm and 7pm to 11pm.",
  "title": "Restaurant opening hours"
}'
```

Response 200

```json
{
  "document": {
    "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
    "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
    "createdAt": "2026-03-14T09:30:00Z",
    "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
    "title": "Opening hours and prices",
    "updatedAt": "2026-03-18T16:05:00Z"
  }
}
```

### Parameters

`id` string 

path

Required

The agent's ID (UUID).

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`customRules` string

New custom rules.

`emojiEnabled` boolean

Whether the agent may use emoji.

`guardrails` object

New guardrails, replacing the current ones.

1 child attribute

`values` array of enum

The guardrails. Empty removes them all.

`instructions` string

New instructions.

`language` string

New language code. An empty string matches the visitor's language.

`name` string

New name.

`questionHandling` enum

New question handling. UNSPECIFIED keeps it.

Allowed values

* `AGENT_QUESTION_HANDLING_ANSWER_AND_STEER` Answers, then brings the conversation back to its goal.
* `AGENT_QUESTION_HANDLING_ANSWER_BRIEFLY` One-line answers, then back to the goal.
* `AGENT_QUESTION_HANDLING_COLLECT_ONLY` Politely declines questions and only collects.
* `AGENT_QUESTION_HANDLING_FREE_CONVERSATION` Talks freely and collects along the way.
* `AGENT_QUESTION_HANDLING_UNSPECIFIED` Not set. Defaults to AGENT\_QUESTION\_HANDLING\_ANSWER\_AND\_STEER on create, keeps the value on update.

`replyLength` enum

New reply length. UNSPECIFIED keeps it.

Allowed values

* `AGENT_REPLY_LENGTH_SHORT` One or two sentences.
* `AGENT_REPLY_LENGTH_MEDIUM` A short paragraph.
* `AGENT_REPLY_LENGTH_DETAILED` As long as the answer needs.
* `AGENT_REPLY_LENGTH_UNSPECIFIED` Not set. Defaults to AGENT\_REPLY\_LENGTH\_SHORT on create, keeps the value on update.

`role` enum

New role. UNSPECIFIED keeps it.

Allowed values

* `AGENT_ROLE_LEAD_QUALIFIER` Qualifies leads: learns who the visitor is and what they need.
* `AGENT_ROLE_EVENT_CONCIERGE` Welcomes event attendees and answers practical questions.
* `AGENT_ROLE_FEEDBACK_COLLECTOR` Collects feedback about an experience.
* `AGENT_ROLE_PRODUCT_EXPERT` Presents a product and answers questions about it.
* `AGENT_ROLE_SUPPORT_FAQ` Answers frequent support questions.
* `AGENT_ROLE_CUSTOM` No preset role: the agent follows its instructions only.
* `AGENT_ROLE_UNSPECIFIED` Not set. Defaults to AGENT\_ROLE\_CUSTOM on create, keeps the value on update.

`styleNotes` string

New style notes.

`tone` enum

New tone. UNSPECIFIED keeps it.

Allowed values

* `AGENT_TONE_FRIENDLY` Warm and approachable.
* `AGENT_TONE_PROFESSIONAL` Polished and businesslike.
* `AGENT_TONE_PLAYFUL` Light and fun.
* `AGENT_TONE_CONCISE` Straight to the point.
* `AGENT_TONE_ENTHUSIASTIC` Energetic and upbeat.
* `AGENT_TONE_UNSPECIFIED` Not set. Defaults to AGENT\_TONE\_FRIENDLY on create, keeps the value on update.

### Response

200

`agent` object

The updated agent, with its knowledge documents.

Fields: [The agent object](#agents-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/agents/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
  "emojiEnabled": false,
  "guardrails": {
    "values": [
      "AGENT_GUARDRAIL_STAY_ON_TOPIC",
      "AGENT_GUARDRAIL_NO_COMMITMENTS"
    ]
  },
  "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon. Help guests with the restaurant'\''s spring menu.",
  "language": "en",
  "name": "Concierge",
  "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_BRIEFLY",
  "replyLength": "AGENT_REPLY_LENGTH_MEDIUM",
  "role": "AGENT_ROLE_EVENT_CONCIERGE",
  "styleNotes": "Use the guest'\''s first name when they give it.",
  "tone": "AGENT_TONE_PROFESSIONAL"
}'
```

Response 200

```json
{
  "agent": {
    "createdAt": "2026-03-14T09:30:00Z",
    "customRules": "Never quote room rates. Send booking questions to reception@example.com.",
    "emojiEnabled": true,
    "guardrails": [
      "AGENT_GUARDRAIL_STAY_ON_TOPIC",
      "AGENT_GUARDRAIL_NO_COMMITMENTS"
    ],
    "id": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
    "instructions": "You work for Hotel Lumiere, a boutique hotel in Lyon.",
    "knowledgeDocumentCount": 3,
    "knowledgeDocuments": [
      {
        "agentId": "3f9a1c52-8d1e-4b7a-9c3e-2a6f5d8b1e40",
        "content": "# Opening hours\n\nMonday to Friday, 9am to 6pm.",
        "createdAt": "2026-03-14T09:30:00Z",
        "id": "e5b2c8f1-6a3d-4b9e-8c7f-1d0a2e4b6c93",
        "title": "Opening hours and prices",
        "updatedAt": "2026-03-18T16:05:00Z"
      }
    ],
    "language": "fr",
    "name": "Front desk",
    "questionHandling": "AGENT_QUESTION_HANDLING_ANSWER_AND_STEER",
    "replyLength": "AGENT_REPLY_LENGTH_SHORT",
    "role": "AGENT_ROLE_SUPPORT_FAQ",
    "styleNotes": "Address visitors informally.",
    "tone": "AGENT_TONE_FRIENDLY",
    "updatedAt": "2026-03-18T16:05:00Z",
    "usages": [
      {
        "linkId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "linkName": "Spring menu",
        "workflowStepId": "987fcdeb-a321-45e6-b789-123456789012"
      }
    ],
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`agentId` string 

path

Required

The agent's ID (UUID).

`id` string 

path

Required

The document's ID (UUID).

### Response

200

An empty JSON object.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/agents/{agentId}/knowledge-documents/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

### Parameters

`id` string 

path

Required

The agent's ID (UUID).

### Response

200

An empty JSON object.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/agents/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

Source: https://linkbreakers.com/help/api/agents
