> ## 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.

# Agent-first onboarding

> Let an AI agent build a Wiredesk agent from a website before anyone has an account, then hand the person one link where they try it and claim it.

With agent-first onboarding, an AI agent such as Claude Code, Codex or Cursor sets Wiredesk up for someone. It sends a website URL, with no Wiredesk account and no API key. Wiredesk builds a trial agent from the site and returns a key that works for that trial. The AI agent tunes the agent and tests it. Then it gives the person one link, where they chat with the agent and claim it into an account.

If you already have an account, [make an API key](https://wiredesk.ai/docs/api-reference/authentication.md) instead.

## Paste this into your AI agent

Copy this prompt into an AI agent that can make web requests, such as Claude Code, Cursor, Codex or Windsurf. Change the website to yours first.

```text Prompt theme={null}
Set up Wiredesk for my business's website: https://YOUR-WEBSITE.com

Wiredesk is an AI agent that answers customers on chat, phone and email.
Read https://wiredesk.ai/docs/developers/agent-onboarding.md and follow it.
No Wiredesk account or API key is needed to start.

1. Start a trial: POST https://wiredesk.ai/api/v1/onboarding with my
   website_url, and your own name as agent_name. Keep the api_key it
   returns to yourself.
2. Check GET https://wiredesk.ai/api/v1/onboarding/{id} until knowledge
   is done. This usually takes a minute or two.
3. Test the agent with 5 questions my customers would ask
   (POST /api/v1/agents/{agent_id}/chat). If an answer is wrong or vague,
   fix the instructions or add knowledge, then test again.
4. Give me the claim_url, say what the agent has read, and list what
   you changed. I'll try the agent there and claim it.
```

The agent works for a few minutes and then gives you a link. On that page you chat with your new agent. Sign up or sign in, then press **Claim this agent**. It's free, and you don't need a card.

> [!NOTE]
>
> Chat apps that can only read web pages, such as ChatGPT or Claude on the web, can't start a trial, because they can't send a `POST`. Use an agent that can run commands, or [sign up](https://console.wiredesk.ai/sign-up) and paste your website there.

The rest of this page is for the AI agent, or for you if you're building the integration yourself.

## How it works

1. `POST /onboarding` with the website. No key needed. Wiredesk reads a few pages, drafts the agent's name, greeting and instructions, and starts crawling the whole site. The response includes a key for the trial and `claim_url`.
2. With that key, the AI agent uses the rest of the [API](https://wiredesk.ai/docs/developers/api.md) or the [MCP server](https://wiredesk.ai/docs/developers/mcp.md) like any other caller. For example, it can change the instructions, add knowledge, and send test messages.
3. `GET /onboarding/{id}` returns the setup checklist. The AI agent fixes what is not `done`.
4. The AI agent gives the person `claim_url`. On that page they chat with the agent, sign up or sign in, and press **Claim this agent**.

A trial lasts 7 days. If nobody claims it by then, Wiredesk deletes it.

## Start

```bash theme={null}
curl https://wiredesk.ai/api/v1/onboarding \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://acmeplumbing.com", "agent_name": "Claude" }'
```

| Field | |
| - | - |
| `website_url` | Required. The business's public website. |
| `purpose` | What the agent is for: `answers` (the default) answers questions about the business, `support` helps existing customers with problems, `bookings` takes bookings, and `custom` is anything else. |
| `agent_name` | Your name, as the AI agent doing the setup. The claim page shows it: "Claude built this from acmeplumbing.com". |
| `client_id` | Your runtime's own id, if it has one. |

The response is `201`:

```json theme={null}
{
  "data": {
    "id": "ob_3f9a1c2d4e5f60718293a4b5c6d7e8f9",
    "object": "onboarding",
    "status": "active",
    "agent_id": "8f0e…",
    "website_url": "https://acmeplumbing.com/",
    "setup_agent": "Claude",
    "claim_url": "https://console.wiredesk.ai/try/ob_3f9a1c2d4e5f60718293a4b5c6d7e8f9",
    "claim": { "email": null, "plan": "free", "claimed_at": null },
    "created_at": "2026-10-10T12:00:00.000Z",
    "expires_at": "2026-10-17T12:00:00.000Z",
    "api_key": "wd_…",
    "api_base": "https://wiredesk.ai/api/v1",
    "mcp_url": "https://wiredesk.ai/api/mcp",
    "setup": [
      { "key": "knowledge", "state": "pending", "detail": "Still reading the website. Check again in a minute." },
      { "key": "instructions", "state": "done", "detail": "164 words." },
      { "key": "greeting", "state": "done", "detail": "Acme Plumbing, how can I help?" },
      { "key": "appearance", "state": "pending", "detail": "Reading the website's colours. Check again in a few seconds." }
    ]
  }
}
```

Save `id`, `agent_id` and `api_key`. The key is shown only once. Do not show the full key to the person.

Starting takes a few seconds: Wiredesk reads the home page and a few others and drafts the agent before it answers. The rest of the site, and its colours, are read afterwards. A site Wiredesk cannot read returns `502`, and nothing is created.

## Set up and test the agent

Send the trial's key as `Authorization: Bearer wd_…`. It works for this trial's agent only.

```bash theme={null}
# Change the instructions
curl -X PATCH https://wiredesk.ai/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "You answer for Acme Plumbing in Ithaca, NY…" }'

# Teach it something the site does not say
curl https://wiredesk.ai/api/v1/agents/AGENT_ID/knowledge \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "label": "Call-out fee", "content": "Emergency call-outs are $95 before 8pm." }'

# Ask it what a customer would
curl https://wiredesk.ai/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you do emergency call-outs on Sunday?" }'
```

Useful calls during setup:

* `PATCH /agents/{agent_id}` changes the name, greeting or instructions.
* `GET /agents/{agent_id}/knowledge` shows when the website is `ready`.
* `POST /agents/{agent_id}/knowledge` adds pasted text or another website.
* `POST /agents/{agent_id}/chat` sends a test message.

The same key works with the [MCP server](https://wiredesk.ai/docs/developers/mcp.md) at `https://wiredesk.ai/api/mcp`.

A trial's chats stop at \$2 of usage, which is about 100 replies, until someone claims it.

## Check the setup

```bash theme={null}
curl https://wiredesk.ai/api/v1/onboarding/ob_3f9a… \
  -H "Authorization: Bearer wd_…"
```

`data.setup` lists four items. Each item has a `state` and a `detail`.

| `key` | Done when |
| - | - |
| `knowledge` | The website has been read. It is `pending` while the site is crawled, usually a minute or two, and `warning` if the crawl failed. |
| `instructions` | The agent has instructions. |
| `greeting` | The agent has a greeting. |
| `appearance` | The widget uses the site's colours. It is `pending` for up to half a minute after the start while they are read, and `warning` if Wiredesk could not read them. The person can set them after claiming. |

Share `claim_url` once the knowledge is `done` and the test answers use facts from the website.

## Hand it to the person

Give the person `claim_url`. Tell them what the agent is for, what it has read, and anything you changed.

If they have told you the email they will sign up with, save it first. The sign-up form then has it filled in:

```bash theme={null}
curl https://wiredesk.ai/api/v1/onboarding/ob_3f9a…/claim \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@acmeplumbing.com" }'
```

The response is the onboarding, with `claim_url`. The claim itself is always made by the person, signed in, on that page. The API cannot claim an agent for someone.

## What claiming does

The person signs up or signs in, then presses **Claim this agent**:

* **They have no workspace yet.** The trial's workspace becomes theirs, with the agent, its knowledge and the test conversations.
* **They already have a workspace.** The agent is copied into it, and the website is crawled again for the copy. The trial is deleted. They need to be an owner or admin there, and the workspace needs room under its plan's agent limit.

A claimed agent is always on the **Free** plan, with no card. The person can upgrade later under **Billing**. See [Plans and limits](https://wiredesk.ai/docs/reference/plans-and-limits.md).

After a claim, the trial's key stops working. `GET /onboarding/{id}` with a key from the workspace the agent went to shows `status: "claimed"` and the agent's new `agent_id`.

## Delete a trial

If the person does not want the agent, or the setup went wrong:

```bash theme={null}
curl -X DELETE https://wiredesk.ai/api/v1/onboarding/ob_3f9a… \
  -H "Authorization: Bearer wd_…"
```

This deletes the agent and the trial, and the key stops working. You cannot delete an agent someone has claimed: that returns `409 conflict`.

## Build trials for other people

If you build agents for others, such as an agency making demos for prospects, send your workspace's full-access [API key](https://wiredesk.ai/docs/api-reference/authentication.md) with the start:

```bash theme={null}
curl https://wiredesk.ai/api/v1/onboarding \
  -H "Authorization: Bearer wd_…" \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://acmeplumbing.com", "agent_name": "Northside Digital" }'
```

The trial is the same: its own workspace, its own key in the response, and a `claim_url` for the person it is for. The difference is the limit. The starts count against your workspace, 100 a day, rather than against your IP address. The key must be valid, or the start fails with `401`. A trial's own key counts by IP address, as if no key was sent.

### From an agent's API call

Your own Wiredesk agent can build a visitor a trial in the middle of a chat, with an [API call](https://wiredesk.ai/docs/actions/api-calls.md) action. Under **Actions**, add an **API call**:

| Field | Value |
| - | - |
| **Tool name** | `build_trial_agent` |
| **When should the agent call this?** | When a visitor wants to try a chatbot or an agent for their own business, once they have given their website. |
| **Method** | `POST` |
| **URL** | `https://wiredesk.ai/api/v1/onboarding` |
| **Params** | `website_url`: "The visitor's business website, e.g. acme.com" (required) |
| **Request body** | `{"website_url": "{{website_url}}", "agent_name": "Your company"}` |
| **Response fields** | `data.claim_url` |
| **Authentication** | **Bearer token**, with a full-access API key from your workspace |
| **Channels** | Chat |

Then tell the agent, in its instructions, to ask for the visitor's website when they want to try it, and to give them the `data.claim_url` it gets back. For example:

```text theme={null}
When someone wants to try us, start a pilot, or see a chatbot for their own business, don't take
their details first. Ask for their website address, call build_trial_agent with it, and tell them
it takes a few seconds. Give them the data.claim_url it returns, exactly as returned, as a link.
Never make up a link. If it fails, say so and offer to take their details instead.
```

Listing the response field keeps the trial's own key out of the conversation. Starting a trial takes a few seconds, well within the 30 seconds an API call gets on chat.

> [!WARNING]
>
> Add the key. Without one the action still works, but a call from an agent reaches Wiredesk with no visitor address, so every such trial counts as the same caller and shares one limit of 10 a day with every other agent that calls without a key. With your workspace's key it is 100 a day. Past the limit the agent gets a `429` and no link, and follows its instructions for a failure.

## Limits

* 20 requests a minute and 10 trials a day from one IP address, and a daily limit across everyone. Past either limit, a start gets `429`. For more, sign up and [send your workspace's key](#build-trials-for-other-people) with each start.
* A trial's chats stop at \$2 of usage.
* A trial lasts 7 days.
* Anyone with `claim_url` can claim the agent. Share it only with the person it is for.

## Related

* [REST API](https://wiredesk.ai/docs/developers/api.md)
* [MCP server](https://wiredesk.ai/docs/developers/mcp.md)
* [Create an agent](https://wiredesk.ai/docs/agents/create-an-agent.md)


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