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

# REST API

> Read and change a workspace from your own code: agents, conversations, contacts, leads and knowledge, and talk to an agent. How each part behaves, beyond the API reference.

The REST API reads and changes one workspace: its agents, conversations and messages, contacts, leads and knowledge. You can also send a customer's message to an agent and get its reply, without the chat widget. Every endpoint is on every plan.

```
https://wiredesk.ai/api/v1
```

The [API reference](https://wiredesk.ai/docs/api-reference/introduction.md) tab lists every endpoint with its parameters and responses, and lets you try each one. It starts with [authentication](https://wiredesk.ai/docs/api-reference/authentication.md) and the [conventions](https://wiredesk.ai/docs/api-reference/conventions.md) every endpoint follows: errors, pagination and rate limits. It is built from an OpenAPI 3.1 spec you can also import into Postman or a code generator: `https://wiredesk.ai/docs/api-reference/openapi.json`. The same operations are also tools on the [MCP server](https://wiredesk.ai/docs/developers/mcp.md), for AI assistants.

This page covers what the reference leaves out: how changing an agent, talking to one, search, knowledge and contacts behave.

## Change an agent

`PATCH /agents/{agent_id}` changes the agent's `name` (up to 80 characters), `greeting` (300) or `instructions` (4,000). Send only the fields that change. They take effect on every channel at once. `greeting` is the phone greeting, spoken when the agent picks up a call; website chat opens with the widget's own opening message instead. Each change is a new version in the agent's **Settings › Version history**, so you can roll it back, and appears in the activity log with the key's name. Voice, actions, channels and the widget's look are changed in the dashboard.

## Talk to an agent

`POST /agents/{agent_id}/chat` runs the same agent as the chat widget, with the same instructions, knowledge, actions and handover. It is billed as a chat reply.

```bash theme={null}
curl https://wiredesk.ai/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "When are you open on Saturday?", "user_id": "crm-4812", "name": "Jane Doe" }'
```

```json theme={null}
{
  "data": {
    "conversation_id": "2b0c…",
    "user_message": { "id": "981", "object": "message", "role": "user", "text": "When are you open on Saturday?", … },
    "reply": { "id": "982", "object": "message", "role": "agent", "text": "Saturdays we're open 10 to 4.", … },
    "handover_state": null
  }
}
```

* Leave out `conversation_id` to start a conversation. Pass the one you got back to continue it. Only conversations started through the API can be continued this way.
* `user_id` is your own id for the person. Their conversations then share one contact, of kind `api`, whose value is your `user_id`. It is kept apart from website visitors, so nobody on your website can claim it. Without it, each conversation gets a contact of its own.
* `name` is stored on the contact if it has none yet.
* If a teammate has taken the conversation over, `reply` is `null` and `handover_state` is `active`. Their reply arrives in the [messages list](https://wiredesk.ai/docs/api-reference/conversations/list-messages.md) and as a `message.created` [webhook](https://wiredesk.ai/docs/developers/webhooks.md).
* If the agent asked for a person during its reply, `handover_state` is `requested`.
* If the workspace is at its spend cap, the request gets `402` and nothing is stored.
* If the agent's chat channel is switched off, the request gets `403` and nothing is stored.

API conversations appear in **Conversations** with the channel **Website chat**.

## Search conversations

`GET /conversations/search?q=` finds what the search box on the **Conversations** page finds: the customer's name, number or email, the agent, the channel, the summary, the topic and the outcome. The match is case-insensitive.

One request reads at most 1,000 conversations, newest first. If it stops there without filling the page, `has_more` is `true` and `next_cursor` continues from where it stopped, even if `data` is empty. Keep following the cursor until `has_more` is `false`.

## Knowledge

* **Text** (`"type": "text"`, with `content` up to 200,000 characters and an optional `label`) is indexed before the response. It comes back `201` with `status: "ready"`.
* **A website** (`"type": "url"`, with `url`) is crawled in the background. It comes back `202` with `status: "pending"`. List the sources to see when it is `ready` or `error`.
* **Files** are not in the API yet. Upload them on the agent's **Knowledge** page.
* **Q\&A answers** (`qa`) and **synced sources** (`zendesk_guide`, `intercom_articles`, `notion`, `confluence`) appear in the list and can be deleted here, but are added on the agent's **Knowledge** page. Deleting a synced source removes every article it brought in.
* `GET /agents/{agent_id}/knowledge/search?q=` returns the passages the agent itself would find, best first, each with its `source` and `score`.

## Contacts

You can add a contact before they ever get in touch, for example from your CRM, so the agents know their name. `kind` is `phone` (in international format, like `+14155550123`) or `email`. The first call or email from that number or address lands on that contact. Website visitors' contacts are created by their conversations and cannot be made by hand.

Deleting a contact also deletes the notes the agents saved about them ("Remember callers"). Their conversations stay.

## Related

* [API reference](https://wiredesk.ai/docs/api-reference/introduction.md)
* [Agent-first onboarding](https://wiredesk.ai/docs/developers/agent-onboarding.md)
* [Webhooks](https://wiredesk.ai/docs/developers/webhooks.md)
* [MCP server](https://wiredesk.ai/docs/developers/mcp.md)
* [Request logs](https://wiredesk.ai/docs/developers/logs.md)
* [Exports](https://wiredesk.ai/docs/workspace/exports.md)


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