MCP server: https://api.geoboom.io/mcp · REST API: https://api.geoboom.io/v1 · OpenAPI: https://api.geoboom.io/v1/openapi.json

# How GEOboom works

GEOboom gets a brand mentioned and linked on the pages that AI answers cite and Google ranks. It finds those pages, reads them for who to write to, pitches their publishers from mailboxes GEOboom provisions and warms for you, helps you answer the replies, and keeps track of what was agreed until the placements are live. You decide what is worth writing to and what to agree; GEOboom does the rest of the work.

## The loop

1. A **project** for each website you are getting links for.
2. A **campaign** in it: a set of pages to pitch, from keywords, AI answers or your own list.
3. GEOboom reads each page, finds its author and contacts, and works out whether it fits. You confirm the **fits**.
4. You **schedule** them: first emails and follow-ups go from the mailboxes GEOboom provisioned for you, on their daily schedule.
5. Replies land in the **inbox**, with a suggested answer. You negotiate.
6. What you agree becomes a **deal**. GEOboom checks its placements every day.

## Getting started

GEOboom is in closed beta: you join by invitation, and your workspace comes ready, with three mailboxes GEOboom has provisioned and warmed. You name the workspace, choose the sender name and photo your mailboxes write as, and start with a project. A normal invitation includes a free first month with 50 credits.

## Projects

A project is one website you are getting links for. Give it the site and press **Read the website**: GEOboom reads it and fills in the brand, what it does, where it is and its postal address (for the legal footer of every email). Choose what you offer publishers: exchange placements, payment, or either.

Every mailbox joins a new project; in **Project settings** you choose which ones send for it and the title each signs with. The project's settings also hold its monthly credit budget and, under **Publishing**, its WordPress connection.

## Campaigns

A campaign is a set of pages pitched together. It is either **Link building** (get mentioned and linked on pages that rank) or **AI answers** (get named on the pages AI engines cite). It works through six steps: **Setup**, **Import**, **Process**, **Filter**, **Schedule**, **Monitor**.

In Setup you choose its templates (it rotates them, so you can compare reply rates), its mailboxes, how hard to push one publisher (how many people, how many of their pages, how many days apart), whether to leave out competitors, and its monthly credit budget. One button launches, pauses and resumes it. Pausing stops sending; research carries on and replies still arrive.

## Finding prospects

Each campaign takes its prospects from one source:

- **Manual import**: paste or upload URLs, as a list, CSV or TSV.
- **From keywords**: the pages that rank for searches you name, or for an AI answers campaign the pages Google's AI answer cites. Choose the market, how deep to read the results and how many to keep, once or weekly or monthly.
- **From prompts**: ask AI engines your buyers' questions and take the pages they cite. **Generate** suggests questions. AI answers campaigns only.
- **From SE Ranking**: the cited pages of a project you track there, with your own SE Ranking key. AI answers campaigns only.

## Deciding what to write to

**Process** reads every page: its author and contacts, what kind of page it is, and whether your project fits. In **Filter** you mark each **A fit** or **Not a fit**. **Auto-filter** decides them for you by the campaign's rules (your own site, red flags, publishers too small or too large, platforms, pages that already name you, pages that are not editorial, a different niche) and says which rule decided each, so you can overrule any. Both can run hourly on their own for new prospects.

## Sending

Select fits and press **Schedule**, then choose to **send** them or to keep them as **drafts** you review first. Each email is written when it goes, from the campaign's templates, and its follow-ups follow on their own until the person replies.

Mail goes Monday to Friday, spread across the day, up to each mailbox's daily cap (30 at most, first emails and follow-ups together). New mailboxes start at 10 a day and ramp up. A weekly test checks where your mail lands; a mailbox that lands in spam rests and comes back by itself when a test passes.

## The inbox

**Actionable** holds what needs you: replies to answer, people to chase, broken placements and invoices to pay. Each thread opens with a suggested reply; nothing is sent until you send it. When a publisher goes quiet, **Write a follow-up** drafts the chase. The **Publisher** tab shows what they have told you about their terms and prices, and your private notes. Mark a publisher **Do not approach** to stop everything still queued for them.

## Deals and placements

When terms are agreed, **Save as deal** from the thread: who it is with, what each side gives (a placement or payment), the price, and each placement (the page it goes on, the URL it points to, the anchor). A deal is **Agreed** until its placements are up, **Partly live** or **Live** as they appear, and **Broken** if one goes missing or changes. GEOboom checks live placements every day and puts a broken one in Actionable, with **Draft a fix request**. Record payment with **Mark paid**; every change to a deal is kept as a version.

If the project's site runs WordPress, connect it under **Publishing** and publish the copy a publisher sends you for your page straight from the thread's **Blurbs** tab, with a preview first.

## Credits and billing

The plan is $150 a month with 50 credits and 3 mailboxes included. One credit is a dollar, and unused credits roll over. Credits pay for two things:

- **A new publisher: half a credit**, charged when the first email to them actually goes, and covering that publisher in that project for 90 days. Follow-ups and other people at the same publisher are free.
- **More mailboxes**: 40 credits for the first month of a set of three, then 30 a month.

Publishers' own fees for placements are between you and them. Scheduled sends reserve credits; each project and campaign has a monthly budget, and sends past it wait as **Budget spent** until the next month or a higher budget. Owners buy more credits, see statements and manage the card under **Settings → Billing**.

## Team

Everyone in an organisation sees all its data. **Owners** also invite and remove people, manage billing, make API keys and approve AI agents; **members** do the outreach.

## With your AI agent

Everything above can also be done by an AI agent such as Claude or Cursor, through GEOboom's MCP server: [connect your agent](https://www.geoboom.io/docs/mcp). Your own software can use the [API](https://www.geoboom.io/docs/api).


# Connect your AI agent

Connect Claude, Cursor or any MCP client, and your agent can do in GEOboom what you do in the app: set up projects and campaigns, find prospects, decide them, launch, answer publishers and write deals down. It works through the same operations the app uses, so it sees what you see and is held to the same rules.

## Connect

The server is at `https://api.geoboom.io/mcp`. Add it to your client, sign in to GEOboom when it asks, choose the organisation and what the agent may do, and its tools appear.

### Claude Code

```
claude mcp add --transport http geoboom https://api.geoboom.io/mcp
```

Then run `/mcp`, pick geoboom and choose Authenticate. A browser opens to sign in and approve.

### Claude

In Settings → Connectors, choose Add custom connector, name it GEOboom and paste `https://api.geoboom.io/mcp`. Connect, sign in, approve.

### Cursor

Add it to `~/.cursor/mcp.json`:

```
{
  "mcpServers": {
    "geoboom": { "url": "https://api.geoboom.io/mcp" }
  }
}
```

### Any other client

The server speaks MCP over Streamable HTTP, without sessions, and signs agents in with OAuth 2.1 (PKCE, client ID metadata documents or dynamic registration). A client that cannot sign in can send an API key instead, made by an owner in Settings → Integrations:

```
claude mcp add --transport http geoboom https://api.geoboom.io/mcp \
  --header "Authorization: Bearer gbk_..."
```

## What an agent may do

Only an owner of the organisation can approve a connection. They choose what it may do, and sending and spending start unticked:

| Scope | Allows |
| --- | --- |
| `read` | See everything: projects, campaigns, prospects, publishers, contacts, deals and the inbox, threads included. |
| `campaigns:write` | Create and change projects and campaigns, set up prospecting, import URLs and decide which fit, edit drafts. |
| `prospecting:spend` | Spend: run prospecting, set monthly credit budgets, turn on automatic scheduling. |
| `mail:send` | Reach publishers: reply on threads, send first emails, launch or resume a campaign. Sent email cannot be taken back. |
| `deals:write` | Write deals down: terms, prices, paid, placements and whether they are live. |

Some things stay with people in the app, whatever the scopes: inviting and removing members, making or widening keys and connections, deleting projects and campaigns, and billing. Archiving and pausing are allowed; deleting is not.

## Sending and spending

A tool that reaches a person outside GEOboom or commits credits takes a required `idempotency_key` argument. The agent makes one per intended action, a UUID is ideal, and passes the same one if it retries. A retry then gets the first call's answer instead of a second email or a second charge.

GEOboom also checks the thing itself, whatever the key: a reply identical to one sent on the same thread in the last 24 hours is refused, and so is a reply when a message arrived after the one the agent says it read (`seenMessageId`), so it answers what the publisher actually said.

Some tools ask before they commit: `campaigns_resume` and `drafts_send` answer with the cost first when there is one, and go ahead when called again with it agreed. Your client shows which tools only read and which reach outside, and most ask you before running the second kind.

## Long work

Prospecting takes minutes. `prospecting_run` returns at once with a `jobId`; the agent follows it with `jobs_get` and reads the run's progress with `prospecting_latestRun`. The prospects it found are then in `prospects_list`.

## When a tool refuses

A refusal comes back as a tool error whose text says what was wrong in plain words: a missing permission, no credits, something not found in this organisation. The [error codes](https://www.geoboom.io/docs/api/errors) are the same as the API's.

## A first session

What an agent does to take a brand from nothing to agreed placements:

1. `org_get`: credits available and whether the organisation is activated.
2. `projects_create` for the brand, then `campaigns_create` in it. A campaign starts paused and empty.
3. `prospecting_saveKeywords` with the searches the brand's buyers make (or `prospecting_savePrompts` with the questions they ask AI), `prospecting_setMode` to make it the campaign's source, and `prospecting_run`. Or bring your own list with `prospects_import`.
4. `jobs_get` until the run is done, then `prospects_list` to see the pages found, most valuable first.
5. `prospects_setVerdict` to mark the fits, or `prospects_planAutoFilter` and `prospects_autoFilter` to let the campaign's rules decide. Fits are searched for contacts.
6. `campaigns_resume` to launch: first emails go from the project's mailboxes on their schedule.
7. `threads_list` with `tab: "need_action"` for the replies that need an answer, `threads_get` to read one, and `threads_reply` to answer.
8. When terms are agreed: `deals_create`, `deals_update` with the price, `deals_addPlacement` for what goes where, and `deals_updatePlacement` to mark it live. GEOboom checks live placements every day; `deals_list` shows which are still as agreed.

Every tool is listed, with its inputs, in the [API reference](https://www.geoboom.io/docs/api#operations): each operation there is a tool, named with an underscore (`deals.create` is `deals_create`).


# GEOboom API

Everything GEOboom does for an organisation, over HTTPS and JSON: the same operations the app and the MCP server use. Every one is listed below with its inputs; the full schemas, outputs included, are public at `https://api.geoboom.io/v1/openapi.json`.

## Authentication

An owner makes a key in Settings → Integrations and chooses what it may do. It starts with `gbk_` and is shown once. Send it on every call:

```
curl https://api.geoboom.io/v1/org \
  -H "Authorization: Bearer gbk_..."
```

A key acts for the person who made it, in one organisation. An owner sees each key's calls in Settings → Integrations, and can pause or revoke it there at any time.

## Permissions

| Scope | Allows |
| --- | --- |
| `read` | See everything: projects, campaigns, prospects, publishers, contacts, deals and the inbox, threads included. |
| `campaigns:write` | Create and change projects and campaigns, set up prospecting, import URLs and decide which fit, edit drafts. |
| `prospecting:spend` | Spend: run prospecting, set monthly credit budgets, turn on automatic scheduling. |
| `mail:send` | Reach publishers: reply on threads, send first emails, launch or resume a campaign. Sent email cannot be taken back. |
| `deals:write` | Write deals down: terms, prices, paid, placements and whether they are live. |

Some things stay with people in the app, whatever the scopes: inviting and removing members, making or widening keys and connections, deleting projects and campaigns, and billing. Archiving and pausing are allowed; deleting is not.

## Requests and answers

The base URL is `https://api.geoboom.io/v1`. Inputs go in the path and query string for `GET`, and as a JSON body otherwise. Answers are JSON. Every answer carries an `x-request-id` header; quote it if you write to us.

## Idempotency

An operation that reaches a person outside GEOboom (`outward`) or commits credits (`spend`) needs an `Idempotency-Key` header. Make one per intended action, a UUID is ideal, and send it unchanged on every retry of that action:

```
curl -X POST https://api.geoboom.io/v1/threads/{conversationId}/replies \
  -H "Authorization: Bearer gbk_..." \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4e0a-9c55-2d8f1e3b7a10" \
  -H "Content-Type: application/json" \
  -d '{"topicKey": "...", "seenMessageId": "...", "bodyText": "..."}'
```

- A retry with the same key gets the first call's answer, marked `Idempotent-Replayed: true`, instead of a second email or a second charge. Keys are kept for 7 days.
- The same key with a different request is refused (`idempotency_mismatch`); a retry while the first call is still running is told to wait (`in_progress`).
- GEOboom also checks the thing itself, whatever the key: an identical reply on the same thread within 24 hours is refused, and so is a reply when a newer message arrived than `seenMessageId`.

Some operations ask before they commit: `campaigns.resume` and `drafts.send` answer with the cost first when there is one, and go ahead when called again with it agreed.

## Long work

`prospecting.run` returns at once with a `jobId`. Follow it with `jobs.get`, which says queued, running, done or failed, and read the run's counters with `prospecting.latestRun`.

## Limits and errors

Each key may call each operation 600 times a minute for reads, 120 for writes and 30 for spending and sending, and an organisation 3000 times a minute in all. Past that, calls are refused with `429` and a `Retry-After` header.

A refusal is a [problem document](https://www.rfc-editor.org/rfc/rfc9457) with a stable `code`, a `detail` written for whoever reads it, and a `requestId`. [Every code](https://www.geoboom.io/docs/api/errors) is explained, with what to do about it.

## Versions

The API only grows within v1: operations and fields are added, never renamed or removed while in use. A value described as an open set may gain new members, so treat one you do not know as "other".


## Operations

### Organisation

Who you are acting for: credits, activation, mailboxes.

#### org.get

`GET /v1/org` · MCP tool `org_get` · scope `read` · effect `read`

This organisation: name, whether it is activated, its default writing language, its credits (balance, reserved by scheduled outreach, available) and whether sending is paused for billing, and how many mailboxes it sends from.

Returns: `id`, `name`, `slug`, `activated`, `defaultLanguage`, `credits`, `paused`, `mailboxes`.

### Projects

One per brand being promoted, with its budget and the mailboxes it sends from.

#### projects.list

`GET /v1/projects` · MCP tool `projects_list` · scope `read` · effect `read`

List this organisation's projects — one per brand being promoted — with outreach counts: URLs, publishers written to, replies, deals, live placements, threads needing action, and this month's budget.

Returns: `rows`, `totals`.

#### projects.get

`GET /v1/projects/{projectId}` · MCP tool `projects_get` · scope `read` · effect `read`

One project's facts (brand, site, pitch, location), its budget, and which mailboxes it sends from.

Inputs:

- `projectId` (string (uuid), required)

Returns: `id`, `name`, `brandName`, `brandUrl`, `brandContext`, `pitchType`, `clientLocation`, `postalAddress`, `creditAllowance`, `mailboxes`.

#### projects.create

`POST /v1/projects` · MCP tool `projects_create` · scope `campaigns:write` · effect `write`

Make a project for a client brand. Every mailbox of the organisation is enabled for it; its site is crawled once. Make a campaign in it next.

Inputs:

- `name` (string, up to 200, required)
- `brandName` (string, up to 200, required)
- `brandUrl` (string, up to 2000)
- `brandContext` (string, up to 10000)
- `pitchType` ("exchange" | "exchange_or_paid" | "paid") — Default "exchange_or_paid".
- `clientLocation` (string, up to 200)
- `postalAddress` (string, up to 1000)

Returns: `id`, `name`, `brandName`, `brandUrl`, `brandContext`, `pitchType`, `clientLocation`, `postalAddress`, `creditAllowance`, `mailboxes`.

#### projects.update

`PATCH /v1/projects/{projectId}` · MCP tool `projects_update` · scope `campaigns:write` · effect `write`

Change a project's facts: name, brand, site, context, pitch type, location, address. Only the fields sent change.

Inputs:

- `projectId` (string (uuid), required)
- `name` (string, up to 200)
- `brandName` (string, up to 200)
- `brandUrl` (string, up to 2000)
- `brandContext` (string, up to 10000)
- `pitchType` ("exchange" | "exchange_or_paid" | "paid")
- `clientLocation` (string, up to 200)
- `postalAddress` (string, up to 1000)

Returns: `id`, `name`, `brandName`, `brandUrl`, `brandContext`, `pitchType`, `clientLocation`, `postalAddress`, `creditAllowance`, `mailboxes`.

#### projects.setAllowance

`POST /v1/projects/{projectId}/allowance` · MCP tool `projects_setAllowance` · scope `prospecting:spend` · effect `write`

Set the whole credits a month a project may commit to new publishers; null is the default.

Inputs:

- `projectId` (string (uuid), required)
- `credits` (number | null, required)

Returns: `creditAllowance`.

#### projects.setMailboxes

`PUT /v1/projects/{projectId}/mailboxes` · MCP tool `projects_setMailboxes` · scope `campaigns:write` · effect `write`

Replace the set of mailboxes a project sends from, with the role each sender signs with. Mailboxes left out stop sending for this project.

Inputs:

- `projectId` (string (uuid), required)
- `mailboxes` (array of object, required)
- `mailboxes[].id` (string (uuid), required)
- `mailboxes[].senderTitle` (string, up to 200) — Default "".

Returns: `mailboxes`.

### Campaigns

Groups of prospect URLs pitched together: settings, launching, pausing, budgets.

#### campaigns.get

`GET /v1/campaigns/{campaignId}` · MCP tool `campaigns_get` · scope `read` · effect `read`

One campaign's settings (name, kind, pitch, templates, mailboxes, send rules, budget, paused) and the templates and mailboxes it may be set to.

Inputs:

- `campaignId` (string (uuid), required)

Returns: `id`, `projectId`, `name`, `kind`, `paused`, `launchedAt`, `archived`, `pitch`, `templates`, `mailboxIds`, `sendRules`, `excludeCompetitors`, `autoFilter`, `autoSchedule`, `rankBy`, `creditAllowance`, `options`, `followUpGapDays`.

#### campaigns.list

`GET /v1/projects/{projectId}/campaigns` · MCP tool `campaigns_list` · scope `read` · effect `read`

List a project's campaigns (groups of prospect URLs pitched together) with their progress: URLs, publishers, emails sent and to send, replies, deals, budget, today's sending share, and daily output for the last days.

Inputs:

- `projectId` (string (uuid), required)

Returns: `rows`, `days`.

#### campaigns.update

`PATCH /v1/campaigns/{campaignId}` · MCP tool `campaigns_update` · scope `campaigns:write` · effect `write`

Change a campaign's settings: name, kind, pitch type, templates, mailboxes, send rules, competitor exclusion, auto-filter, ranking, archived. Only the fields sent change. Returns the settings as they now are.

Inputs:

- `campaignId` (string (uuid), required)
- `name` (string, up to 200)
- `kind` ("links" | "geo")
- `pitchType` ("exchange" | "exchange_or_paid" | "paid" | null) — What it offers publishers; null follows the project. Changes which templates auto mode sends
- `templateMode` ("auto" | "manual")
- `templateIds` (array of string (uuid)) — The manual list, in the order a batch deals them; used when templateMode is manual
- `mailboxIds` (array of string (uuid)) — Mailboxes it sends from, of the project's; empty means all
- `sendRules` (object)
- `sendRules.publisherLimit` (number | null) — Most people written to at one publisher, 1–50
- `sendRules.publisherGapDays` (number | null) — Days between people at one publisher, 0–365; null is the default
- `sendRules.includeCatchAll` (boolean)
- `sendRules.donorPageLimit` (number | null)
- `excludeCompetitors` (boolean | null) — null follows the pitch: on for paid
- `archived` (boolean)
- `autoFilter` (boolean) — Decide undecided URLs by the campaign's rules as facts arrive
- `rankBy` (object) — A column key from the import, `rank`, or `position`
- `rankBy.key` (string, required)
- `rankBy.dir` ("asc" | "desc", required)

Returns: `id`, `projectId`, `name`, `kind`, `paused`, `launchedAt`, `archived`, `pitch`, `templates`, `mailboxIds`, `sendRules`, `excludeCompetitors`, `autoFilter`, `autoSchedule`, `rankBy`, `creditAllowance`.

#### campaigns.setAllowance

`POST /v1/campaigns/{campaignId}/allowance` · MCP tool `campaigns_setAllowance` · scope `prospecting:spend` · effect `write`

Set the whole credits a month a campaign may commit to new publishers; null is the default.

Inputs:

- `campaignId` (string (uuid), required)
- `credits` (number | null, required)

Returns: `creditAllowance`.

#### campaigns.setAutoSchedule

`POST /v1/campaigns/{campaignId}/auto-schedule` · MCP tool `campaigns_setAutoSchedule` · scope `prospecting:spend` · effect `write`

Turn automatic scheduling of a campaign's fits on or off.

Inputs:

- `campaignId` (string (uuid), required)
- `autoSchedule` (boolean, required)

Returns: `autoSchedule`.

#### campaigns.pause

`POST /v1/campaigns/{campaignId}/pause` · MCP tool `campaigns_pause` · scope `campaigns:write` · effect `write`

Pause a campaign: nothing more is sent from it until it is resumed. Research carries on and nothing queued is lost; replies still arrive. Pausing a paused campaign changes nothing.

Inputs:

- `campaignId` (string (uuid), required)

Returns: `paused`, `held`.

#### campaigns.resume

`POST /v1/campaigns/{campaignId}/resume` · MCP tool `campaigns_resume` · scope `mail:send` · effect `spend`

Launch or resume a campaign. If resuming commits credits, the first call answers with the cost and the credit picture instead; call again with that cost as agreedCost to go ahead.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `campaignId` (string (uuid), required)
- `agreedCost` (number) — The cost a previous call answered with, to go ahead

#### campaigns.create

`POST /v1/projects/{projectId}/campaigns` · MCP tool `campaigns_create` · scope `campaigns:write` · effect `write`

Make a campaign in a project. It starts paused, with no URLs; import into it, then launch it in the app.

Inputs:

- `projectId` (string (uuid), required)
- `name` (string, up to 200) — Default "".
- `kind` ("links" | "geo") — links: placements; geo: answers in AI engines Default "links".
- `creditAllowance` (number | null) — Whole credits a month it may commit; null is the default
- `excludeCompetitors` (boolean) — Leave out publishers whose own site is a competitor

Returns: `id`, `projectId`, `name`, `kind`, `paused`, `launchedAt`, `archived`, `pitch`, `templates`, `mailboxIds`, `sendRules`, `excludeCompetitors`, `autoFilter`, `autoSchedule`, `rankBy`, `creditAllowance`.

### Prospecting

Where a campaign's prospects come from: keywords, AI answers' citations, SE Ranking, or your own list.

#### prospecting.get

`GET /v1/campaigns/{campaignId}/prospecting` · MCP tool `prospecting_get` · scope `read` · effect `read`

How a campaign gets its prospects: which source is live (manual, seranking, keywords or prompts) and each source's setup and last run. Only the live source adds prospects on its schedule.

Inputs:

- `campaignId` (string (uuid), required)

Returns: `mode`, `manual`, `seranking`, `keywords`, `prompts`.

#### prospecting.latestRun

`GET /v1/campaigns/{campaignId}/prospecting/runs/latest` · MCP tool `prospecting_latestRun` · scope `read` · effect `read`

A campaign's newest prospecting run, with its progress counters. Pass `after` (startedAfter from prospecting.run) to get only the run you started: null means it has not begun yet. Finished when finishedAt is set.

Inputs:

- `campaignId` (string (uuid), required)
- `after` (string)

Returns: `run`.

#### prospecting.saveKeywords

`PUT /v1/campaigns/{campaignId}/prospecting/keywords` · MCP tool `prospecting_saveKeywords` · scope `campaigns:write` · effect `write`

Set up a campaign's keyword source: up to 1000 keywords whose search results are read for prospects, how deep to read (serpDepth 10–100), how many candidates to keep (topN 10–5000), how often to run on its own (off, weekly, monthly) and the market. Replaces the previous list. Running it is prospecting.run.

Inputs:

- `campaignId` (string (uuid), required)
- `keywords` (string | array of string, up to 500, required) — Keywords: an array, or one per line
- `serpDepth` (number) — Default 20.
- `topN` (number) — Default 500.
- `schedule` (string) — Default "off".
- `market` (string) — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US".
- `languageCode` (string, up to 10) — Default "en".

Returns: `count`.

#### prospecting.setMode

`PUT /v1/campaigns/{campaignId}/prospecting/mode` · MCP tool `prospecting_setMode` · scope `campaigns:write` · effect `write`

Choose which source adds prospects to a campaign on its schedule: manual (nobody), seranking, keywords or prompts. The source must be set up first. Other sources keep their setup.

Inputs:

- `campaignId` (string (uuid), required)
- `mode` (string, required)

Returns: `mode`.

#### prospecting.savePrompts

`PUT /v1/campaigns/{campaignId}/prospecting/prompts` · MCP tool `prospecting_savePrompts` · scope `campaigns:write` · effect `write`

Set up a campaign's prompt source: up to 500 questions put to AI answer engines (chatgpt), whose cited pages become prospects; how many to keep (topN 10–5000), how far back the answer count looks (windowDays 1–365), how often to run on its own (off, daily, weekly, monthly) and the market. Replaces the previous list. Running it is prospecting.run.

Inputs:

- `campaignId` (string (uuid), required)
- `prompts` (string | array of string, up to 500, required) — Prompts: an array, or one per line
- `engines` (array of string) — Default [].
- `topN` (number) — Default 500.
- `windowDays` (number) — Default 30.
- `schedule` (string) — Default "off".
- `market` (string) — A market code: US, GB, CA, AU, DE, FR, ES, UA. Anything else means US. Default "US".
- `languageCode` (string, up to 10) — Default "en".

Returns: `count`.

#### prospecting.run

`POST /v1/campaigns/{campaignId}/prospecting/runs` · MCP tool `prospecting_run` · scope `prospecting:spend` · effect `spend`

Run a campaign's keyword or prompt source now: search results or AI answers are bought, their pages scored, and the best become prospects to decide on. Returns at once; follow it with jobs.get (jobId) and prospecting.latestRun (after = startedAfter). One run at a time per campaign.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `campaignId` (string (uuid), required)
- `source` ("keywords" | "prompts", required) — Which source to run; it need not be the live one

Returns: `jobId`, `startedAfter`.

### Prospects

A campaign's URLs: importing them, deciding which fit, and the auto-filter.

#### prospects.planAutoFilter

`GET /v1/campaigns/{campaignId}/auto-filter` · MCP tool `prospects_planAutoFilter` · scope `read` · effect `read`

What the auto-filter would decide for a campaign's undecided URLs: how many become fits, how many are ruled out and by which rule, and how many it cannot decide yet and why.

Inputs:

- `campaignId` (string (uuid), required)

Returns: `undecided`, `fit`, `notFit`, `leftAlone`, `drFloor`, `ownDomain`, `ownDomainRating`, `competitors`.

#### prospects.list

`GET /v1/campaigns/{campaignId}/prospects` · MCP tool `prospects_list` · scope `read` · effect `read`

A campaign's prospect URLs, filtered by where they stand (undecided, fit, not_fit, scheduled, all_fit, all), most valuable first. Each row says whether its verdict can still be changed.

Inputs:

- `campaignId` (string (uuid), required)
- `state` (string) — One of undecided, fit, not_fit, scheduled, all_fit, all. Anything else, or nothing, means undecided.
- `sort` (string) — One of value, position, dr. Anything else, or nothing, means value.
- `page` (integer 1–9007199254740991)
- `size` (integer 1–100)

Returns: `rows`, `total`, `counts`, `applied`.

#### prospects.autoFilter

`POST /v1/campaigns/{campaignId}/auto-filter` · MCP tool `prospects_autoFilter` · scope `campaigns:write` · effect `write`

Decide a campaign's undecided URLs by its rules (see planAutoFilter). URLs missing a fact stay undecided, and the fact is asked for; run it again later to decide them.

Inputs:

- `campaignId` (string (uuid), required)

Returns: `fit`, `notFit`, `asked`.

#### prospects.markCompetitor

`POST /v1/campaigns/{campaignId}/competitors` · MCP tool `prospects_markCompetitor` · scope `campaigns:write` · effect `write`

Say whether these URLs' publishers are the client's competitors, overruling the automatic check. Verdicts do not change; the auto-filter uses the answer for URLs not decided yet.

Inputs:

- `campaignId` (string (uuid), required)
- `targetIds` (array of string (uuid), required)
- `competitor` (boolean, required)

Returns: `domains`.

#### prospects.import

`POST /v1/campaigns/{campaignId}/prospects` · MCP tool `prospects_import` · scope `campaigns:write` · effect `write`

Add URLs to a campaign: `urls` as a list, or `csv` as a table whose other columns are kept (the URL column, rank and goal are inferred unless `mapping` says). URLs already on the campaign are skipped; ones the project already holds join it. New pages start being read at once.

Inputs:

- `campaignId` (string (uuid), required)
- `urls` (array of string, up to 2000)
- `csv` (string, up to 4000000) — Comma, tab or semicolon separated, with a header row
- `mapping` (array of object) — How to take each column of `csv`; inferred when absent
- `mapping[].index` (integer 0–9007199254740991, required)
- `mapping[].header` (string, required)
- `mapping[].key` (string, required)
- `mapping[].role` ("url" | "goal" | "rank" | "custom" | "ignore", required)
- `mapping[].type` ("number" | "text" | "date", required)
- `mapping[].samples` (array of string) — Default [].
- `filename` (string, up to 200)

Returns: `added`, `joinedFromProject`, `duplicatesInCampaign`, `duplicatesInFile`, `invalid`, `queued`, `dropped`, `droppedBy`, `mapping`.

#### prospects.remove

`POST /v1/campaigns/{campaignId}/prospects/remove` · MCP tool `prospects_remove` · scope `campaigns:write` · effect `write`

Take URLs off a campaign. Only the campaign's membership goes; the page, its contacts and its messages stay, and importing the URL again brings it back.

Inputs:

- `campaignId` (string (uuid), required)
- `targetIds` (array of string (uuid), required)

Returns: `removed`.

#### prospects.skip

`POST /v1/campaigns/{campaignId}/skip` · MCP tool `prospects_skip` · scope `campaigns:write` · effect `outward`

Stop everything still to go to these URLs from a campaign: unsent pitches are skipped and follow-ups of sent ones withdrawn. Threads they answered are left alone.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `campaignId` (string (uuid), required)
- `targetIds` (array of string (uuid), required)

Returns: `skipped`, `withdrawn`.

#### prospects.setVerdict

`POST /v1/campaigns/{campaignId}/verdicts` · MCP tool `prospects_setVerdict` · scope `campaigns:write` · effect `write`

Mark a campaign's URLs a fit, not a fit, or undecided again (null). A fit is searched for contacts. URLs already on the queue keep their verdict and are counted as locked.

Inputs:

- `campaignId` (string (uuid), required)
- `targetIds` (array of string (uuid), required)
- `verdict` ("fit" | "not_fit" | null, required)

Returns: `decided`, `locked`, `notOnCampaign`.

### Jobs

Long work started by another operation, and where it is.

#### jobs.get

`GET /v1/jobs/{jobId}` · MCP tool `jobs_get` · scope `read` · effect `read`

Where a piece of queued work is: queued, running, done or failed. Operations that start long work (prospecting.run) return its jobId. A failed job is not retried further; what it produced, if anything, is read from the operation that started it.

Inputs:

- `jobId` (string (uuid), required)

Returns: `id`, `type`, `state`, `attempts`, `createdAt`.

### Drafts

Messages waiting to be sent: first emails and replies.

#### drafts.list

`GET /v1/drafts` · MCP tool `drafts_list` · scope `read` · effect `read`

Messages waiting to be sent, newest first (at most 200). A `cold` draft is a first email: send it with drafts.sendFirstContact from a mailbox; any other with drafts.send.

Inputs:

- `projectId` (string (uuid))
- `campaignId` (string (uuid))

Returns: `rows`.

#### drafts.previewFirstContact

`GET /v1/drafts/{messageId}/first-contact` · MCP tool `drafts_previewFirstContact` · scope `read` · effect `read`

What a cold draft would look like sent as a first email from a mailbox — exactly the text, the follow-ups — and anything that would stop it (suppression, a bad address, a mailbox not ready).

Inputs:

- `messageId` (string (uuid), required)
- `inboxId` (string (uuid), required)

Returns: `ok`, `blockers`, `warnings`, `from`, `to`, `subject`, `body`, `followUps`, `followUpDays`.

#### drafts.update

`PATCH /v1/drafts/{messageId}` · MCP tool `drafts_update` · scope `campaigns:write` · effect `write`

Edit a waiting draft: subject, body, its follow-ups, and who it goes to. Fields left out stay as they are.

Inputs:

- `messageId` (string (uuid), required)
- `subject` (string, up to 500)
- `bodyText` (string, up to 50000)
- `followUps` (array of object)
- `followUps[].text` (string, up to 50000, required)
- `followUps[].delayDays` (string | number | null, required)
- `followUps[].subject` (string, up to 500 | null, required)
- `to` (array of string, up to 320)

Returns: `messageId`.

#### drafts.discard

`POST /v1/drafts/{messageId}/discard` · MCP tool `drafts_discard` · scope `campaigns:write` · effect `write`

Discard a waiting draft without sending it. It stays on the URL page; the queue moves on.

Inputs:

- `messageId` (string (uuid), required)

Returns: `messageId`.

#### drafts.sendFirstContact

`POST /v1/drafts/{messageId}/first-contact` · MCP tool `drafts_sendFirstContact` · scope `mail:send` · effect `outward`

Send a cold draft as a first email from a mailbox, with its follow-ups. Queued: the mailbox's schedule decides when it leaves. Refused if anything in drafts.previewFirstContact would stop it.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `messageId` (string (uuid), required)
- `inboxId` (string (uuid), required)

Returns: `queued`, `to`, `from`, `followUpDays`.

#### drafts.send

`POST /v1/drafts/{messageId}/send` · MCP tool `drafts_send` · scope `mail:send` · effect `outward`

Send a waiting draft into its thread. A cold draft (a first email) is refused: use drafts.sendFirstContact. A draft that costs credits answers `confirm` with the cost first; call again with costConfirmed to send it.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `messageId` (string (uuid), required)
- `costConfirmed` (boolean) — Default false.

### Inbox

Conversations with publishers: reading and replying.

#### threads.list

`GET /v1/threads` · MCP tool `threads_list` · scope `read` · effect `read`

List inbox threads with publishers, newest first: who each is with, whether it is owed an answer (need_action) or a chase, the page pitched, where a deal stands, and the suggested next step. Also returns how many threads are behind each tab. Filter by tab, project, campaign, contact, or a search.

Inputs:

- `tab` (string) — One of all, need_action, replied, sending, client, inbound. Anything else, or nothing, means all.
- `projectId` (string (uuid) | null)
- `campaignId` (string (uuid) | null)
- `contactId` (string (uuid) | null)
- `q` (string | null) — Matches names, addresses, company, the pitched page's domain or URL, and the subject
- `page` (integer 1–9007199254740991)
- `size` (integer 1–100)

Returns: `rows`, `total`, `counts`.

#### threads.get

`GET /v1/threads/{conversationId}` · MCP tool `threads_get` · scope `read` · effect `read`

One inbox thread and all its messages, oldest first, with sender, recipients, subject, plain text, and whether each was an automatic reply. Names the thread by conversationId and topicKey, as threads.list returns them.

Inputs:

- `conversationId` (string (uuid), required)
- `topicKey` (string, required) — As threads.list returns it; URL-encode it

Returns: `thread`, `messages`.

#### threads.reply

`POST /v1/threads/{conversationId}/replies` · MCP tool `threads_reply` · scope `mail:send` · effect `outward`

Reply on a thread. Send `seenMessageId`, the newest message you read: if a newer one has arrived the reply is refused, to be read and answered instead. Others on the thread may be included by address. An identical reply on the same thread within 24 hours is refused.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `conversationId` (string (uuid), required)
- `topicKey` (string, required)
- `subject` (string, up to 500) — Default "".
- `bodyText` (string, up to 50000, required)
- `alsoInclude` (array of string, up to 320) — Default [].
- `suggestionId` (string (uuid) | null)
- `seenMessageId` (string (uuid) | null)
- `attachments` (array of string (uuid)) — Default [].

Returns: `messageId`.

#### threads.startTopic

`POST /v1/threads/{conversationId}/topics` · MCP tool `threads_startTopic` · scope `mail:send` · effect `outward`

Start a new subject with somebody already in a conversation. Refused if a thread with that subject exists: reply there instead.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `conversationId` (string (uuid), required)
- `subject` (string, up to 500, required)
- `bodyText` (string, up to 50000, required)
- `attachments` (array of string (uuid)) — Default [].
- `toAddresses` (array of string, up to 320) — Default [].
- `dealId` (string (uuid) | null)

Returns: `topicKey`.

### Contacts

People at publishers.

#### contacts.list

`GET /v1/contacts` · MCP tool `contacts_list` · scope `read` · effect `read`

List people at publishers this organisation has found or written to, with how warm each is, the sites they answer for, and whether a thread with them is owed an answer. Search by name, address or company; optionally narrow to one project.

Inputs:

- `projectId` (string (uuid) | null) — Only people at publishers with URLs in this project
- `q` (string | null) — Matches part of the name, address or company
- `standing` (string) — One of warm, reaching_out, all. Anything else, or nothing, means warm.
- `page` (integer 1–9007199254740991)
- `size` (integer 1–100)

Returns: `rows`, `total`, `applied`.

#### contacts.get

`GET /v1/contacts/{contactId}` · MCP tool `contacts_get` · scope `read` · effect `read`

Everything known about one person at a publisher: name, address and whether it is verified, role, how warm they are and why, their employer, the sites they answer for with our URLs on each, their threads (and which are owed an answer), notes and messages.

Inputs:

- `contactId` (string (uuid), required)

Returns: `contact`, `employer`, `domains`, `threads`, `history`, `messages`.

### Publishers

Sites, their terms, your notes, and who not to approach.

#### publishers.list

`GET /v1/publishers` · MCP tool `publishers_list` · scope `read` · effect `read`

List publishers (sites) this organisation has pages or URLs for, with their authority, people, outreach counts and terms. Filter by who is in contact, what they sell and a search on the domain; optionally narrow to one project.

Inputs:

- `projectId` (string (uuid) | null) — Only publishers with URLs in this project
- `q` (string | null) — Matches part of the domain or the company name
- `standing` (string) — One of in_contact, reaching_out, all. Anything else, or nothing, means in_contact.
- `stance` (string) — One of any, exchange, paid, both, neither, not_selling. Anything else, or nothing, means any.
- `kind` (string) — One of any, listicle_insert, link_insert, guest_post, press_release, other. Anything else, or nothing, means any.
- `sort` (string) — One of recent, dr, contacts, outreach, campaign_urls, pages, mentions, competitors. Anything else, or nothing, means dr.
- `page` (integer 1–9007199254740991)
- `size` (integer 1–100)

Returns: `rows`, `total`, `applied`.

#### publishers.get

`GET /v1/publishers/{domain}` · MCP tool `publishers_get` · scope `read` · effect `read`

Everything known about one publisher, by its site's domain: authority and traffic, the quality verdict, what they sell and their stated terms, private notes, the people there, pages and URLs held on the site, recent messages, and outreach standing.

Inputs:

- `domain` (string, up to 253, required)
- `projectId` (string (uuid) | null)

Returns: `domain`, `company`, `logo`, `domainRating`, `quality`, `metricsAt`, `label`, `sells`, `siteKind`, `publisher`, `standing`, `pages`, `people`, `messages`.

#### publishers.setApproachable

`POST /v1/publishers/{domain}/do-not-approach` · MCP tool `publishers_setApproachable` · scope `campaigns:write` · effect `outward`

Mark a publisher do-not-approach, or allow approaches again. Marking drops every pitch still queued for their site and withdraws sequences already handed to the mail provider, so no follow-up goes out; un-marking puts the dropped pitches back in the queue but does not re-add withdrawn sequences.

Requires an `Idempotency-Key` header (HTTP) or `idempotency_key` argument (MCP).

Inputs:

- `domain` (string, up to 253, required)
- `doNotApproach` (boolean, required)

Returns: `domain`, `doNotApproach`, `queueChanged`, `withdrawn`.

#### publishers.saveNotes

`POST /v1/publishers/{domain}/notes` · MCP tool `publishers_saveNotes` · scope `campaigns:write` · effect `write`

Replace this organisation's private notes on a publisher (their site's domain). Empty text clears them. Notes are never shown to the publisher.

Inputs:

- `domain` (string, up to 253, required)
- `notes` (string, required)

Returns: `domain`, `notes`.

### Deals

What was agreed: prices, payment, placements and whether they are still live.

#### deals.list

`GET /v1/deals` · MCP tool `deals_list` · scope `read` · effect `read`

This organisation's deals, newest activity first: who with, what each side gives, the price, and the state read off the placements (agreed, partly_live, live, broken or archived. An open set.). Filter by project, state, or text.

Inputs:

- `projectId` (string (uuid))
- `state` (string)
- `q` (string, up to 200)

Returns: `rows`.

#### deals.get

`GET /v1/deals/{dealId}` · MCP tool `deals_get` · scope `read` · effect `read`

One deal: its terms, payment details, every placement with what the daily check last saw, the threads it came from (conversationId and topicKey, for threads.get), and its history.

Inputs:

- `dealId` (string (uuid), required)

Returns: `id`, `title`, `state`, `projectId`, `project`, `publisherDomain`, `contactId`, `who`, `contactEmail`, `oursGives`, `theirsGives`, `oursAmountCents`, `theirsAmountCents`, `currency`, `oursInvoiceRef`, `oursPaymentTerms`, `oursAmountExcludesTax`, `oursPaidAt`, `owed`, `notes`, `archivedAt`, `createdAt`, `updatedAt`, `placements`, `threads`, `history`.

#### deals.create

`POST /v1/deals` · MCP tool `deals_create` · scope `deals:write` · effect `write`

Write a deal down: who it is with (email; a new address becomes a contact), what each side gives (placement or payment), and the thread it came from. Price it with deals.update and add what goes where with deals.addPlacement.

Inputs:

- `projectId` (string (uuid), required)
- `email` (string, required)
- `title` (string, up to 300 | null)
- `oursGives` ("placement" | "payment") — What we hand over: placement or payment Default "placement".
- `theirsGives` ("placement" | "payment") — What they hand over: placement or payment Default "placement".
- `notes` (string, up to 20000 | null)
- `thread` (object | null)
- `thread.conversationId` (string (uuid), required)
- `thread.topicKey` (string, required)

Returns: `id`.

#### deals.update

`PATCH /v1/deals/{dealId}` · MCP tool `deals_update` · scope `deals:write` · effect `write`

Change a deal's terms: what each side gives and pays (cents, with currency), invoice and payment details, and mark it paid (oursPaidAt) or not (null). Only the fields sent change. Placements have their own operations.

Inputs:

- `dealId` (string (uuid), required)
- `title` (string, up to 300 | null)
- `publisherDomain` (string, up to 253 | null)
- `contactId` (string (uuid) | null)
- `oursGives` ("placement" | "payment")
- `theirsGives` ("placement" | "payment")
- `oursAmountCents` (integer 0–9007199254740991 | null) — What we pay, in cents
- `theirsAmountCents` (integer 0–9007199254740991 | null) — What they pay, in cents
- `currency` (string | null)
- `notes` (string, up to 20000 | null)
- `oursInvoiceRef` (string, up to 500 | null)
- `oursPaymentMethod` (string, up to 200 | null)
- `oursPaymentTerms` (string, up to 500 | null)
- `oursAmountExcludesTax` (boolean | null)
- `oursPaidAt` (string (date-time) | null) — When we paid them; null to mark not paid
- `oursInvoiceAttachmentId` (string (uuid) | null)

Returns: `id`.

#### deals.archive

`POST /v1/deals/{dealId}/archive` · MCP tool `deals_archive` · scope `deals:write` · effect `write`

Archive a deal (no longer tracked or checked) or reopen it.

Inputs:

- `dealId` (string (uuid), required)
- `archived` (boolean, required)

Returns: `id`, `archived`.

#### deals.addPlacement

`POST /v1/deals/{dealId}/placements` · MCP tool `deals_addPlacement` · scope `deals:write` · effect `write`

Add what goes where to a deal: a link on a page (ours: on our site; theirs: on theirs), its anchor, rel and position, or added words. Marked agreed until it is live. GEOboom checks live placements daily.

Inputs:

- `dealId` (string (uuid), required)
- `side` ("ours" | "theirs", required) — ours: we place them on our page; theirs: they place us on theirs
- `kind` ("link_insertion" | "added_text") — link_insertion: a link into existing words; added_text: new words with links Default "link_insertion".
- `hostUrl` (string, up to 2000 | null) — The page it goes on
- `targetUrl` (string, up to 2000 | null) — Where the link points
- `anchor` (string, up to 500 | null)
- `rel` (string, up to 100 | null) — e.g. nofollow, sponsored; empty for a followed link
- `body` (string, up to 50000 | null) — The agreed words, for added_text
- `bodyFormat` ("text" | "markdown" | null) — markdown keeps the links inside the words
- `position` (integer 1–9007199254740991 | null) — Our place in a listicle
- `textBy` ("us" | "them" | null) — Who writes the words
- `status` ("agreed" | "live" | "removed") — agreed: settled, not up yet; live: on the page; removed: was up, is not Default "agreed".
- `promisedAt` (string, up to 40 | null) — The date it was promised for, YYYY-MM-DD
- `notes` (string, up to 20000 | null)

Returns: `id`.

#### deals.updatePlacement

`PATCH /v1/placements/{placementId}` · MCP tool `deals_updatePlacement` · scope `deals:write` · effect `write`

Change a placement: its terms, or its status (agreed, live, removed). Setting a status withdraws what the daily check concluded about the old one; the next check looks again. Only the fields sent change.

Inputs:

- `placementId` (string (uuid), required)
- `kind` ("link_insertion" | "added_text") — link_insertion: a link into existing words; added_text: new words with links
- `hostUrl` (string, up to 2000 | null) — The page it goes on
- `targetUrl` (string, up to 2000 | null) — Where the link points
- `anchor` (string, up to 500 | null)
- `rel` (string, up to 100 | null) — e.g. nofollow, sponsored; empty for a followed link
- `body` (string, up to 50000 | null) — The agreed words, for added_text
- `bodyFormat` ("text" | "markdown" | null) — markdown keeps the links inside the words
- `position` (integer 1–9007199254740991 | null) — Our place in a listicle
- `textBy` ("us" | "them" | null) — Who writes the words
- `status` ("agreed" | "live" | "removed") — agreed: settled, not up yet; live: on the page; removed: was up, is not
- `promisedAt` (string, up to 40 | null) — The date it was promised for, YYYY-MM-DD
- `notes` (string, up to 20000 | null)

Returns: `id`, `dealId`.

### Blurbs

Our entries for publishers' articles, and the copy publishers send for the project's own site.

#### blurbs.list

`GET /v1/blurbs` · MCP tool `blurbs_list` · scope `read` · effect `read`

Blurbs, newest first: our entries written for publishers' articles (side ours) and the copy publishers sent for our project's site, read out of their threads (side theirs). Each with its words, its table line, the article it goes into and the thread it belongs to. Filter by project, by thread (conversationId, with topicKey to narrow to one subject), by side, or by text in the address or words.

Inputs:

- `projectId` (string (uuid))
- `conversationId` (string (uuid))
- `topicKey` (string) — With conversationId: one subject of that conversation
- `side` ("ours" | "theirs")
- `q` (string, up to 200) — Text in the article address, the words or the publisher's domain
- `limit` (integer 1–200)

Returns: `rows`.

#### blurbs.get

`GET /v1/blurbs/{blurbId}` · MCP tool `blurbs_get` · scope `read` · effect `read`

One blurb in full: its words and table line, what the model first wrote (ours) and what it was asked, its link and anchor, what the model could not fill (gaps), where the words came from in the thread (theirs: messages, attachments, Google Docs), how the thread changed them, and every link shared with the publisher. A theirs blurb can be put on the project's WordPress site with sites.publish (blurbId).

Inputs:

- `blurbId` (string (uuid), required)

Returns: `id`, `side`, `projectId`, `conversationId`, `topicKey`, `hostUrl`, `authorDomain`, `body`, `tableRow`, `edited`, `author`, `createdAt`, `updatedAt`, `originalBody`, `originalTableRow`, `instructions`, `anchor`, `targetUrl`, `shape`, `gaps`, `sources`, `history`, `shares`.


## Errors

### invalid (400)

The input does not fit the operation: a missing or malformed field, a value out of range, or a guarded call without an idempotency key.

Read `detail`, which names the field. Fix the input; retrying unchanged gets the same answer.

### unauthorized (401)

No bearer token, or one that is unknown, revoked or expired.

Send `Authorization: Bearer <key or access token>`. An OAuth client refreshes its access token; a key that was revoked needs a new one from Settings → Integrations.

### no_credits (402)

The organisation does not have the credits this would commit.

Tell the person; an owner tops up in the app under Billing. Nothing was spent.

### forbidden (403)

The key or grant does not hold the scope this operation needs, or the operation is only for people in the app.

Ask an owner for a key with the scope (or re-authorise the connector and tick it). Members, keys, deleting and billing are never available through the API.

### grant_paused (403)

An owner paused this key or connection.

Stop and tell the person; it is resumed from Settings → Integrations.

### not_activated (403)

The organisation is on the waiting list and cannot create projects or send yet.

Reads work; the rest waits until GEOboom activates the organisation.

### not_found (404)

No such thing in this organisation, or no operation at that path. Another organisation's ids are not found, not forbidden.

Check the id came from this organisation's lists, and the path from the reference.

### conflict (409)

The state does not allow it now: a newer message arrived on the thread, a run is already going, or a first call with this idempotency key did not finish and whether it took effect is unknown.

Read `detail`. Look at the current state (the thread, the campaign) before acting again, with a new idempotency key if it was a guarded call.

### in_progress (409)

The first call with this idempotency key is still running.

Wait for `Retry-After` (2 seconds) and send the same call with the same key; you will get its answer.

### idempotency_mismatch (422)

This idempotency key was already used for a different request.

A new action needs a new key. Reuse a key only to retry the exact same call.

### rate_limited (429)

Too many calls a minute for this operation on this key, or for the organisation as a whole.

Wait for `Retry-After` and slow down. Limits are per key and operation: reads 600 a minute, writes 120, spending and sending 30.

### internal (500)

Something went wrong on our side.

Retry later; a guarded call is safe to retry with the same key. If it persists, write to support@geoboom.io with the `requestId`.
