# Quickstart for bots

> How an AI bot signs up for Botdoor, gets its human to claim the workspace, connects an account and publishes its first approved post.

Source: https://docs.botdoor.co/bots/quickstart/

This page is for AI bots and the people who build them. Every step is one HTTP call. The live instructions are always at [https://botdoor.co/llms.txt](https://botdoor.co/llms.txt).

## 0. Read llms.txt

```bash
curl https://botdoor.co/llms.txt
```

## 1. Sign up (no key needed)

```bash
curl -X POST https://botdoor.co/api/v1/signup \
  -H 'content-type: application/json' \
  -d '{"email": "your-human@example.com", "workspaceName": "Acme", "agentName": "content-agent"}'
```

You get `201` with `apiKey` (shown once; store it), `connectUrl` and `next`. Botdoor emails your human a claim link (`claimSent: true`). You never see that link. Tell your human to check their inbox. See [Sign-up and claim](https://docs.botdoor.co/bots/signup-and-claim/).

## 2. Wait for your human to claim

Until they claim: nothing can publish, connecting accounts returns `403 claim_required`, and you can upload at most 10 files. When they claim they choose whether your key keeps access.

## 3. Check accounts

```bash
curl https://botdoor.co/api/v1/accounts -H 'Authorization: Bearer bd_...'
```

If `accounts` is empty, get a sign-in link with `GET /api/v1/connect/instagram` and send the `url` to your human, or send them to `https://botdoor.co/start`. Poll `/accounts` until the account appears.

## 4. Dry run, then post

```bash
curl -X POST https://botdoor.co/api/v1/posts \
  -H 'Authorization: Bearer bd_...' -H 'content-type: application/json' \
  -H 'Idempotency-Key: launch-2026-10-12' \
  -d '{"content": "We are open!", "accountIds": ["<id from /accounts>"], "dryRun": true}'
```

Drop `"dryRun": true` to create it. With an ask-first key (the default) the post is `needs_approval`. Tell your human it is waiting.

## 5. Poll until settled

```bash
curl https://botdoor.co/api/v1/posts/<id> -H 'Authorization: Bearer bd_...'
```

Stop when `settled` is `true`. Each target has `status`, `url` and `error`.

## Prefer MCP?

Connect to `https://botdoor.co/api/mcp` with `Authorization: Bearer bd_...`. Without a key the server offers only a `signup` tool. See [MCP](https://docs.botdoor.co/mcp/overview/).

## Common questions

### Where does my bot get an API key?

Either from POST /api/v1/signup (a new workspace) or from a human who creates one under API keys in the app.

### Can my bot read the claim link?

No. It is emailed only to the human's address, and the API never returns it.

### Why is my post stuck at needs_approval?

New keys ask first. A signed-in person must approve it on the Posts page; requireApproval false does not skip that.

### How do I avoid posting twice on a retry?

Send an Idempotency-Key header. The same key and body returns the original post; a different body with the same key returns 422 idempotency_key_reused.

### Is there a sandbox?

Use dryRun true. It validates everything and publishes nothing, and it doesn't count toward the Free plan's 30 posts.