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

# Agent Signup

> Let an agent create a Raindrop org for you, then claim it with one link.

An agent can create a Raindrop org without a browser or an account. It gets a write key, instruments your app, and checks the integration. You get a claim link, and the first person to sign in becomes the owner of the org.

Ask your agent:

> Set up Raindrop using raindrop.ai/auth.md

[`raindrop.ai/auth.md`](https://www.raindrop.ai/auth.md)

## How it works

* **Unclaimed org.** Signup creates an org on the [Hobby plan](https://raindrop.ai/docs/platform/plans.md) with no members. Its write key can send events, but nobody can sign in to read them.
* **Claim link.** The link is valid for 72 hours. The first person who signs in through it becomes the org's Owner. If nobody claims the org in 72 hours, the link and the write key are disabled.

## Sign up

Run this in the project root:

> [tab] create-raindrop
>
> ```bash theme={null}
> npx -y create-raindrop --org-name "Acme"
> ```
>
> `--org-name` is required and allows letters, numbers, spaces, and underscores. The command writes `RAINDROP_WRITE_KEY` to `./.env`, adds `.env` to `.gitignore`, and prints the claim link. It does not print the key, and it does nothing if `RAINDROP_WRITE_KEY` is already set.

> [tab] HTTP API
>
> ```bash theme={null}
> curl -sS -X POST https://backend.raindrop.ai/api/v1/agent/signup \
>   -H "Content-Type: application/json" \
>   -d '{"org_name":"Acme","source":"claude-code"}'
> ```
>
> `org_name` is required and allows letters, numbers, spaces, and underscores. `source` is optional: the name of the agent.
>
> A `201` response:
>
> ```json theme={null}
> {
>   "status": "created",
>   "org_id": "…",
>   "org_name": "Acme",
>   "write_key": "…",
>   "env_var": "RAINDROP_WRITE_KEY",
>   "plan": "hobby",
>   "claim_url": "https://app.raindrop.ai/claim#…",
>   "integration_check_url": "https://backend.raindrop.ai/api/v1/agent/integration-check"
> }
> ```
>
> Write `write_key` to `.env` as `RAINDROP_WRITE_KEY`, and make sure `.env` is gitignored.

Then instrument the app with the [`raindrop-setup` skill](https://raindrop.ai/docs/integrations/skills) and send one real interaction through it.

## Check the integration

About 30 seconds after the interaction, check the newest event:

> [tab] create-raindrop
>
> ```bash theme={null}
> npx -y create-raindrop check
> ```
>
> Exit code `0` means healthy, `1` means it needs attention (the command prints the checks and a fix prompt), and `2` means no events have arrived yet.

> [tab] HTTP API
>
> ```bash theme={null}
> curl -sS https://backend.raindrop.ai/api/v1/agent/integration-check \
>   -H "Authorization: Bearer $RAINDROP_WRITE_KEY"
> ```
>
> `status` is `no_events`, `needs_attention`, or `healthy`. When it needs attention, the response includes `checks` and a `fix_prompt`.

The check reviews four things, the same as the **Get started** page in the dashboard:

* The user message is clean: only the current turn, as plain text.
* The assistant response is complete: the text the user saw, not a raw provider response.
* Tool calls appear in the trace.
* Tool inputs and outputs are readable.

The agent fixes what fails, sends another interaction, and checks again until the status is `healthy`.

> [!NOTE]
>
> The check works only for an org created through agent signup, until someone claims it. Other write keys get `403`. After the claim, review the integration on the **Get started** page.

## Claim the org

The agent gives you the claim link, which looks like `https://app.raindrop.ai/claim#…`. Open it, sign in or sign up, and select **Claim**. The page shows when the org was created and how many events it has, so you can confirm it's the one your agent set up.

> [!WARNING]
>
> Anyone with the link can claim the org until it's claimed. The agent should show the link only to you and never write it to files, commits, or logs.

## Errors

| Status | `error` | Meaning |
| - | - | - |
| `400` | `invalid_request` | The body is not valid. `message` says what to fix. |
| `401` | `unauthorized` | The integration check needs `Authorization: Bearer <write key>`. |
| `403` | `not_an_unclaimed_agent_org` | The write key is not from agent signup, or the org has been claimed. |
| `404` | `event_not_found` | The newest event is not readable yet. Check again in 30 seconds. |
| `429` | `rate_limited` | Too many signups. Wait for `Retry-After` seconds. |
| `503` | `write_key_pending` | The org exists but its write key is not ready. `message` has the claim link; copy the key from **Settings** after claiming. |
| `500` | `signup_failed` | Try again in a minute. |


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