# CommsHarbor — full API reference

> Generated from the catalog at https://commsharbor.com · build `074a2a11`
> 151 endpoints · 74 structures
> Short index: https://commsharbor.com/llms.txt · Spec: https://commsharbor.com/openapi.json · MCP: https://commsharbor.com/mcp

> Transactional email and permission-based marketing with tenant isolation.
> English is the default product language; the human UI is also available in pt-BR.

## How to read

- Every endpoint lists path, auth, parameters, body, response structure, errors and a call that runs.
- `Pagina<Canal>` is a reference: the fields are under **Structures**, at the end, once.
- `(optional)` on a field means it may be absent; `(may be null)` means it comes with a null value.
- Slice what you need: `https://commsharbor.com/llms-full.txt?prefix=/api/` returns only that branch.

## Authentication

- `credito` — Prepaid credit token in `Authorization: Bearer cred_…` (or the `X-Credito` header). Not an account: it is a bearer of balance.
- `none` — Public endpoint. No tenant data is returned.
- `session` — Bearer session or secure session cookie. No organization is implied.
- `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.
- `organization_template_write` — Active organization identity with template:write permission.
- `organization_messages_send` — Active organization identity with messages:send permission. Idempotency-Key is mandatory.
- `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.
- `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.
- `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.
- `aws_sns` — Amazon SNS signature, regional certificate URL and the exact configured TopicArn. This callback never accepts a user credential.
- `preference_capability` — Signed, expiring capability scoped to one organization and contact. No login is required and no email address is embedded in the token.

## Endpoints

## Discovery

### `GET /okf/:arquivo`

OKF bundle (Open Knowledge Format v0.1): markdown with frontmatter so an agent reads the whole product without parsing HTML.

- **URL:** `https://commsharbor.com/okf/:arquivo`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Path parameters**

- `arquivo` (string, required) — `index.md`, `sobre.md`, `api.md` or `faq.md`. e.g.: `index.md`.

**Response `200`**

`text/markdown`. Start at `/okf/index.md`, which lists the bundle.

**Errors**

- `404` — File outside the bundle.

**Example**

```sh
curl -s https://commsharbor.com/okf/index.md
```

### `GET /.well-known/:arquivo`

Machine discovery before the home page: `api-catalog` (RFC 9727, a linkset with the API and the MCP), `security.txt` (RFC 9116) and `mcp-registry-auth` (the official MCP registry key).

- **URL:** `https://commsharbor.com/.well-known/:arquivo`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Path parameters**

- `arquivo` (string, required) — `api-catalog`, `security.txt`, `mcp-registry-auth` or `apis.json`. e.g.: `api-catalog`.

**Response `200`**

`application/linkset+json` for the api-catalog; `text/plain` for the other two.

**Errors**

- `404` — Name outside the four published.

**Example**

```sh
curl -s https://commsharbor.com/.well-known/api-catalog
```

### `GET /apis.json`

APIs.json (apisjson.org, 0.19): the index APIs.io harvests — the API, the MCP, OpenAPI, guide and OKF bundle in one file. Also at `/.well-known/apis.json`.

- **URL:** `https://commsharbor.com/apis.json`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Response `200`**

`application/json` in the APIs.json 0.19 format: `apis[]` with `baseURL`, `humanURL` and `properties[]`.

**Example**

```sh
curl -s https://commsharbor.com/apis.json
```

### `GET /api/`

Discover the whole API: every endpoint, every auth mode and the MCP endpoint.

- **URL:** `https://commsharbor.com/api/`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Response `200`**

Structure: `ApiIndex`.

- `name` (string) — Product name.
- `description` (string) — What the product does, in one sentence.
- `build` (string) — Deployed commit.
- `environment` (string) — Which environment answered: `production`, `staging` or `local`.
- `base_url` (string) — Origin this API is served from.
- `docs` (object) — Links to llms.txt, llms-full.txt, openapi.json, the MCP endpoint and the human UI.
- `auth` (object) — Every authentication mode and how to obtain it.
- `endpoints` (object[]) — Every endpoint with method, path, auth, absolute URL and what it returns.
- `mcp` (object) — Remote MCP endpoint and transport.
- `mcp_tools` (string[]) — Name of every MCP tool.

### `GET /api/health`

Read liveness, environment and the commit currently deployed.

Smoke tests wait for their own commit to appear here instead of racing edge propagation.

- **URL:** `https://commsharbor.com/api/health`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Response `200`**

Structure: `Health`.

- `ok` (bool) — Always true when the Worker answers.
- `app` (string) — Product name.
- `build` (string) — Deployed commit; CI passes the short SHA at deploy time.
- `environment` (string) — Which environment answered.
- `timestamp` (string) — Response time (UTC, ISO-8601).

### `GET /mcp`

Inspect the remote MCP server card: transport, protocol and tool count.

`POST /mcp` speaks Streamable HTTP with JSON-RPC 2.0. The tools are the operations in this catalog; the MCP has no backend of its own.

- **URL:** `https://commsharbor.com/mcp`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Response `200`**

- `transport` (string) — How the server speaks — `streamable-http`.
- `protocol_version` (string) — MCP protocol version the server implements.
- `endpoint` (string) — Absolute URL to POST JSON-RPC to.
- `server` (object) — `name` and `version` of this server; the version is the deployed commit.
- `tools` (int) — How many tools the server exposes.
- `usage` (string) — One line saying how to call it.
- `api_index` (string) — The self-describing API index, for the operations behind the tools.

## Account

### `POST /api/auth/start`

Send a one-time login code to an email address.

- **URL:** `https://commsharbor.com/api/auth/start`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Body** (`application/json`)

- `email` (string, required) — Where to send the code.

**Body example**

```json
{
  "email": "owner@example.com"
}
```

**Response `200`**

- `sent` (bool) — Whether the message was accepted for delivery.
- `expires_in` (int) — Seconds until the code stops working.

**Errors**

- `400` — Missing or malformed email.
- `429` — Too many codes requested for this address.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/auth/start -H 'content-type: application/json' -d '{"email":"owner@example.com"}'
```

### `POST /api/auth/verify`

Exchange a one-time code for a session.

- **URL:** `https://commsharbor.com/api/auth/verify`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Body** (`application/json`)

- `email` (string, required) — The address the code was sent to.
- `code` (string, required) — The six digits from the email.

**Body example**

```json
{
  "email": "owner@example.com",
  "code": "123456"
}
```

**Response `200`**

- `user` (User) — The person who just signed in. → see `User` under **Structures**.
- `session_token` (string) — Bearer token for `Authorization`. It implies no organization on its own.

**Errors**

- `400` — Wrong or expired code.
- `429` — Too many attempts.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/auth/verify -H 'content-type: application/json' -d '{"email":"owner@example.com","code":"123456"}'
```

### `POST /api/auth/logout`

Revoke the session in use right now.

- **URL:** `https://commsharbor.com/api/auth/logout`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Response `200`**

Structure: `Ok`.

- `ok` (bool) — Always true — failures arrive as a 4xx/5xx status, never as `ok:false`.

**Errors**

- `401` — No session, or the session expired.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/auth/logout -H "Authorization: Bearer $TOKEN"
```

### `GET /api/me`

Read the profile, every membership and the platform role, if any.

This is how a client discovers which organizations it may pass in `X-Organization-Id`.

- **URL:** `https://commsharbor.com/api/me`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Response `200`**

- `user` (User) — The person behind the session. → see `User` under **Structures**.
- `profile` (Profile) — Personal preferences — they belong to the person, not to a tenant. → see `Profile` under **Structures**.
- `organizations` (Organization[]) — Every organization this person belongs to. → see `Organization` under **Structures**.
- `platform_role` (string, may be null) — Platform role, when one was explicitly granted. Owning a tenant grants nothing here.

**Errors**

- `401` — No session, or the session expired.

**Example**

```sh
curl -s https://commsharbor.com/api/me -H "Authorization: Bearer $TOKEN"
```

### `PATCH /api/me`

Update the display name or language of the current profile.

- **URL:** `https://commsharbor.com/api/me`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Body** (`application/json`)

- `display_name` (string) — Name shown in the interface.
- `locale` (string) — Preferred language, e.g. `en` or `pt-br`.

**Body example**

```json
{
  "display_name": "A. User",
  "locale": "en"
}
```

**Response `200`**

Structure: `Profile`.

- `display_name` (string, may be null) — Name shown in the interface.
- `locale` (string, may be null) — Preferred language, e.g. `en` or `pt-br`.

**Errors**

- `400` — No updatable field in the body.
- `401` — No session, or the session expired.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/me -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"locale":"pt-br"}'
```

## Organizations

### `GET /api/organizations`

List the organizations the current person belongs to.

- **URL:** `https://commsharbor.com/api/organizations`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Response `200`**

- `organizations` (Organization[]) — Every organization with a membership for this person. → see `Organization` under **Structures**.

**Errors**

- `401` — No session, or the session expired.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations -H "Authorization: Bearer $TOKEN"
```

### `POST /api/organizations`

Create one organization trial for a verified owner and a sending domain.

One trial per owner. The domain is registered here but not verified — DNS state is only ever observed, in the domains resource.

- **URL:** `https://commsharbor.com/api/organizations`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Body** (`application/json`)

- `name` (string, required) — Display name of the organization.
- `sending_domain` (string, required) — Domain the organization will send from.

**Body example**

```json
{
  "name": "Acme",
  "sending_domain": "example.com"
}
```

**Response `200`**

Structure: `Organization`.

- `id` (string) — Organization ID, used in every tenant route.
- `name` (string) — Display name.
- `sending_domain` (string, may be null) — Domain the organization sends from.
- `created_at` (string) — Creation time (UTC, ISO-8601).

**Errors**

- `400` — Missing name or domain.
- `401` — No session, or the session expired.
- `409` — This owner already has a trial organization.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"name":"Acme","sending_domain":"example.com"}'
```

### `GET /api/context`

Resolve which organization and role the current credential is acting as.

Read this before a write when you are not certain which tenant is active. Guessing is how data lands in the wrong organization.

- **URL:** `https://commsharbor.com/api/context`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Headers**

- `X-Organization-Id` (string, required) — Which organization to act in. Required with a human session; an API key determines its own and rejects a conflicting value.

**Response `200`**

Structure: `Identity`.

- `kind` (string) — How the identity was resolved.
- `organizationId` (string) — The active organization.
- `userId` (string, optional) — The person, when a session is in play.
- `email` (string, optional) — The person's e-mail, on a session.
- `sessionId` (string, optional) — Session identifier, on a session.
- `role` (string, optional) — Role inside that organization; sessions only.
- `organization` (object, optional) — `{ id, name, slug }` of the active organization; sessions only.
- `apiKeyId` (string, optional) — Which key answered, on an API key.
- `scopes` (string[], optional) — Granted scopes; present on an API key, which carries its own narrower set.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/context -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id`

Read one organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `Organization`.

- `id` (string) — Organization ID, used in every tenant route.
- `name` (string) — Display name.
- `sending_domain` (string, may be null) — Domain the organization sends from.
- `created_at` (string) — Creation time (UTC, ISO-8601).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id`

Update an organization's name.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — New display name.

**Body example**

```json
{
  "name": "Acme Global"
}
```

**Response `200`**

Structure: `Organization`.

- `id` (string) — Organization ID, used in every tenant route.
- `name` (string) — Display name.
- `sending_domain` (string, may be null) — Domain the organization sends from.
- `created_at` (string) — Creation time (UTC, ISO-8601).

**Errors**

- `400` — Empty name.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"name":"Acme Global"}'
```

### `GET /api/organizations/:organization_id/members`

List the members of an organization and their roles.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/members`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `members` (Membership[]) — Every member and the role they hold. → see `Membership` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/members -H "Authorization: Bearer $TOKEN"
```

### `PATCH /api/organizations/:organization_id/members/:user_id`

Change the role of a member who is not the owner.

The owner's role cannot be changed through this route — an organization that can lose its last owner is an organization nobody can administer.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/members/:user_id`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `user_id` (string, required) — Member user ID, as returned by the members listing.

**Body** (`application/json`)

- `role` (string, required) — Role to give the member from now on. Values: `admin`, `marketer`, `viewer`.

**Body example**

```json
{
  "role": "marketer"
}
```

**Response `200`**

Structure: `Membership`.

- `organization_id` (string) — The organization.
- `user_id` (string) — The member.
- `role` (string) — What the member may do.
- `created_at` (string) — When the membership started (UTC).

**Errors**

- `400` — Unknown role.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG/members/$USER -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"role":"marketer"}'
```

### `GET /api/organizations/:organization_id/invitations`

List invitations without their tokens.

The token is shown once, when the invitation is created. Listing never shows it again.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/invitations`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `invitations` (Invitation[]) — Invitations for this organization, without tokens. → see `Invitation` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/invitations -H "Authorization: Bearer $TOKEN"
```

### `POST /api/organizations/:organization_id/invitations`

Create an invitation and reveal its token exactly once.

Store the token now: this is the only response that carries it.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/invitations`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `email` (string, required) — Who to invite.
- `role` (string, required) — Role the invitation grants. Values: `admin`, `marketer`, `viewer`.

**Body example**

```json
{
  "email": "member@example.com",
  "role": "viewer"
}
```

**Response `200`**

Structure: `Invitation`.

- `id` (string) — Invitation ID.
- `email` (string) — Who is being invited.
- `role` (string) — Role the invitation grants.
- `expires_at` (string) — When the invitation stops working (UTC).
- `invitation_token` (string, optional) — The invitation token. Present only on the response that created it.
- `token_notice` (string, optional) — Reminder that the token is shown once.

**Errors**

- `400` — Missing email or unknown role.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/invitations -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"email":"member@example.com","role":"viewer"}'
```

### `POST /api/invitations/accept`

Accept an invitation and join the organization it points at.

Accepting joins an EXISTING organization trial. It never creates one, so an invitation cannot be used to mint tenants.

- **URL:** `https://commsharbor.com/api/invitations/accept`
- **Auth:** `session` — Bearer session or secure session cookie. No organization is implied.

**Body** (`application/json`)

- `token` (string, required) — The invitation token, from the response that created it.

**Body example**

```json
{
  "token": "invite_…"
}
```

**Response `200`**

Structure: `Membership`.

- `organization_id` (string) — The organization.
- `user_id` (string) — The member.
- `role` (string) — What the member may do.
- `created_at` (string) — When the membership started (UTC).

**Errors**

- `400` — Missing token.
- `401` — No session, or the session expired.
- `404` — Unknown, expired or already used invitation.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/invitations/accept -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"token":"invite_…"}'
```

## Credentials

### `GET /api/organizations/:organization_id/api-keys`

List API keys without token hashes or secrets.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/api-keys`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `api_keys` (ApiKey[]) — Keys of this organization, without the tokens. → see `ApiKey` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/api-keys -H "Authorization: Bearer $TOKEN"
```

### `POST /api/organizations/:organization_id/api-keys`

Create a scoped API key and reveal it exactly once.

The key determines its own organization. It cannot manage credentials or membership — those stay with human admins.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/api-keys`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Label so the key can be recognised later.
- `scopes` (string[], required) — What the key may do, e.g. `organization:read`, `crm:write`, `messages:send`.

**Body example**

```json
{
  "name": "Automation",
  "scopes": [
    "organization:read",
    "crm:read",
    "crm:write"
  ]
}
```

**Response `200`**

Structure: `ApiKey`.

- `id` (string) — API key ID, used to revoke it.
- `name` (string) — Label chosen at creation.
- `scopes` (string[]) — What this key may do, e.g. `crm:read`, `messages:send`.
- `prefix` (string) — Token prefix, so a key can be recognised in a list.
- `last_used_at` (string, may be null) — When the key last answered; null if never.
- `revoked_at` (string, may be null) — When it was revoked; null while it is still valid.
- `created_at` (string) — Creation time (UTC).
- `token` (string, optional) — The key itself. Present only on the response that created it — it is never shown again.

**Errors**

- `400` — Missing name or unknown scope.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/api-keys -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"name":"Automation","scopes":["crm:read"]}'
```

### `DELETE /api/organizations/:organization_id/api-keys/:api_key_id`

Revoke an API key. It stops working immediately, not at the next cache expiry.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/api-keys/:api_key_id`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `api_key_id` (string, required) — API key ID from the key listing. The token itself is never returned again.

**Response `200`**

Structure: `ApiKey`.

- `id` (string) — API key ID, used to revoke it.
- `name` (string) — Label chosen at creation.
- `scopes` (string[]) — What this key may do, e.g. `crm:read`, `messages:send`.
- `prefix` (string) — Token prefix, so a key can be recognised in a list.
- `last_used_at` (string, may be null) — When the key last answered; null if never.
- `revoked_at` (string, may be null) — When it was revoked; null while it is still valid.
- `created_at` (string) — Creation time (UTC).
- `token` (string, optional) — The key itself. Present only on the response that created it — it is never shown again.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/$ORG/api-keys/$KEY -H "Authorization: Bearer $TOKEN"
```

### `GET /api/organizations/:organization_id/audit`

List the append-only audit trail of the organization.

Audit records are never rewritten and never carry recipient PII.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audit`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `PageCamel<AuditEvent>`.

- `items` (AuditEvent[]) — The records on this page. → see `AuditEvent` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s 'https://commsharbor.com/api/organizations/$ORG/audit?limit=20' -H "Authorization: Bearer $TOKEN"
```

### `GET /api/platform/context`

Confirm an explicitly granted platform administrator.

Tenant ownership grants nothing here: platform access is a separate, explicit grant.

- **URL:** `https://commsharbor.com/api/platform/context`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Response `200`**

- `role` (string) — The platform role that was granted.
- `user_id` (string) — Who holds it.

**Errors**

- `401` — No session.
- `403` — This person has no platform grant.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/context -H "Authorization: Bearer $TOKEN"
```

## Domains

### `GET /api/organizations/:organization_id/domains`

List the sending domains of the organization and their last observed state.

`status` is what was last OBSERVED at SES and DNS. It does not become `active` because provisioning was requested.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `Lista<Domain>`.

- `items` (Domain[]) — Every record in the collection. → see `Domain` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/domains -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/domains`

Register the organization's sending domain and queue idempotent SES provisioning.

Asking twice does not provision twice. Publish the returned DKIM records, then call `verify` to have the state observed.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `domain` (string, required) — The domain to send from, e.g. `example.com`.

**Body example**

```json
{
  "domain": "example.com"
}
```

**Response `200`**

- `domain` (Domain) — The registered domain, with the DKIM records to publish. → see `Domain` under **Structures**.
- `provisioning` (Provisioning) — Whether this call enqueued provisioning work. → see `Provisioning` under **Structures**.

**Errors**

- `400` — Missing or malformed domain.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/domains -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"domain":"example.com"}'
```

### `GET /api/organizations/:organization_id/domains/:domain_id`

Read one sending domain, without inferring current DNS state.

This returns what was stored at the last observation. To look again, call `verify`.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Response `200`**

Structure: `Domain`.

- `id` (string) — Domain ID.
- `domain` (string) — The domain itself, e.g. `example.com`.
- `status` (string) — Last observed state.
- `dkim_tokens` (string[]) — CNAME records to publish for DKIM.
- `dmarc` (object, may be null) — DMARC policy observed at the domain.
- `mail_from` (object, may be null) — Custom MAIL FROM subdomain and its observed state.
- `last_observed_at` (string, may be null) — When SES and DNS were last actually checked (UTC).
- `created_at` (string) — Registration time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/domains/:domain_id/verify`

Observe SES, DKIM, DMARC and custom MAIL FROM state right now, and store what was seen.

This is the ONLY operation that can move a domain to `active`, and only because it actually looked.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id/verify`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Body example**

```json
{}
```

**Response `200`**

Structure: `Domain`.

- `id` (string) — Domain ID.
- `domain` (string) — The domain itself, e.g. `example.com`.
- `status` (string) — Last observed state.
- `dkim_tokens` (string[]) — CNAME records to publish for DKIM.
- `dmarc` (object, may be null) — DMARC policy observed at the domain.
- `mail_from` (object, may be null) — Custom MAIL FROM subdomain and its observed state.
- `last_observed_at` (string, may be null) — When SES and DNS were last actually checked (UTC).
- `created_at` (string) — Registration time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN/verify -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

### `POST /api/organizations/:organization_id/domains/:domain_id/smoke`

Queue one controlled smoke message to the server-side QA recipient.

The request never accepts a recipient: the destination is a server-side secret. That is what keeps this from becoming a way to send mail to arbitrary addresses through someone else's verified domain.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id/smoke`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Body example**

```json
{}
```

**Response `200`**

- `delivery` (Delivery) — The delivery record for the smoke. → see `Delivery` under **Structures**.
- `capacity` (Capacity) — What is left to send after it. → see `Capacity` under **Structures**.
- `dispatch` (Dispatch) — The queue work behind it. → see `Dispatch` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The domain is not active yet — verify it first.
- `429` — No capacity left.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN/smoke -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

## Deliveries

### `GET /api/organizations/:organization_id/domains/:domain_id/deliveries`

List deliveries sent from one domain, without recipient addresses.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id/deliveries`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Response `200`**

Structure: `Lista<Delivery>`.

- `items` (Delivery[]) — Every record in the collection. → see `Delivery` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN/deliveries -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/deliveries/:delivery_id`

Read one delivery and its SES MessageId, without recipient data.

`ses_message_id` is what correlates this record with AWS when you need to chase a message there.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deliveries/:delivery_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `delivery_id` (string, required) — Delivery ID returned when the message was queued.

**Response `200`**

Structure: `Delivery`.

- `id` (string) — Delivery ID.
- `status` (string) — Delivery state, authoritative in D1.
- `domain_id` (string) — Domain it was sent from.
- `template_id` (string, may be null) — Template used.
- `template_version` (int, may be null) — Immutable template version used.
- `ses_message_id` (string, may be null) — SES MessageId, for correlating with AWS.
- `created_at` (string) — When it was queued (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/deliveries/$DELIVERY -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/deliveries/:delivery_id/events`

List the normalized SES feedback events for one delivery.

Open and Click are ADDITIVE: they are recorded alongside delivery state and never overwrite it.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deliveries/:delivery_id/events`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `delivery_id` (string, required) — Delivery ID returned when the message was queued.

**Response `200`**

Structure: `Lista<DeliveryEvent>`.

- `items` (DeliveryEvent[]) — Every record in the collection. → see `DeliveryEvent` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/deliveries/$DELIVERY/events -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/aws/sns`

Receive a signed Amazon SNS callback for the configured SES topic.

This callback never accepts a user credential. It requires a valid SNS signature, a certificate URL in the expected AWS region, and the exact configured TopicArn — anything else is rejected before the body is read.

- **URL:** `https://commsharbor.com/api/aws/sns`
- **Auth:** `aws_sns` — Amazon SNS signature, regional certificate URL and the exact configured TopicArn. This callback never accepts a user credential.

**Response `200`**

`204 No Content` when the notification was accepted.

**Errors**

- `400` — Malformed notification, or a certificate URL outside the expected region.
- `403` — Bad signature, or a TopicArn other than the configured one.

**Example**

```sh
# Amazon SNS posts this; a hand-made call is rejected at the signature check.
curl -s -XPOST https://commsharbor.com/api/aws/sns -H 'x-amz-sns-message-type: Notification' -H 'content-type: text/plain; charset=UTF-8' -d '{"Type":"Notification","TopicArn":"arn:aws:sns:…","Signature":"…","SigningCertURL":"https://sns.<region>.amazonaws.com/…","Message":"{…SES event…}"}'
```

## CRM

### `GET /api/organizations/:organization_id/crm/contacts`

List contacts in the tenant CRM — a person in the tenant CRM.

Being in the CRM is not permission to email: consent lives in the `marketing` sub-resource.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `company_id` (string) — Restrict to one CRM company.

**Response `200`**

Structure: `Page<Contact>`.

- `items` (Contact[]) — The records on this page. → see `Contact` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/contacts -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/contacts`

Create a contact in the tenant CRM.

Being in the CRM is not permission to email: consent lives in the `marketing` sub-resource.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `email` (string, required) — Email address. Normalized and never truncated.
- `first_name` (string, required) — Given name of the contact.
- `last_name` (string) — Family name.
- `company_id` (string) — Company this contact belongs to.

**Body example**

```json
{
  "email": "buyer@example.com",
  "first_name": "Buyer",
  "company_id": "co_…"
}
```

**Response `200`**

Structure: `Contact`.

- `id` (string) — Contact ID.
- `email` (string) — Email address, normalized and never truncated.
- `first_name` (string, may be null) — Given name.
- `last_name` (string, may be null) — Family name.
- `company_id` (string, may be null) — Company this contact belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this contact — agents never build the path by hand.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/contacts -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"email":"buyer@example.com","first_name":"Buyer","company_id":"co_…"}'
```

### `GET /api/organizations/:organization_id/crm/contacts/:contact_id`

Read one contact from the tenant CRM.

Being in the CRM is not permission to email: consent lives in the `marketing` sub-resource.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Response `200`**

Structure: `Contact`.

- `id` (string) — Contact ID.
- `email` (string) — Email address, normalized and never truncated.
- `first_name` (string, may be null) — Given name.
- `last_name` (string, may be null) — Family name.
- `company_id` (string, may be null) — Company this contact belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this contact — agents never build the path by hand.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/contacts/contact_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/contacts/:contact_id`

Update one contact in the tenant CRM. Only the fields you send change.

Being in the CRM is not permission to email: consent lives in the `marketing` sub-resource.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Body** (`application/json`)

- `email` (string, required) — Email address. Normalized and never truncated.
- `first_name` (string, required) — Given name of the contact.
- `last_name` (string) — Family name.
- `company_id` (string) — Company this contact belongs to.

**Body example**

```json
{
  "email": "buyer@example.com",
  "first_name": "Buyer",
  "company_id": "co_…"
}
```

**Response `200`**

Structure: `Contact`.

- `id` (string) — Contact ID.
- `email` (string) — Email address, normalized and never truncated.
- `first_name` (string, may be null) — Given name.
- `last_name` (string, may be null) — Family name.
- `company_id` (string, may be null) — Company this contact belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this contact — agents never build the path by hand.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/contacts/contact_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"email":"buyer@example.com","first_name":"Buyer","company_id":"co_…"}'
```

### `DELETE /api/organizations/:organization_id/crm/contacts/:contact_id`

Delete one contact from the tenant CRM. The response carries the record as it was.

Being in the CRM is not permission to email: consent lives in the `marketing` sub-resource.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Response `200`**

Structure: `Contact`.

- `id` (string) — Contact ID.
- `email` (string) — Email address, normalized and never truncated.
- `first_name` (string, may be null) — Given name.
- `last_name` (string, may be null) — Family name.
- `company_id` (string, may be null) — Company this contact belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this contact — agents never build the path by hand.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/contacts/contact_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/companies`

List companies in the tenant CRM — an organization in the tenant CRM — a customer of the customer.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/companies`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.

**Response `200`**

Structure: `Page<Company>`.

- `items` (Company[]) — The records on this page. → see `Company` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/companies -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/companies`

Create a company in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/companies`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Company name.
- `domain` (string) — Primary domain, used to group contacts.
- `website` (string) — Website URL.

**Body example**

```json
{
  "name": "Acme",
  "domain": "example.com",
  "website": "https://example.com"
}
```

**Response `200`**

Structure: `Company`.

- `id` (string) — Company ID.
- `name` (string) — Company name.
- `domain` (string, may be null) — Primary domain.
- `website` (string, may be null) — Website URL.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this company.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/companies -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Acme","domain":"example.com","website":"https://example.com"}'
```

### `GET /api/organizations/:organization_id/crm/companies/:company_id`

Read one company from the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/companies/:company_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `company_id` (string, required) — CRM company ID inside the active organization.

**Response `200`**

Structure: `Company`.

- `id` (string) — Company ID.
- `name` (string) — Company name.
- `domain` (string, may be null) — Primary domain.
- `website` (string, may be null) — Website URL.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this company.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/companies/company_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/companies/:company_id`

Update one company in the tenant CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/companies/:company_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `company_id` (string, required) — CRM company ID inside the active organization.

**Body** (`application/json`)

- `name` (string, required) — Company name.
- `domain` (string) — Primary domain, used to group contacts.
- `website` (string) — Website URL.

**Body example**

```json
{
  "name": "Acme",
  "domain": "example.com",
  "website": "https://example.com"
}
```

**Response `200`**

Structure: `Company`.

- `id` (string) — Company ID.
- `name` (string) — Company name.
- `domain` (string, may be null) — Primary domain.
- `website` (string, may be null) — Website URL.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this company.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/companies/company_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Acme","domain":"example.com","website":"https://example.com"}'
```

### `DELETE /api/organizations/:organization_id/crm/companies/:company_id`

Delete one company from the tenant CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/companies/:company_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `company_id` (string, required) — CRM company ID inside the active organization.

**Response `200`**

Structure: `Company`.

- `id` (string) — Company ID.
- `name` (string) — Company name.
- `domain` (string, may be null) — Primary domain.
- `website` (string, may be null) — Website URL.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this company.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/companies/company_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/pipelines`

List pipelines in the tenant CRM — a named sequence of stages that deals move through.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.

**Response `200`**

Structure: `Page<Pipeline>`.

- `items` (Pipeline[]) — The records on this page. → see `Pipeline` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/pipelines -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/pipelines`

Create a pipeline in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Pipeline name.
- `stages` (string[]) — Stage names to create with the pipeline, in order.

**Body example**

```json
{
  "name": "Sales",
  "stages": [
    "New",
    "Proposal",
    "Won"
  ]
}
```

**Response `200`**

Structure: `Pipeline`.

- `id` (string) — Pipeline ID.
- `name` (string) — Pipeline name.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this pipeline.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/pipelines -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Sales","stages":["New","Proposal","Won"]}'
```

### `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id`

Read one pipeline from the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.

**Response `200`**

Structure: `Pipeline`.

- `id` (string) — Pipeline ID.
- `name` (string) — Pipeline name.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this pipeline.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/pipelines/:pipeline_id`

Update one pipeline in the tenant CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.

**Body** (`application/json`)

- `name` (string, required) — Pipeline name.
- `stages` (string[]) — Stage names to create with the pipeline, in order.

**Body example**

```json
{
  "name": "Sales",
  "stages": [
    "New",
    "Proposal",
    "Won"
  ]
}
```

**Response `200`**

Structure: `Pipeline`.

- `id` (string) — Pipeline ID.
- `name` (string) — Pipeline name.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this pipeline.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Sales","stages":["New","Proposal","Won"]}'
```

### `DELETE /api/organizations/:organization_id/crm/pipelines/:pipeline_id`

Delete one pipeline from the tenant CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.

**Response `200`**

Structure: `Pipeline`.

- `id` (string) — Pipeline ID.
- `name` (string) — Pipeline name.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this pipeline.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/deals`

List deals in the tenant CRM — an opportunity moving through a pipeline.

Money is in minor units: `value_minor: 10000` with `currency: "USD"` is $100.00, not $10,000.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/deals`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `pipeline_id` (string) — Restrict to one pipeline.
- `stage_id` (string) — Restrict to one pipeline stage.
- `status` (string) — Restrict to one status value.

**Response `200`**

Structure: `Page<Deal>`.

- `items` (Deal[]) — The records on this page. → see `Deal` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/deals -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/deals`

Create a deal in the tenant CRM.

Money is in minor units: `value_minor: 10000` with `currency: "USD"` is $100.00, not $10,000.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/deals`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `title` (string, required) — What the deal is.
- `pipeline_id` (string, required) — Pipeline the deal lives in.
- `stage_id` (string, required) — Stage the deal is at.
- `value_minor` (int) — Value in the currency's MINOR unit — cents, not dollars.
- `currency` (string) — ISO 4217 code for `value_minor`.

**Body example**

```json
{
  "title": "Renewal",
  "pipeline_id": "pl_…",
  "stage_id": "st_…",
  "value_minor": 10000,
  "currency": "USD"
}
```

**Response `200`**

Structure: `Deal`.

- `id` (string) — Deal ID.
- `title` (string) — What the deal is.
- `pipeline_id` (string) — Pipeline the deal lives in.
- `stage_id` (string) — Current stage.
- `status` (string) — Where it stands.
- `value_minor` (int, may be null) — Value in the currency's minor unit — cents, not dollars.
- `currency` (string, may be null) — ISO 4217 code for `value_minor`.
- `contact_id` (string, may be null) — Main contact on the deal.
- `company_id` (string, may be null) — Company on the deal.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this deal.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/deals -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Renewal","pipeline_id":"pl_…","stage_id":"st_…","value_minor":10000,"currency":"USD"}'
```

### `GET /api/organizations/:organization_id/crm/deals/:deal_id`

Read one deal from the tenant CRM.

Money is in minor units: `value_minor: 10000` with `currency: "USD"` is $100.00, not $10,000.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/deals/:deal_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `deal_id` (string, required) — CRM deal ID inside the active organization.

**Response `200`**

Structure: `Deal`.

- `id` (string) — Deal ID.
- `title` (string) — What the deal is.
- `pipeline_id` (string) — Pipeline the deal lives in.
- `stage_id` (string) — Current stage.
- `status` (string) — Where it stands.
- `value_minor` (int, may be null) — Value in the currency's minor unit — cents, not dollars.
- `currency` (string, may be null) — ISO 4217 code for `value_minor`.
- `contact_id` (string, may be null) — Main contact on the deal.
- `company_id` (string, may be null) — Company on the deal.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this deal.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/deals/deal_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/deals/:deal_id`

Update one deal in the tenant CRM. Only the fields you send change.

Money is in minor units: `value_minor: 10000` with `currency: "USD"` is $100.00, not $10,000.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/deals/:deal_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `deal_id` (string, required) — CRM deal ID inside the active organization.

**Body** (`application/json`)

- `title` (string, required) — What the deal is.
- `pipeline_id` (string, required) — Pipeline the deal lives in.
- `stage_id` (string, required) — Stage the deal is at.
- `value_minor` (int) — Value in the currency's MINOR unit — cents, not dollars.
- `currency` (string) — ISO 4217 code for `value_minor`.

**Body example**

```json
{
  "title": "Renewal",
  "pipeline_id": "pl_…",
  "stage_id": "st_…",
  "value_minor": 10000,
  "currency": "USD"
}
```

**Response `200`**

Structure: `Deal`.

- `id` (string) — Deal ID.
- `title` (string) — What the deal is.
- `pipeline_id` (string) — Pipeline the deal lives in.
- `stage_id` (string) — Current stage.
- `status` (string) — Where it stands.
- `value_minor` (int, may be null) — Value in the currency's minor unit — cents, not dollars.
- `currency` (string, may be null) — ISO 4217 code for `value_minor`.
- `contact_id` (string, may be null) — Main contact on the deal.
- `company_id` (string, may be null) — Company on the deal.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this deal.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/deals/deal_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Renewal","pipeline_id":"pl_…","stage_id":"st_…","value_minor":10000,"currency":"USD"}'
```

### `DELETE /api/organizations/:organization_id/crm/deals/:deal_id`

Delete one deal from the tenant CRM. The response carries the record as it was.

Money is in minor units: `value_minor: 10000` with `currency: "USD"` is $100.00, not $10,000.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/deals/:deal_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `deal_id` (string, required) — CRM deal ID inside the active organization.

**Response `200`**

Structure: `Deal`.

- `id` (string) — Deal ID.
- `title` (string) — What the deal is.
- `pipeline_id` (string) — Pipeline the deal lives in.
- `stage_id` (string) — Current stage.
- `status` (string) — Where it stands.
- `value_minor` (int, may be null) — Value in the currency's minor unit — cents, not dollars.
- `currency` (string, may be null) — ISO 4217 code for `value_minor`.
- `contact_id` (string, may be null) — Main contact on the deal.
- `company_id` (string, may be null) — Company on the deal.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this deal.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/deals/deal_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/activities`

List activities in the tenant CRM — something that happened with a contact, company or deal.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/activities`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `deal_id` (string) — Restrict to one deal.
- `contact_id` (string) — Restrict to one CRM contact.
- `company_id` (string) — Restrict to one CRM company.
- `activity_type` (string) — Restrict to one activity type, e.g. `note` or `call`.

**Response `200`**

Structure: `Page<Activity>`.

- `items` (Activity[]) — The records on this page. → see `Activity` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/activities -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/activities`

Create a activity in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/activities`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `note` (string, required) — The text of the activity.
- `activity_type` (string) — What kind it was, e.g. `note`, `call`, `meeting`.
- `deal_id` (string) — Deal it refers to.
- `contact_id` (string) — Contact it refers to.
- `company_id` (string) — Company it refers to.

**Body example**

```json
{
  "activity_type": "note",
  "note": "Followed up",
  "deal_id": "de_…"
}
```

**Response `200`**

Structure: `Activity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`, `call`, `meeting`.
- `note` (string) — The text of the activity.
- `deal_id` (string, may be null) — Deal it refers to.
- `contact_id` (string, may be null) — Contact it refers to.
- `company_id` (string, may be null) — Company it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/activities -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"activity_type":"note","note":"Followed up","deal_id":"de_…"}'
```

### `GET /api/organizations/:organization_id/crm/activities/:activity_id`

Read one activity from the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/activities/:activity_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Response `200`**

Structure: `Activity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`, `call`, `meeting`.
- `note` (string) — The text of the activity.
- `deal_id` (string, may be null) — Deal it refers to.
- `contact_id` (string, may be null) — Contact it refers to.
- `company_id` (string, may be null) — Company it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/activities/:activity_id`

Update one activity in the tenant CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/activities/:activity_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Body** (`application/json`)

- `note` (string, required) — The text of the activity.
- `activity_type` (string) — What kind it was, e.g. `note`, `call`, `meeting`.
- `deal_id` (string) — Deal it refers to.
- `contact_id` (string) — Contact it refers to.
- `company_id` (string) — Company it refers to.

**Body example**

```json
{
  "activity_type": "note",
  "note": "Followed up",
  "deal_id": "de_…"
}
```

**Response `200`**

Structure: `Activity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`, `call`, `meeting`.
- `note` (string) — The text of the activity.
- `deal_id` (string, may be null) — Deal it refers to.
- `contact_id` (string, may be null) — Contact it refers to.
- `company_id` (string, may be null) — Company it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"activity_type":"note","note":"Followed up","deal_id":"de_…"}'
```

### `DELETE /api/organizations/:organization_id/crm/activities/:activity_id`

Delete one activity from the tenant CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/activities/:activity_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Response `200`**

Structure: `Activity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`, `call`, `meeting`.
- `note` (string) — The text of the activity.
- `deal_id` (string, may be null) — Deal it refers to.
- `contact_id` (string, may be null) — Contact it refers to.
- `company_id` (string, may be null) — Company it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/tasks`

List tasks in the tenant CRM — work someone still has to do in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/tasks`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `status` (string) — Restrict to one status value.
- `deal_id` (string) — Restrict to one deal.
- `contact_id` (string) — Restrict to one CRM contact.
- `assignee_user_id` (string) — Restrict to the member the work is assigned to.

**Response `200`**

Structure: `Page<Task>`.

- `items` (Task[]) — The records on this page. → see `Task` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/tasks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/tasks`

Create a task in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/tasks`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `title` (string, required) — What has to be done.
- `status` (string) — Current state. Default: `open`. Values: `open`, `done`, `cancelled`.
- `due_at` (string) — When it is due, ISO-8601.
- `assignee_user_id` (string) — Member responsible for it.
- `deal_id` (string) — Deal the task belongs to.
- `contact_id` (string) — Contact the task belongs to.

**Body example**

```json
{
  "title": "Follow up",
  "status": "open",
  "deal_id": "de_…"
}
```

**Response `200`**

Structure: `Task`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Member responsible for it.
- `deal_id` (string, may be null) — Deal the task belongs to.
- `contact_id` (string, may be null) — Contact the task belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/tasks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Follow up","status":"open","deal_id":"de_…"}'
```

### `GET /api/organizations/:organization_id/crm/tasks/:task_id`

Read one task from the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/tasks/:task_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `task_id` (string, required) — CRM task ID inside the active organization.

**Response `200`**

Structure: `Task`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Member responsible for it.
- `deal_id` (string, may be null) — Deal the task belongs to.
- `contact_id` (string, may be null) — Contact the task belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/tasks/:task_id`

Update one task in the tenant CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/tasks/:task_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `task_id` (string, required) — CRM task ID inside the active organization.

**Body** (`application/json`)

- `title` (string, required) — What has to be done.
- `status` (string) — Current state. Default: `open`. Values: `open`, `done`, `cancelled`.
- `due_at` (string) — When it is due, ISO-8601.
- `assignee_user_id` (string) — Member responsible for it.
- `deal_id` (string) — Deal the task belongs to.
- `contact_id` (string) — Contact the task belongs to.

**Body example**

```json
{
  "title": "Follow up",
  "status": "open",
  "deal_id": "de_…"
}
```

**Response `200`**

Structure: `Task`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Member responsible for it.
- `deal_id` (string, may be null) — Deal the task belongs to.
- `contact_id` (string, may be null) — Contact the task belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Follow up","status":"open","deal_id":"de_…"}'
```

### `DELETE /api/organizations/:organization_id/crm/tasks/:task_id`

Delete one task from the tenant CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/tasks/:task_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `task_id` (string, required) — CRM task ID inside the active organization.

**Response `200`**

Structure: `Task`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Member responsible for it.
- `deal_id` (string, may be null) — Deal the task belongs to.
- `contact_id` (string, may be null) — Contact the task belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages`

List stages in the tenant CRM — one step of a pipeline, addressed under the pipeline it belongs to.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<Stage>`.

- `items` (Stage[]) — The records on this page. → see `Stage` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id/stages -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages`

Create a stage in the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.

**Body** (`application/json`)

- `name` (string, required) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int) — Chance of winning at this stage, 0 to 100.

**Body example**

```json
{
  "name": "Proposal",
  "position": 2,
  "probability": 60
}
```

**Response `200`**

Structure: `Stage`.

- `id` (string) — Stage ID.
- `pipeline_id` (string) — Pipeline this stage belongs to.
- `name` (string) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int, may be null) — Chance of winning at this stage, 0 to 100.
- `url` (string) — Absolute URL of this stage.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id/stages -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Proposal","position":2,"probability":60}'
```

### `GET /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`

Read one stage from the tenant CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.
- `stage_id` (string, required) — Pipeline stage ID. Stages live under one pipeline.

**Response `200`**

Structure: `Stage`.

- `id` (string) — Stage ID.
- `pipeline_id` (string) — Pipeline this stage belongs to.
- `name` (string) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int, may be null) — Chance of winning at this stage, 0 to 100.
- `url` (string) — Absolute URL of this stage.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id/stages/stage_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`

Update one stage in the tenant CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.
- `stage_id` (string, required) — Pipeline stage ID. Stages live under one pipeline.

**Body** (`application/json`)

- `name` (string, required) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int) — Chance of winning at this stage, 0 to 100.

**Body example**

```json
{
  "name": "Proposal",
  "position": 2,
  "probability": 60
}
```

**Response `200`**

Structure: `Stage`.

- `id` (string) — Stage ID.
- `pipeline_id` (string) — Pipeline this stage belongs to.
- `name` (string) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int, may be null) — Chance of winning at this stage, 0 to 100.
- `url` (string) — Absolute URL of this stage.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id/stages/stage_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Proposal","position":2,"probability":60}'
```

### `DELETE /api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`

Delete one stage from the tenant CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/pipelines/:pipeline_id/stages/:stage_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `pipeline_id` (string, required) — CRM pipeline ID inside the active organization.
- `stage_id` (string, required) — Pipeline stage ID. Stages live under one pipeline.

**Response `200`**

Structure: `Stage`.

- `id` (string) — Stage ID.
- `pipeline_id` (string) — Pipeline this stage belongs to.
- `name` (string) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int, may be null) — Chance of winning at this stage, 0 to 100.
- `url` (string) — Absolute URL of this stage.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/organization_id/crm/pipelines/pipeline_id/stages/stage_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

## Platform CRM

### `GET /api/platform/crm/leads`

List leads in the platform CRM — a prospective ORGANIZATION in our own funnel — platform CRM is not tenant data.

- **URL:** `https://commsharbor.com/api/platform/crm/leads`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `stage` (string) — Restrict to one funnel stage of the platform lead.

**Response `200`**

Structure: `Page<Lead>`.

- `items` (Lead[]) — The records on this page. → see `Lead` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/leads -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/platform/crm/leads`

Create a lead in the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/leads`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Body** (`application/json`)

- `email` (string, required) — Contact email for the lead.
- `name` (string, required) — Who to talk to.
- `company_name` (string) — Name of the prospective organization.
- `source` (string) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where it sits in our funnel, e.g. `new`.
- `organization_id` (string) — The organization it became, once converted.

**Body example**

```json
{
  "email": "lead@example.com",
  "name": "Lead",
  "company_name": "Acme",
  "source": "manual",
  "stage": "new",
  "organization_id": "org_…"
}
```

**Response `200`**

Structure: `Lead`.

- `id` (string) — Lead ID.
- `email` (string) — Contact email for the lead.
- `name` (string) — Who to talk to.
- `company_name` (string, may be null) — Name of the prospective organization.
- `source` (string, may be null) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where the lead is in our own funnel, e.g. `new`.
- `organization_id` (string, may be null) — The organization this lead became, once it converted.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this lead.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/platform/crm/leads -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"email":"lead@example.com","name":"Lead","company_name":"Acme","source":"manual","stage":"new","organization_id":"org_…"}'
```

### `GET /api/platform/crm/leads/:lead_id`

Read one lead from the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.

**Response `200`**

Structure: `Lead`.

- `id` (string) — Lead ID.
- `email` (string) — Contact email for the lead.
- `name` (string) — Who to talk to.
- `company_name` (string, may be null) — Name of the prospective organization.
- `source` (string, may be null) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where the lead is in our own funnel, e.g. `new`.
- `organization_id` (string, may be null) — The organization this lead became, once it converted.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this lead.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/leads/lead_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/platform/crm/leads/:lead_id`

Update one lead in the platform CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.

**Body** (`application/json`)

- `email` (string, required) — Contact email for the lead.
- `name` (string, required) — Who to talk to.
- `company_name` (string) — Name of the prospective organization.
- `source` (string) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where it sits in our funnel, e.g. `new`.
- `organization_id` (string) — The organization it became, once converted.

**Body example**

```json
{
  "email": "lead@example.com",
  "name": "Lead",
  "company_name": "Acme",
  "source": "manual",
  "stage": "new",
  "organization_id": "org_…"
}
```

**Response `200`**

Structure: `Lead`.

- `id` (string) — Lead ID.
- `email` (string) — Contact email for the lead.
- `name` (string) — Who to talk to.
- `company_name` (string, may be null) — Name of the prospective organization.
- `source` (string, may be null) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where the lead is in our own funnel, e.g. `new`.
- `organization_id` (string, may be null) — The organization this lead became, once it converted.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this lead.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/platform/crm/leads/lead_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"email":"lead@example.com","name":"Lead","company_name":"Acme","source":"manual","stage":"new","organization_id":"org_…"}'
```

### `DELETE /api/platform/crm/leads/:lead_id`

Delete one lead from the platform CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.

**Response `200`**

Structure: `Lead`.

- `id` (string) — Lead ID.
- `email` (string) — Contact email for the lead.
- `name` (string) — Who to talk to.
- `company_name` (string, may be null) — Name of the prospective organization.
- `source` (string, may be null) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where the lead is in our own funnel, e.g. `new`.
- `organization_id` (string, may be null) — The organization this lead became, once it converted.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this lead.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/platform/crm/leads/lead_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/platform/crm/tasks`

List tasks in the platform CRM — work on a platform lead — about a prospective tenant, not about a tenant's customer.

- **URL:** `https://commsharbor.com/api/platform/crm/tasks`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.
- `status` (string) — Restrict to one status value.
- `lead_id` (string) — Restrict to one platform lead.
- `assignee_user_id` (string) — Restrict to the member the work is assigned to.

**Response `200`**

Structure: `Page<PlatformTask>`.

- `items` (PlatformTask[]) — The records on this page. → see `PlatformTask` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/tasks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/platform/crm/tasks`

Create a task in the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/tasks`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Body** (`application/json`)

- `title` (string, required) — What has to be done.
- `lead_id` (string) — Lead the task belongs to.
- `due_at` (string) — When it is due, ISO-8601.
- `assignee_user_id` (string) — Who is responsible.

**Body example**

```json
{
  "title": "Follow up",
  "lead_id": "ld_…",
  "due_at": "2026-09-01T12:00:00Z"
}
```

**Response `200`**

Structure: `PlatformTask`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `lead_id` (string, may be null) — Lead the task belongs to.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Who is responsible.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/platform/crm/tasks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Follow up","lead_id":"ld_…","due_at":"2026-09-01T12:00:00Z"}'
```

### `GET /api/platform/crm/tasks/:task_id`

Read one task from the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/tasks/:task_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `task_id` (string, required) — CRM task ID inside the active organization.

**Response `200`**

Structure: `PlatformTask`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `lead_id` (string, may be null) — Lead the task belongs to.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Who is responsible.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/platform/crm/tasks/:task_id`

Update one task in the platform CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/platform/crm/tasks/:task_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `task_id` (string, required) — CRM task ID inside the active organization.

**Body** (`application/json`)

- `title` (string, required) — What has to be done.
- `lead_id` (string) — Lead the task belongs to.
- `due_at` (string) — When it is due, ISO-8601.
- `assignee_user_id` (string) — Who is responsible.

**Body example**

```json
{
  "title": "Follow up",
  "lead_id": "ld_…",
  "due_at": "2026-09-01T12:00:00Z"
}
```

**Response `200`**

Structure: `PlatformTask`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `lead_id` (string, may be null) — Lead the task belongs to.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Who is responsible.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/platform/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"title":"Follow up","lead_id":"ld_…","due_at":"2026-09-01T12:00:00Z"}'
```

### `DELETE /api/platform/crm/tasks/:task_id`

Delete one task from the platform CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/platform/crm/tasks/:task_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `task_id` (string, required) — CRM task ID inside the active organization.

**Response `200`**

Structure: `PlatformTask`.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `lead_id` (string, may be null) — Lead the task belongs to.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Who is responsible.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/platform/crm/tasks/task_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/platform/crm/leads/:lead_id/activities`

List activities in the platform CRM — our note about a prospective tenant.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id/activities`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.
- `q` (string) — Free-text search over the record's main fields.

**Response `200`**

Structure: `Page<PlatformActivity>`.

- `items` (PlatformActivity[]) — The records on this page. → see `PlatformActivity` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/leads/lead_id/activities -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/platform/crm/leads/:lead_id/activities`

Create a activity in the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id/activities`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.

**Body** (`application/json`)

- `note` (string, required) — The text of the activity.
- `activity_type` (string) — What kind it was, e.g. `note`.

**Body example**

```json
{
  "activity_type": "note",
  "note": "Followed up"
}
```

**Response `200`**

Structure: `PlatformActivity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`.
- `note` (string) — The text of the activity.
- `lead_id` (string) — Lead it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `400` — A required field is missing, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/platform/crm/leads/lead_id/activities -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"activity_type":"note","note":"Followed up"}'
```

### `GET /api/platform/crm/leads/:lead_id/activities/:activity_id`

Read one activity from the platform CRM.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id/activities/:activity_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Response `200`**

Structure: `PlatformActivity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`.
- `note` (string) — The text of the activity.
- `lead_id` (string) — Lead it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/platform/crm/leads/lead_id/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/platform/crm/leads/:lead_id/activities/:activity_id`

Update one activity in the platform CRM. Only the fields you send change.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id/activities/:activity_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Body** (`application/json`)

- `note` (string, required) — The text of the activity.
- `activity_type` (string) — What kind it was, e.g. `note`.

**Body example**

```json
{
  "activity_type": "note",
  "note": "Followed up"
}
```

**Response `200`**

Structure: `PlatformActivity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`.
- `note` (string) — The text of the activity.
- `lead_id` (string) — Lead it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `400` — A field is invalid, or a referenced record does not exist here.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/platform/crm/leads/lead_id/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"activity_type":"note","note":"Followed up"}'
```

### `DELETE /api/platform/crm/leads/:lead_id/activities/:activity_id`

Delete one activity from the platform CRM. The response carries the record as it was.

- **URL:** `https://commsharbor.com/api/platform/crm/leads/:lead_id/activities/:activity_id`
- **Auth:** `platform_admin` — Session with an explicit platform_roles grant. Tenant ownership does not grant platform access.

**Path parameters**

- `lead_id` (string, required) — Platform CRM lead ID. Platform CRM is not tenant data.
- `activity_id` (string, required) — CRM activity ID inside the active organization.

**Response `200`**

Structure: `PlatformActivity`.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`.
- `note` (string) — The text of the activity.
- `lead_id` (string) — Lead it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/platform/crm/leads/lead_id/activities/activity_id -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

## Consent

### `GET /api/organizations/:organization_id/crm/contacts/:contact_id/marketing`

Read consent and marketing preference for one CRM contact.

Being in the CRM is not permission to email. This resource is where permission actually lives.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id/marketing`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Response `200`**

Structure: `Marketing`.

- `marketing_enabled` (bool) — Whether marketing may be sent to this contact right now.
- `basis` (string, may be null) — Why sending is allowed.
- `source` (string, may be null) — Where the consent came from, e.g. a signup form.
- `captured_at` (string, may be null) — When consent was captured (UTC).
- `unsubscribed_at` (string, may be null) — When the contact unsubscribed; null when they never did.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/crm/contacts/$CONTACT/marketing -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PUT /api/organizations/:organization_id/crm/contacts/:contact_id/marketing`

Record permission-based marketing consent for one contact.

This NEVER restores a previous unsubscribe. If the contact opted out, they stay out and `marketing_enabled` remains false — recording consent after the fact does not undo their decision.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id/marketing`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Body** (`application/json`)

- `basis` (string, required) — Why sending is allowed. Values: `explicit`, `documented_relationship`.
- `source` (string, required) — Where the consent came from, e.g. the signup form that captured it.
- `captured_at` (string, required) — When consent was captured, ISO-8601.

**Body example**

```json
{
  "basis": "explicit",
  "source": "website signup form",
  "captured_at": "2026-08-29T12:00:00.000Z"
}
```

**Response `200`**

Structure: `Marketing`.

- `marketing_enabled` (bool) — Whether marketing may be sent to this contact right now.
- `basis` (string, may be null) — Why sending is allowed.
- `source` (string, may be null) — Where the consent came from, e.g. a signup form.
- `captured_at` (string, may be null) — When consent was captured (UTC).
- `unsubscribed_at` (string, may be null) — When the contact unsubscribed; null when they never did.

**Errors**

- `400` — Missing basis, source or capture time, or an unknown basis.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPUT https://commsharbor.com/api/organizations/$ORG/crm/contacts/$CONTACT/marketing -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"basis":"explicit","source":"website signup form","captured_at":"2026-08-29T12:00:00.000Z"}'
```

### `POST /api/organizations/:organization_id/crm/contacts/:contact_id/preference-token`

Create a signed preference and one-click unsubscribe capability for a contact.

The capability is scoped to one organization and one contact, it expires, and it embeds no email address. Put `marketing_headers` in the message and the unsubscribe works without a login.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/crm/contacts/:contact_id/preference-token`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Body example**

```json
{}
```

**Response `200`**

Structure: `PreferenceToken`.

- `api_url` (string) — Machine-readable preference endpoint.
- `preferences_url` (string) — Human preference page.
- `unsubscribe_url` (string) — RFC 8058 one-click unsubscribe endpoint.
- `marketing_headers` (object) — `List-Unsubscribe` and `List-Unsubscribe-Post`, ready to add to the message.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/crm/contacts/$CONTACT/preference-token -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

### `GET /api/preferences/:token`

Read a contact's preference through a signed capability, with no login.

The token IS the credential. It reveals preference state and nothing else — no email address, no CRM record.

- **URL:** `https://commsharbor.com/api/preferences/:token`
- **Auth:** `preference_capability` — Signed, expiring capability scoped to one organization and contact. No login is required and no email address is embedded in the token.

**Path parameters**

- `token` (string, required) — Signed preference capability. It is scoped to one organization and one contact, it expires, and it never embeds an email address.

**Response `200`**

Structure: `PreferenceState`.

- `marketing_enabled` (bool) — Whether marketing may be sent.
- `unsubscribed_at` (string, may be null) — When the contact unsubscribed.
- `expires_at` (string) — When this capability stops working (UTC).

**Errors**

- `401` — Bad signature.
- `404` — Unknown or expired capability.

**Example**

```sh
curl -s https://commsharbor.com/api/preferences/$TOKEN
```

### `POST /api/preferences/:token/unsubscribe`

Apply an RFC 8058 one-click unsubscribe, idempotently.

This is the endpoint mail clients call from the `List-Unsubscribe-Post` header, which is why the body is form-encoded and fixed. Calling it twice is the same as calling it once.

- **URL:** `https://commsharbor.com/api/preferences/:token/unsubscribe`
- **Auth:** `preference_capability` — Signed, expiring capability scoped to one organization and contact. No login is required and no email address is embedded in the token.

**Path parameters**

- `token` (string, required) — Signed preference capability. It is scoped to one organization and one contact, it expires, and it never embeds an email address.

**Body example**

```json
List-Unsubscribe=One-Click
```

**Response `200`**

- `unsubscribed` (bool) — Always true once the contact is unsubscribed, whether or not this call was the one that did it.

**Errors**

- `401` — Bad signature.
- `404` — Unknown or expired capability.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/preferences/$TOKEN/unsubscribe -H 'content-type: application/x-www-form-urlencoded' -d 'List-Unsubscribe=One-Click'
```

### `POST /api/organizations/:organization_id/domains/:domain_id/marketing-smoke`

Queue one controlled permission-based marketing message to the server-side recipient.

Like the transactional smoke, the destination is a server-side secret. `contact_id` must be the CRM contact that matches it — you cannot point this at an arbitrary person.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id/marketing-smoke`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Headers**

- `Idempotency-Key` (string, required) — Unique key for this controlled send. Replaying the same key returns the same result and produces NO second Queue message; a different payload under the same key conflicts.

**Body** (`application/json`)

- `contact_id` (string, required) — CRM contact matching the server-side QA recipient.

**Body example**

```json
{
  "contact_id": "ct_controlled"
}
```

**Response `200`**

Structure: `Send`.

- `delivery` (Delivery) — The delivery record. → see `Delivery` under **Structures**.
- `capacity` (Capacity) — What is left after this send. → see `Capacity` under **Structures**.
- `dispatch` (Dispatch) — The queue work behind it. → see `Dispatch` under **Structures**.
- `replayed` (bool) — True when this was a replay of an earlier identical request.

**Errors**

- `400` — Missing contact.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The contact does not match the controlled recipient, or the domain is not active.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN/marketing-smoke -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{"contact_id":"ct_controlled"}'
```

## Imports

### `GET /api/organizations/:organization_id/contact-imports`

List the contact imports of the organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-imports`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<ContactImport>`.

- `items` (ContactImport[]) — The records on this page. → see `ContactImport` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/contact-imports -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/contact-imports`

Upload a consent-declared CSV and get back a safe preview before anything is imported.

Nothing is created by this call. The consent declaration is mandatory: an import that cannot say why these people may be emailed is an import that does not happen.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-imports`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `csv` (string, required) — The CSV itself, up to 5 MB and 10,000 rows.
- `mapping` (object, required) — Which CSV column feeds which contact field, e.g. `{ "email": "Email" }`.
- `basis` (string, required) — Why sending is allowed. Values: `explicit`, `documented_relationship`.
- `source` (string, required) — Where the consent came from, e.g. the signup form that captured it.
- `captured_at` (string, required) — When consent was captured, ISO-8601.

**Body example**

```json
{
  "csv": "Email,First name\\nalice@example.com,Alice",
  "mapping": {
    "email": "Email",
    "first_name": "First name"
  },
  "basis": "explicit",
  "source": "website signup form",
  "captured_at": "2026-08-29T12:00:00.000Z"
}
```

**Response `200`**

- `import` (ContactImport) — The import in `preview` state. → see `ContactImport` under **Structures**.
- `preview` (object[]) — The first parsed rows, so you can check the mapping before confirming.
- `errors` (ImportError[]) — Rows that would be rejected, addressed by line number. → see `ImportError` under **Structures**.

**Errors**

- `400` — CSV too large, unparseable, or missing the consent declaration.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `413` — Above the size limit.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/contact-imports -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"csv":"Email\\nalice@example.com","mapping":{"email":"Email"},"basis":"explicit","source":"website signup form","captured_at":"2026-08-29T12:00:00.000Z"}'
```

### `GET /api/organizations/:organization_id/contact-imports/:import_id`

Read one durable contact import and its current counts.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-imports/:import_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `import_id` (string, required) — Contact import ID returned by the CSV preview.

**Response `200`**

Structure: `ContactImport`.

- `id` (string) — Import ID.
- `status` (string) — Where the import stands.
- `rows` (int) — Rows found in the CSV.
- `accepted` (int) — Rows that will be imported.
- `rejected` (int) — Rows rejected, with reasons in the errors listing.
- `basis` (string) — Declared consent basis for every row.
- `file_id` (string, may be null) — Stored file, downloadable for seven days.
- `created_at` (string) — Upload time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/contact-imports/$IMPORT -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/contact-imports/:import_id/confirm`

Confirm a previewed import and enqueue it, exactly once.

The idempotency key is mandatory here. Reusing it returns the same import and never creates a second Queue message — which is what keeps a retry from importing everyone twice.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-imports/:import_id/confirm`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `import_id` (string, required) — Contact import ID returned by the CSV preview.

**Headers**

- `Idempotency-Key` (string, required) — Unique key for this import confirmation. Replaying the same key returns the same result and produces NO second Queue message; a different payload under the same key conflicts.

**Body example**

```json
{}
```

**Response `200`**

Structure: `ContactImport`.

- `id` (string) — Import ID.
- `status` (string) — Where the import stands.
- `rows` (int) — Rows found in the CSV.
- `accepted` (int) — Rows that will be imported.
- `rejected` (int) — Rows rejected, with reasons in the errors listing.
- `basis` (string) — Declared consent basis for every row.
- `file_id` (string, may be null) — Stored file, downloadable for seven days.
- `created_at` (string) — Upload time (UTC).

**Errors**

- `400` — Missing Idempotency-Key.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The same key was used with a different payload, or the import was already confirmed.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/contact-imports/$IMPORT/confirm -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{}'
```

### `GET /api/organizations/:organization_id/contact-imports/:import_id/errors`

List the row-numbered errors of one import, so the source file can be fixed.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-imports/:import_id/errors`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `import_id` (string, required) — Contact import ID returned by the CSV preview.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<ImportError>`.

- `items` (ImportError[]) — The records on this page. → see `ImportError` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/contact-imports/$IMPORT/errors -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/contact-files/:file_id`

Download a tenant-owned CSV before its seven-day expiry.

Files expire seven days after creation. Durable audit and row-level results survive the file.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contact-files/:file_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `file_id` (string, required) — Contact file ID. Files expire seven days after they are created.

**Response `200`**

`text/csv` as an attachment, with the tenant's file name.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `410` — The file expired. Its audit record still exists.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/contact-files/$FILE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/contacts/export`

Create a CSV export of the organization's contacts, retained for seven days.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/contacts/export`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body example**

```json
{}
```

**Response `200`**

- `export` (ContactImport) — The export record, with its file and expiry. → see `ContactImport` under **Structures**.
- `download_url` (string) — Where to fetch the CSV while it lasts.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/contacts/export -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

## Suppressions

### `GET /api/organizations/:organization_id/suppressions`

List the organization's suppressions, without exposing email hashes.

Global, organization and SES tenant suppressions are all checked BEFORE quota and before any queue work.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/suppressions`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<Suppression>`.

- `items` (Suppression[]) — The records on this page. → see `Suppression` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/suppressions -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/suppressions`

Suppress one recipient inside the active organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/suppressions`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `email` (string, required) — Address to suppress.
- `contact_id` (string) — CRM contact it corresponds to, when you know it.

**Body example**

```json
{
  "email": "alice@example.com",
  "contact_id": "ct_example"
}
```

**Response `200`**

- `suppressed` (bool) — Always true once the address is suppressed.

**Errors**

- `400` — Missing or malformed email.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/suppressions -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"email":"alice@example.com"}'
```

## Audiences

### `GET /api/organizations/:organization_id/audiences`

List static audiences and saved segments.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<Audience>`.

- `items` (Audience[]) — The records on this page. → see `Audience` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/audiences -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/audiences`

Create a static audience or a saved segment with an allowlisted filter.

Only allowlisted filter fields are accepted — a saved segment cannot be turned into an arbitrary query over the CRM.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Audience name.
- `kind` (string, required) — How membership is decided. Values: `static`, `saved_segment`.
- `filter` (object) — The saved filter, for `saved_segment`. Allowlisted fields only.

**Body example**

```json
{
  "name": "Newsletter",
  "kind": "static"
}
```

**Response `200`**

Structure: `Audience`.

- `id` (string) — Audience ID.
- `name` (string) — Audience name.
- `kind` (string) — How membership is decided.
- `filter` (object, may be null) — The saved filter, for `saved_segment`. Only allowlisted fields are accepted.
- `member_count` (int, may be null) — Contacts currently in the audience.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `400` — Missing name or kind, or a filter field outside the allowlist.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/audiences -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Newsletter","kind":"static"}'
```

### `GET /api/organizations/:organization_id/audiences/:audience_id`

Read one audience of this organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.

**Response `200`**

Structure: `Audience`.

- `id` (string) — Audience ID.
- `name` (string) — Audience name.
- `kind` (string) — How membership is decided.
- `filter` (object, may be null) — The saved filter, for `saved_segment`. Only allowlisted fields are accepted.
- `member_count` (int, may be null) — Contacts currently in the audience.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/audiences/:audience_id`

Rename an audience or change its saved filter.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.

**Body** (`application/json`)

- `name` (string) — New audience name.
- `filter` (object) — New saved filter. Allowlisted fields only.

**Body example**

```json
{
  "name": "Customers",
  "filter": {
    "consent_basis": "explicit"
  }
}
```

**Response `200`**

Structure: `Audience`.

- `id` (string) — Audience ID.
- `name` (string) — Audience name.
- `kind` (string) — How membership is decided.
- `filter` (object, may be null) — The saved filter, for `saved_segment`. Only allowlisted fields are accepted.
- `member_count` (int, may be null) — Contacts currently in the audience.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `400` — A filter field outside the allowlist.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Customers"}'
```

### `DELETE /api/organizations/:organization_id/audiences/:audience_id`

Delete an audience and its memberships. Contacts themselves are untouched.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.

**Response `200`**

Structure: `Audience`.

- `id` (string) — Audience ID.
- `name` (string) — Audience name.
- `kind` (string) — How membership is decided.
- `filter` (object, may be null) — The saved filter, for `saved_segment`. Only allowlisted fields are accepted.
- `member_count` (int, may be null) — Contacts currently in the audience.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/audiences/:audience_id/members`

List the contacts currently in one audience.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id/members`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `Page<Contact>`.

- `items` (Contact[]) — The records on this page. → see `Contact` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE/members -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/audiences/:audience_id/members`

Add a CRM contact to a static audience.

Only for `static` audiences: a saved segment's membership comes from its filter, not from this route.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id/members`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.

**Body** (`application/json`)

- `contact_id` (string, required) — CRM contact to add.

**Body example**

```json
{
  "contact_id": "ct_example"
}
```

**Response `200`**

- `membership` (object) — The audience membership that was created.

**Errors**

- `400` — Missing contact.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The audience is a saved segment and has no manual membership.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE/members -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"contact_id":"ct_example"}'
```

### `DELETE /api/organizations/:organization_id/audiences/:audience_id/members/:contact_id`

Remove a contact from a static audience.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/audiences/:audience_id/members/:contact_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `audience_id` (string, required) — Audience ID inside the active organization.
- `contact_id` (string, required) — CRM contact ID inside the active organization.

**Response `200`**

- `membership` (object) — The membership as it was before removal.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/$ORG/audiences/$AUDIENCE/members/$CONTACT -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

## Templates

### `GET /api/organizations/:organization_id/templates`

List the versioned email templates of the organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `PageCamel<Template>`.

- `items` (Template[]) — The records on this page. → see `Template` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/templates -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/templates`

Create a template draft from canonical blocks.

Creating never publishes. Nothing can send this template until `publish` freezes a version.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Template name.
- `message_type` (string, required) — What the template may be used for. A marketing campaign will not accept a transactional template. Values: `transactional`, `marketing`.
- `subject` (string, required) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: `name`, `type` and whether it is `required`.
- `blocks` (object[]) — Canonical content blocks. This is the stored form — HTML is converted into it, never kept raw.

**Body example**

```json
{
  "name": "Welcome",
  "message_type": "transactional",
  "subject": "Welcome, {{name}}",
  "variables": [
    {
      "name": "name",
      "type": "string",
      "required": true
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "text": "Hello {{name}}",
      "level": 1,
      "align": "left"
    }
  ]
}
```

**Response `200`**

Structure: `Template`.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

**Errors**

- `400` — Missing name, subject or message type, or an unknown block type.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/templates -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Welcome","message_type":"transactional","subject":"Welcome"}'
```

### `GET /api/organizations/:organization_id/templates/:template_id`

Read one template draft owned by this organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Response `200`**

Structure: `Template`.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/templates/:template_id`

Update a template as a new draft, leaving published versions untouched.

Editing a draft can never change what a past delivery rendered: published versions are immutable.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Body** (`application/json`)

- `name` (string, required) — Template name.
- `message_type` (string, required) — What the template may be used for. A marketing campaign will not accept a transactional template. Values: `transactional`, `marketing`.
- `subject` (string, required) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: `name`, `type` and whether it is `required`.
- `blocks` (object[]) — Canonical content blocks. This is the stored form — HTML is converted into it, never kept raw.

**Body example**

```json
{
  "name": "Welcome",
  "message_type": "transactional",
  "subject": "Welcome, {{name}}",
  "variables": [
    {
      "name": "name",
      "type": "string",
      "required": true
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "text": "Hello {{name}}",
      "level": 1,
      "align": "left"
    }
  ]
}
```

**Response `200`**

Structure: `Template`.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

**Errors**

- `400` — Invalid field or unknown block type.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"subject":"Welcome aboard"}'
```

### `DELETE /api/organizations/:organization_id/templates/:template_id`

Archive a template without deleting its published versions.

Deliveries that referenced a version must keep resolving to it, so archiving hides the draft and keeps the history.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Response `200`**

Structure: `Template`.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/templates/:template_id/publish`

Publish an immutable, content-hashed version of the draft.

The version's identity is the hash of its compiled content — publishing identical content does not create a second version.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id/publish`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Body example**

```json
{}
```

**Response `200`**

Structure: `TemplateVersion`.

- `version` (int) — Version number, increasing.
- `content_hash` (string) — Hash of the compiled content; it is the version's identity.
- `subject` (string) — Subject at this version.
- `published_at` (string) — Publication time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The draft does not compile, or nothing changed since the last version.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE/publish -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

### `GET /api/organizations/:organization_id/templates/:template_id/versions`

List the immutable published versions of a template.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id/versions`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Response `200`**

Structure: `Lista<TemplateVersion>`.

- `items` (TemplateVersion[]) — Every record in the collection. → see `TemplateVersion` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE/versions -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/templates/preview`

Compile and safely render a draft, without saving or publishing anything.

`warnings` tells you what was stripped and what would not render — read it before publishing rather than after sending.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/preview`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Template name.
- `message_type` (string, required) — What the template may be used for. A marketing campaign will not accept a transactional template. Values: `transactional`, `marketing`.
- `subject` (string, required) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: `name`, `type` and whether it is `required`.
- `blocks` (object[]) — Canonical content blocks. This is the stored form — HTML is converted into it, never kept raw.
- `values` (object) — Values to substitute into the declared variables for this preview.

**Body example**

```json
{
  "name": "Welcome",
  "message_type": "transactional",
  "subject": "Welcome, {{name}}",
  "variables": [
    {
      "name": "name",
      "type": "string",
      "required": true
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "text": "Hello {{name}}",
      "level": 1,
      "align": "left"
    }
  ],
  "values": {
    "name": "Ada"
  }
}
```

**Response `200`**

Structure: `TemplatePreview`.

- `subject` (string) — Subject with variables applied.
- `html` (string) — Rendered HTML.
- `text` (string) — Plain-text alternative.
- `warnings` (string[]) — What was stripped or would not render — active content, forms, unsafe URLs.

**Errors**

- `400` — The draft does not compile.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/templates/preview -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Welcome","message_type":"transactional","subject":"Hi {{name}}","values":{"name":"Ada"}}'
```

### `GET /api/organizations/:organization_id/templates/:template_id/export`

Export the latest published version as HTML, plain text and MJML.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/:template_id/export`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `template_id` (string, required) — Email template ID inside the active organization.

**Response `200`**

Structure: `TemplateExport`.

- `template_id` (string) — ID of the exported template.
- `version` (int) — Exported version number.
- `subject` (string) — Subject at that version.
- `html` (string) — Compiled HTML.
- `text` (string) — Plain-text alternative.
- `mjml` (string) — MJML source of the compiled blocks.
- `content_hash` (string) — Hash identifying the version.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The template has never been published.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/templates/$TEMPLATE/export -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/templates/import-html`

Import a conservative HTML subset and convert it into canonical blocks.

Active content, forms and unsafe URLs are rejected, not sanitised-and-kept. What survives is stored as blocks, so an imported template behaves exactly like an authored one.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/templates/import-html`
- **Auth:** `organization_template_write` — Active organization identity with template:write permission.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Template name.
- `message_type` (string, required) — What it may be used for. Values: `transactional`, `marketing`.
- `subject` (string, required) — Subject line.
- `html` (string, required) — The HTML to import. Scripts, forms, event handlers and unsafe URLs are rejected.

**Body example**

```json
{
  "name": "Imported",
  "message_type": "transactional",
  "subject": "Imported",
  "html": "<h1>Safe</h1><p>Content</p>"
}
```

**Response `200`**

Structure: `Template`.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

**Errors**

- `400` — The HTML carries active content, a form, or a URL scheme that is not allowed.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/templates/import-html -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"Imported","message_type":"transactional","subject":"Imported","html":"<h1>Safe</h1>"}'
```

## Messages

### `POST /api/messages`

Queue one idempotent transactional delivery for the active organization.

The canonical send route. Suppressions are checked before quota, and quota before any Queue work — a suppressed recipient never costs a send. The response carries no recipient address and no message content.

- **URL:** `https://commsharbor.com/api/messages`
- **Auth:** `organization_messages_send` — Active organization identity with messages:send permission. Idempotency-Key is mandatory.

**Headers**

- `Idempotency-Key` (string, required) — Unique key for this logical message. An equivalent replay returns the SAME delivery and produces no second send; the same key with a different payload conflicts before quota or Queue work.

**Body** (`application/json`)

- `domain_id` (string, required) — Active sending domain to send from.
- `to` (string, required) — Recipient address. It is not echoed back in the response.
- `template_id` (string, required) — Template to render.
- `template_version` (int) — Published version to use. Without it, the latest published version is used — pin it when the content must not drift.
- `variables` (object) — Values for the template's declared variables.
- `reply_to` (string) — Reply-To address, when it differs from the sending domain.

**Body example**

```json
{
  "domain_id": "dom_…",
  "to": "recipient@example.com",
  "template_id": "tpl_…",
  "template_version": 1,
  "variables": {
    "name": "Ada"
  },
  "reply_to": "support@example.com"
}
```

**Response `200`**

Structure: `Send`.

- `delivery` (Delivery) — The delivery record. → see `Delivery` under **Structures**.
- `capacity` (Capacity) — What is left after this send. → see `Capacity` under **Structures**.
- `dispatch` (Dispatch) — The queue work behind it. → see `Dispatch` under **Structures**.
- `replayed` (bool) — True when this was a replay of an earlier identical request.

**Errors**

- `400` — Missing Idempotency-Key, unknown template, or a required variable with no value.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The same Idempotency-Key was used with a different payload, or the recipient is suppressed.
- `429` — No capacity left for this organization, or the global monthly cap was reached.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/messages -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{"domain_id":"dom_1","to":"a@example.com","template_id":"tpl_1"}'
```

### `POST /api/organizations/:organization_id/messages`

Send one transactional message with the organization in the path instead of the header.

Same behaviour and same idempotency as `POST /api/messages`; it exists for clients that cannot set `X-Organization-Id`. Prefer the canonical route.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/messages`
- **Auth:** `organization_messages_send` — Active organization identity with messages:send permission. Idempotency-Key is mandatory.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Headers**

- `Idempotency-Key` (string, required) — Unique key for this logical message. An equivalent replay returns the SAME delivery and produces no second send; the same key with a different payload conflicts before quota or Queue work.

**Body** (`application/json`)

- `domain_id` (string, required) — Active sending domain to send from.
- `to` (string, required) — Recipient address. It is not echoed back in the response.
- `template_id` (string, required) — Template to render.
- `template_version` (int) — Published version to use. Without it, the latest published version is used — pin it when the content must not drift.
- `variables` (object) — Values for the template's declared variables.
- `reply_to` (string) — Reply-To address, when it differs from the sending domain.

**Body example**

```json
{
  "domain_id": "dom_…",
  "to": "recipient@example.com",
  "template_id": "tpl_…",
  "variables": {
    "name": "Ada"
  }
}
```

**Response `200`**

Structure: `Send`.

- `delivery` (Delivery) — The delivery record. → see `Delivery` under **Structures**.
- `capacity` (Capacity) — What is left after this send. → see `Capacity` under **Structures**.
- `dispatch` (Dispatch) — The queue work behind it. → see `Dispatch` under **Structures**.
- `replayed` (bool) — True when this was a replay of an earlier identical request.

**Errors**

- `400` — Missing Idempotency-Key, unknown template, or a required variable with no value.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — Key reused with a different payload, or the recipient is suppressed.
- `429` — No capacity left.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/messages -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{"domain_id":"dom_1","to":"a@example.com","template_id":"tpl_1"}'
```

## Campaigns

### `GET /api/organizations/:organization_id/campaigns`

List the campaigns of the organization.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Query**

- `cursor` (string) — Opaque cursor from the previous page. Do not build or parse it.
- `limit` (int) — Page size, from 1 to 100. Default: `50`.

**Response `200`**

Structure: `PageCamel<Campaign>`.

- `items` (Campaign[]) — The records on this page. → see `Campaign` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/campaigns -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/campaigns`

Create a campaign draft from an active domain, an audience and a published marketing template.

All three must already exist and be usable: a draft cannot be created against an unverified domain or an unpublished template.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `name` (string, required) — Campaign name.
- `domain_id` (string, required) — Active sending domain to send from.
- `audience_id` (string, required) — Audience the campaign goes to.
- `template_id` (string, required) — Published MARKETING template. A transactional template is refused here.
- `template_version` (int) — Published version to freeze into the campaign.

**Body example**

```json
{
  "name": "August update",
  "domain_id": "dom_…",
  "audience_id": "aud_…",
  "template_id": "tpl_…",
  "template_version": 1
}
```

**Response `200`**

Structure: `Campaign`.

- `id` (string) — Campaign ID.
- `name` (string) — Campaign name.
- `status` (string) — Where the campaign is.
- `domain_id` (string) — Domain it sends from.
- `audience_id` (string) — Audience it goes to.
- `template_id` (string) — Published marketing template used.
- `template_version` (int) — Frozen template version.
- `scheduled_for` (string, may be null) — When it is scheduled, in the organization's timezone.
- `frozen_recipients` (int, may be null) — How many recipients were frozen at launch.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `400` — Missing field.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The domain is not active, the template is not published, or it is transactional.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/campaigns -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"name":"August update","domain_id":"dom_1","audience_id":"aud_1","template_id":"tpl_1"}'
```

### `GET /api/organizations/:organization_id/campaigns/:campaign_id`

Read one campaign, without any recipient data.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns/:campaign_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `campaign_id` (string, required) — Campaign ID inside the active organization.

**Response `200`**

Structure: `Campaign`.

- `id` (string) — Campaign ID.
- `name` (string) — Campaign name.
- `status` (string) — Where the campaign is.
- `domain_id` (string) — Domain it sends from.
- `audience_id` (string) — Audience it goes to.
- `template_id` (string) — Published marketing template used.
- `template_version` (int) — Frozen template version.
- `scheduled_for` (string, may be null) — When it is scheduled, in the organization's timezone.
- `frozen_recipients` (int, may be null) — How many recipients were frozen at launch.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/campaigns/$CAMPAIGN -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/campaigns/:campaign_id`

Edit a draft, or pause, resume or cancel a campaign that already launched.

Content can only change while the campaign is a draft. After launch this route moves state — the frozen recipient set and the frozen template version do not change.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns/:campaign_id`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `campaign_id` (string, required) — Campaign ID inside the active organization.

**Body** (`application/json`)

- `name` (string) — New campaign name.
- `domain_id` (string) — New sending domain, while still a draft.
- `audience_id` (string) — New audience, while still a draft.
- `template_id` (string) — New published marketing template, while still a draft.
- `template_version` (int) — Published version to freeze into the campaign.
- `status` (string) — Move a launched campaign. Values: `paused`, `sending`, `cancelled`.

**Body example**

```json
{
  "name": "August update",
  "status": "paused"
}
```

**Response `200`**

Structure: `Campaign`.

- `id` (string) — Campaign ID.
- `name` (string) — Campaign name.
- `status` (string) — Where the campaign is.
- `domain_id` (string) — Domain it sends from.
- `audience_id` (string) — Audience it goes to.
- `template_id` (string) — Published marketing template used.
- `template_version` (int) — Frozen template version.
- `scheduled_for` (string, may be null) — When it is scheduled, in the organization's timezone.
- `frozen_recipients` (int, may be null) — How many recipients were frozen at launch.
- `created_at` (string) — Creation time (UTC).

**Errors**

- `400` — Unknown status.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — Editing content after launch, or resuming while marketing is paused for the organization.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG/campaigns/$CAMPAIGN -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"status":"paused"}'
```

### `POST /api/organizations/:organization_id/campaigns/:campaign_id/launch`

Freeze the eligible recipients and launch — or schedule — the campaign, exactly once.

The freeze happens once and never again: consent, suppressions and audience membership are evaluated at this moment, and the resulting set is what gets sent. Replaying the same Idempotency-Key returns the same campaign and produces no second dispatch.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns/:campaign_id/launch`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `campaign_id` (string, required) — Campaign ID inside the active organization.

**Headers**

- `Idempotency-Key` (string, required) — Stable key for this launch. A replay returns the same campaign and never freezes a second recipient set.

**Body** (`application/json`)

- `scheduled_for` (string) — When to send, ISO-8601 with offset, interpreted in the organization's timezone. Omit to send now.

**Body example**

```json
{
  "scheduled_for": "2026-08-30T14:00:00-03:00"
}
```

**Response `200`**

- `campaign` (Campaign) — The campaign, now scheduled or sending, with the frozen recipient count. → see `Campaign` under **Structures**.
- `dispatch_job_id` (string, may be null) — The dispatch job that will walk the frozen set.
- `replayed` (bool) — True when this was a replay and nothing new was frozen or queued.

**Errors**

- `400` — Missing Idempotency-Key or an unparseable schedule.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — Already launched, marketing paused for the organization, or no eligible recipients.
- `429` — Not enough capacity for the frozen recipient set.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/campaigns/$CAMPAIGN/launch -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{"scheduled_for":"2026-08-30T14:00:00-03:00"}'
```

### `GET /api/organizations/:organization_id/campaigns/:campaign_id/report`

Reconcile a campaign: delivery counts and normalized feedback counts.

Counts only. Which specific person opened what is not something this API answers.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/campaigns/:campaign_id/report`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `campaign_id` (string, required) — Campaign ID inside the active organization.

**Response `200`**

Structure: `CampaignReport`.

- `campaign` (Campaign) — The campaign being reported on. → see `Campaign` under **Structures**.
- `deliveries` (object) — Delivery counts by state.
- `events` (object) — Normalized feedback counts by event type.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/campaigns/$CAMPAIGN/report -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

## Deliverability

### `GET /api/organizations/:organization_id/messaging-settings`

Read the organization's timezone and whether marketing is currently paused.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/messaging-settings`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `MessagingSettings`.

- `timezone` (string) — IANA timezone used to schedule campaigns, e.g. `America/Sao_Paulo`.
- `marketing_state` (string) — Whether marketing may go out.
- `paused_reason` (string, may be null) — Why marketing was paused, when it was.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/messaging-settings -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `PATCH /api/organizations/:organization_id/messaging-settings`

Change the scheduling timezone, or pause and safely resume marketing.

Pausing is always allowed. Resuming is not: if the pause came from reputation or SES tenant risk, a healthy observation has to exist first.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/messaging-settings`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `timezone` (string) — IANA timezone used to interpret campaign schedules, e.g. `America/Sao_Paulo`.
- `marketing_state` (string) — Whether marketing may go out. Values: `active`, `paused`.

**Body example**

```json
{
  "timezone": "America/Sao_Paulo",
  "marketing_state": "active"
}
```

**Response `200`**

Structure: `MessagingSettings`.

- `timezone` (string) — IANA timezone used to schedule campaigns, e.g. `America/Sao_Paulo`.
- `marketing_state` (string) — Whether marketing may go out.
- `paused_reason` (string, may be null) — Why marketing was paused, when it was.

**Errors**

- `400` — Unknown timezone or state.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — Resuming while the risk that caused the pause is still observed.

**Example**

```sh
curl -s -XPATCH https://commsharbor.com/api/organizations/$ORG/messaging-settings -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"timezone":"America/Sao_Paulo"}'
```

### `GET /api/organizations/:organization_id/deliverability`

Read delivery, backlog, suppression, reputation and dead-letter aggregates in one call.

This is the operator's single view of whether sending is healthy. It carries no recipient PII.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deliverability`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `settings` (MessagingSettings) — Timezone and marketing state. → see `MessagingSettings` under **Structures**.
- `deliveries` (object) — Delivery counts by state.
- `backlog` (object) — What is still queued and how old the oldest item is.
- `dead_letters` (object) — Dead-letter counts by origin.
- `suppressions` (object) — Suppression counts by scope.
- `domains` (object[]) — Per-domain reputation and state.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/deliverability -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/domains/:domain_id/report`

Read delivery and feedback aggregates for one sending domain.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/domains/:domain_id/report`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `domain_id` (string, required) — Sending domain ID, from the domains listing.

**Response `200`**

- `domain` (Domain) — The domain being reported on. → see `Domain` under **Structures**.
- `deliveries` (object) — Delivery counts by state for this domain.
- `events` (object) — Normalized feedback counts by event type.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/domains/$DOMAIN/report -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

## Webhooks

### `GET /api/organizations/:organization_id/webhooks`

List the webhook endpoints of the organization, without their signing secrets.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/webhooks`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `Lista<Webhook>`.

- `items` (Webhook[]) — Every record in the collection. → see `Webhook` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/webhooks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/webhooks`

Create an HTTPS webhook and reveal its signing secret exactly once.

Deliveries are signed with timestamped HMAC-SHA256 and retried with exponential backoff; what still fails lands in the tenant-scoped dead-letter queue. Store the secret now — it is never shown again.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/webhooks`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `url` (string, required) — Public HTTPS destination. Plain HTTP is refused.
- `event_types` (string[], required) — Which events to deliver, e.g. `Delivery`, `Bounce`, `Complaint`.

**Body example**

```json
{
  "url": "https://receiver.example.com/events",
  "event_types": [
    "Delivery",
    "Bounce"
  ]
}
```

**Response `200`**

Structure: `Webhook`.

- `id` (string) — Webhook ID.
- `url` (string) — HTTPS destination.
- `event_types` (string[]) — Which events are delivered to it.
- `status` (string) — Whether it is receiving.
- `created_at` (string) — Creation time (UTC).
- `secret` (string, optional) — Signing secret for timestamped HMAC-SHA256. Present only on the response that created it.

**Errors**

- `400` — Non-HTTPS URL or an unknown event type.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/webhooks -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"url":"https://receiver.example.com/events","event_types":["Delivery"]}'
```

### `GET /api/organizations/:organization_id/webhooks/:webhook_id`

Read one webhook, without its signing secret.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/webhooks/:webhook_id`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `webhook_id` (string, required) — Webhook endpoint ID. Signing secrets are revealed once, at creation.

**Response `200`**

Structure: `Webhook`.

- `id` (string) — Webhook ID.
- `url` (string) — HTTPS destination.
- `event_types` (string[]) — Which events are delivered to it.
- `status` (string) — Whether it is receiving.
- `created_at` (string) — Creation time (UTC).
- `secret` (string, optional) — Signing secret for timestamped HMAC-SHA256. Present only on the response that created it.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/webhooks/$WEBHOOK -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `DELETE /api/organizations/:organization_id/webhooks/:webhook_id`

Disable a webhook without deleting the evidence of what it already delivered.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/webhooks/:webhook_id`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `webhook_id` (string, required) — Webhook endpoint ID. Signing secrets are revealed once, at creation.

**Response `200`**

Structure: `Webhook`.

- `id` (string) — Webhook ID.
- `url` (string) — HTTPS destination.
- `event_types` (string[]) — Which events are delivered to it.
- `status` (string) — Whether it is receiving.
- `created_at` (string) — Creation time (UTC).
- `secret` (string, optional) — Signing secret for timestamped HMAC-SHA256. Present only on the response that created it.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XDELETE https://commsharbor.com/api/organizations/$ORG/webhooks/$WEBHOOK -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/webhooks/:webhook_id/deliveries`

List the signed attempts made to one webhook and their retry state.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/webhooks/:webhook_id/deliveries`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `webhook_id` (string, required) — Webhook endpoint ID. Signing secrets are revealed once, at creation.

**Response `200`**

- `items` (object[]) — One record per attempt: status, response code, when it ran and when it will retry.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/webhooks/$WEBHOOK/deliveries -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/dead-letters`

Inspect the tenant's dead letters by opaque record ID.

What ended up here after every retry. Records are addressed by opaque ID and carry no recipient PII.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/dead-letters`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `items` (object[]) — One record per dead letter: origin, reason, when it failed.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/dead-letters -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/dead-letters/:record_id/replay`

Replay one campaign or webhook dead letter, by name.

One record at a time, addressed explicitly. There is no "replay everything": a bulk replay of an unknown set is how a bad hour becomes a bad day.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/dead-letters/:record_id/replay`
- **Auth:** `organization_campaign_write` — Active organization identity with campaign:write permission. Campaign launches require Idempotency-Key.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `record_id` (string, required) — Dead-letter record ID from the dead-letter listing.

**Body example**

```json
{}
```

**Response `200`**

- `dead_letter` (object) — The record with its new replay state.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The record was already replayed or is not replayable.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/dead-letters/$RECORD/replay -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

## Billing

### `GET /api/billing`

Read the versioned trial, pass and top-up catalog, plus the x402 network in force.

Public and unauthenticated: an agent should be able to learn what things cost before deciding whether to sign up at all.

- **URL:** `https://commsharbor.com/api/billing`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Response `200`**

Structure: `BillingPublic`.

- `catalog` (BillingCatalog) — Plans and prices in force. → see `BillingCatalog` under **Structures**.
- `payment` (PlanoX402) — x402 configuration: network, asset, facilitator and where to pay. → see `PlanoX402` under **Structures**.
- `invite_only` (bool) — Whether new organizations require an invitation.

**Example**

```sh
curl -s https://commsharbor.com/api/billing
```

### `GET /api/organizations/:organization_id/billing`

Read this organization's entitlement, quota allocation and expiration warning.

Read this before a bulk send: `state` says how many sends remain and `warning` says when the entitlement runs out.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/billing`
- **Auth:** `organization` — Session plus X-Organization-Id membership, or a scoped API key that determines the organization.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `BillingTenant`.

- `catalog` (BillingCatalog) — Plans and prices in force. → see `BillingCatalog` under **Structures**.
- `state` (object) — Current entitlement: what is active, how many sends remain and when it expires.
- `warning` (object, may be null) — Expiration or exhaustion warning, when one applies.
- `payment` (PlanoX402) — x402 configuration for paying. → see `PlanoX402` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/billing -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/billing/purchases/:action`

Request a pass or a top-up. While live checkout is off, this answers with an x402 challenge.

The response is a standard **402 with `accepts[]`** unless `catalog.checkout_live` is true — nobody is charged by accident. The Idempotency-Key makes a retry safe: the same logical purchase never grants entitlement twice.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/billing/purchases/:action`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `action` (string, required) — Which purchase to request. Values: `pass`, `topup`.

**Headers**

- `Idempotency-Key` (string, required) — Stable key for this logical purchase. A replay returns the same state and grants nothing extra.
- `X-PAYMENT` (string) — Standard x402 payment payload, when live checkout is explicitly enabled.

**Body example**

```json
{}
```

**Response `200`**

- `replayed` (bool) — True when this key had already been used and nothing new was granted.
- `state` (object) — The entitlement after the request: what is active, what remains, when it expires.

**Errors**

- `400` — Missing Idempotency-Key, or an action other than `pass`/`topup`.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `402` — Payment required — the body carries `accepts[]`. This is the normal answer while live checkout is disabled.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The same key was used for a different purchase.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/billing/purchases/pass -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H "Idempotency-Key: $KEY" -H 'content-type: application/json' -d '{}'
```

## Operations

### `GET /api/organizations/:organization_id/operations`

List the organization's current operational alerts.

Covers dead letters, backlog, worker and SNS failures, reputation, paused sending, quota and conservative SES/SNS cost capacity — never with recipient PII.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/operations`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

- `items` (object[]) — One entry per active alert, with its kind, severity and what to do about it.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/operations -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/operations`

Re-observe alerts, quota and global capacity right now.

The GET reads what was last stored; this goes and looks again. Same distinction as domain verification.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/operations`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body example**

```json
{}
```

**Response `200`**

Structure: `Operations`.

- `alerts` (object[]) — Current alerts, each with a kind, a severity and what to do.
- `billing` (object) — Quota position at the time of the observation.
- `capacity` (object) — Conservative SES and SNS capacity observations.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/operations -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

### `GET /api/metrics`

Last-7-day metrics for the operator dashboard; with the token, payments come along.

Without credentials it returns product usage: deliveries per day and organization totals. With `METRICS_TOKEN` as Bearer it adds `payments` — x402 settled on Base mainnet only.

- **URL:** `https://commsharbor.com/api/metrics`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>` to include the financial block; a wrong token is 401.

**Response `200`**

Structure: `Metricas`.

- `app` (string) — Product name.
- `today` (string) — Reference day (UTC, YYYY-MM-DD).
- `today_visits` (int) — Interface visits counted today.
- `today_contacts` (int, optional) — Contact messages today. Only with `METRICS_TOKEN`: contact counts never leave without the token.
- `days` (object[]) — One row per day of the window, with each metric's count.
- `usage` (object) — `entregas`: deliveries per day — real product usage, not catalog load.
- `accounts` (object) — `organizacoes`: total organizations registered.
- `financeiro` (object, optional) — Day aggregate: `hoje_usd`, `hoje_count`, `rede`. Only with `METRICS_TOKEN`: money never leaves without the token; the full series is `payments`.
- `payments` (object, optional) — x402 financial summary; METRICS_TOKEN only.

**Errors**

- `401` — Wrong operator token.
- `503` — Worker without METRICS_TOKEN configured.

**Example**

```sh
curl -s https://commsharbor.com/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## Data

### `GET /api/organizations/:organization_id/data-exports`

List the tenant data exports, which are retained for seven days.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/data-exports`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `Lista<DataExport>`.

- `items` (DataExport[]) — Every record in the collection. → see `DataExport` under **Structures**.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/data-exports -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/data-exports`

Create a tenant-scoped JSON export of the organization's data.

Scoped to one organization by construction: an export can never contain another tenant's data.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/data-exports`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body example**

```json
{}
```

**Response `200`**

Structure: `DataExport`.

- `id` (string) — Export ID.
- `status` (string) — Where the export stands.
- `expires_at` (string) — When the file is deleted (UTC).
- `created_at` (string) — Creation time (UTC).

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/data-exports -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

### `GET /api/organizations/:organization_id/data-exports/:export_id`

Download one tenant-scoped JSON export before it expires.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/data-exports/:export_id`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `export_id` (string, required) — Tenant data export ID. Exports expire seven days after they are created.

**Response `200`**

`application/json` as an attachment, with the organization's data.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The export is not ready yet.
- `410` — It expired after seven days.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/data-exports/$EXPORT -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `GET /api/organizations/:organization_id/deletion-requests`

Read the latest erasure request and where it is in the grace period.

`status: "none"` means no erasure was ever requested — the resource always answers, so a client never has to interpret a 404 as "nothing scheduled".

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deletion-requests`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Response `200`**

Structure: `Deletion`.

- `id` (string, may be null) — Deletion request ID.
- `status` (string) — Where the request stands.
- `scheduled_for` (string, may be null) — When erasure runs, after the grace period (UTC).
- `requested_by` (string, may be null) — Who scheduled it.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.

**Example**

```sh
curl -s https://commsharbor.com/api/organizations/$ORG/deletion-requests -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG"
```

### `POST /api/organizations/:organization_id/deletion-requests`

Schedule the erasure of the organization, after a seven-day grace period.

The confirmation phrase must be exactly `delete <organization_id>` — typing the id is the point, so nobody erases the wrong tenant by clicking. After erasure only pseudonymous financial and audit evidence remains.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deletion-requests`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.

**Body** (`application/json`)

- `confirmation` (string, required) — The exact phrase `delete <organization_id>`.

**Body example**

```json
{
  "confirmation": "delete org_…"
}
```

**Response `200`**

Structure: `Deletion`.

- `id` (string, may be null) — Deletion request ID.
- `status` (string) — Where the request stands.
- `scheduled_for` (string, may be null) — When erasure runs, after the grace period (UTC).
- `requested_by` (string, may be null) — Who scheduled it.

**Errors**

- `400` — The confirmation phrase does not match this organization exactly.
- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — An erasure is already scheduled.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/deletion-requests -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{"confirmation":"delete $ORG"}'
```

### `POST /api/organizations/:organization_id/deletion-requests/:request_id/cancel`

Cancel a scheduled erasure while it is still inside the grace period.

That is what the seven days are for: after they pass, there is nothing left to cancel.

- **URL:** `https://commsharbor.com/api/organizations/:organization_id/deletion-requests/:request_id/cancel`
- **Auth:** `organization_admin` — Human organization member with the required role; API keys cannot manage credentials or membership.

**Path parameters**

- `organization_id` (string, required) — Active organization ID. It must match the organization your session header or API key resolves to.
- `request_id` (string, required) — Deletion request ID from the deletion-requests resource.

**Body example**

```json
{}
```

**Response `200`**

Structure: `Deletion`.

- `id` (string, may be null) — Deletion request ID.
- `status` (string) — Where the request stands.
- `scheduled_for` (string, may be null) — When erasure runs, after the grace period (UTC).
- `requested_by` (string, may be null) — Who scheduled it.

**Errors**

- `401` — No session, no API key, or the credential does not resolve to this organization.
- `403` — The identity is valid but lacks the required role or scope for this operation.
- `404` — The resource does not exist in this organization. Another tenant's ID answers the same 404 — the API never confirms that it exists elsewhere.
- `409` — The erasure already ran, or the request was cancelled before.

**Example**

```sh
curl -s -XPOST https://commsharbor.com/api/organizations/$ORG/deletion-requests/$REQUEST/cancel -H "Authorization: Bearer $TOKEN" -H "X-Organization-Id: $ORG" -H 'content-type: application/json' -d '{}'
```

## Credit

### `POST /api/credito`

Top up prepaid credit: pay once with x402 and get the token that debits on any API of the house.

- **URL:** `https://commsharbor.com/api/credito`
- **Auth:** `none` — Public endpoint. No tenant data is returned.

**Query**

- `usd` (int, required) — Package: 1, 5, 10 ou 25 dollars.

**Response `200`**

- `token` (string) — Bearer token for the balance (`cred_…`). Shown ONCE — it cannot be recovered.
- `saldo_usd` (string) — Credited balance.
- `guarde` (string) — Warning that the token is the bearer of the credit.
- `usar` (string) — How to present the token on paid routes.
- `saldo_em` (string) — Where to check balance and statement.

**Errors**

- `400` — Package outside the list (1, 5, 10 ou 25).
- `402` — Unpaid — the body carries the x402 `accepts[]`.

**Example**

```sh
curl -s -XPOST 'https://commsharbor.com/api/credito?usd=10'
```

### `GET /api/credito`

Credit balance and statement — the latest movements, without returning the token.

- **URL:** `https://commsharbor.com/api/credito`
- **Auth:** `credito` — Prepaid credit token in `Authorization: Bearer cred_…` (or the `X-Credito` header). Not an account: it is a bearer of balance.

**Response `200`**

- `saldo_micros` (int) — Balance in micro-dollars (1e-6 USD).
- `saldo_usd` (string) — Formatted balance.
- `criado_em` (string) — When the credit was opened.
- `movimentos` (object[]) — Recent credits and debits, with product and resource.

**Errors**

- `401` — No token, or unknown token.

**Example**

```sh
curl -s https://commsharbor.com/api/credito -H 'Authorization: Bearer cred_…'
```

## Structures

### `ApiIndex`

The self-describing index of the whole API.

- `name` (string) — Product name.
- `description` (string) — What the product does, in one sentence.
- `build` (string) — Deployed commit.
- `environment` (string) — Which environment answered: `production`, `staging` or `local`.
- `base_url` (string) — Origin this API is served from.
- `docs` (object) — Links to llms.txt, llms-full.txt, openapi.json, the MCP endpoint and the human UI.
- `auth` (object) — Every authentication mode and how to obtain it.
- `endpoints` (object[]) — Every endpoint with method, path, auth, absolute URL and what it returns.
- `mcp` (object) — Remote MCP endpoint and transport.
- `mcp_tools` (string[]) — Name of every MCP tool.

### `Health`

Liveness and the commit currently serving. Smoke tests wait for their own deploy here instead of racing edge propagation.

- `ok` (bool) — Always true when the Worker answers.
- `app` (string) — Product name.
- `build` (string) — Deployed commit; CI passes the short SHA at deploy time.
- `environment` (string) — Which environment answered.
- `timestamp` (string) — Response time (UTC, ISO-8601).

### `User`

The person behind the session.

- `id` (string) — User ID.
- `email` (string) — Email address confirmed by one-time code.

### `Ok`

Write confirmation for an operation with no body of its own.

- `ok` (bool) — Always true — failures arrive as a 4xx/5xx status, never as `ok:false`.

### `Profile`

Personal preferences. They belong to the person, not to any organization.

- `display_name` (string, may be null) — Name shown in the interface.
- `locale` (string, may be null) — Preferred language, e.g. `en` or `pt-br`.

### `Organization`

A tenant. Every piece of customer data in this product is scoped to exactly one.

- `id` (string) — Organization ID, used in every tenant route.
- `name` (string) — Display name.
- `sending_domain` (string, may be null) — Domain the organization sends from.
- `created_at` (string) — Creation time (UTC, ISO-8601).

### `Identity`

Who the current credential resolves to. Read this before a write when you are not sure which organization is active.

- `kind` (string) — How the identity was resolved.
- `organizationId` (string) — The active organization.
- `userId` (string, optional) — The person, when a session is in play.
- `email` (string, optional) — The person's e-mail, on a session.
- `sessionId` (string, optional) — Session identifier, on a session.
- `role` (string, optional) — Role inside that organization; sessions only.
- `organization` (object, optional) — `{ id, name, slug }` of the active organization; sessions only.
- `apiKeyId` (string, optional) — Which key answered, on an API key.
- `scopes` (string[], optional) — Granted scopes; present on an API key, which carries its own narrower set.

### `Membership`

One person's place in one organization.

- `organization_id` (string) — The organization.
- `user_id` (string) — The member.
- `role` (string) — What the member may do.
- `created_at` (string) — When the membership started (UTC).

### `Invitation`

An invitation into an existing organization. The token is revealed once, at creation, and never listed again.

- `id` (string) — Invitation ID.
- `email` (string) — Who is being invited.
- `role` (string) — Role the invitation grants.
- `expires_at` (string) — When the invitation stops working (UTC).
- `invitation_token` (string, optional) — The invitation token. Present only on the response that created it.
- `token_notice` (string, optional) — Reminder that the token is shown once.

### `ApiKey`

A scoped machine credential. It determines its own organization and rejects a conflicting header.

- `id` (string) — API key ID, used to revoke it.
- `name` (string) — Label chosen at creation.
- `scopes` (string[]) — What this key may do, e.g. `crm:read`, `messages:send`.
- `prefix` (string) — Token prefix, so a key can be recognised in a list.
- `last_used_at` (string, may be null) — When the key last answered; null if never.
- `revoked_at` (string, may be null) — When it was revoked; null while it is still valid.
- `created_at` (string) — Creation time (UTC).
- `token` (string, optional) — The key itself. Present only on the response that created it — it is never shown again.

### `PageCamel<AuditEvent>`

The same listing with the cursor in camelCase. Older resources ship it this way and the name is kept because changing it would break clients already reading it.

- `items` (AuditEvent[]) — The records on this page. → see `AuditEvent` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `AuditEvent`

One append-only record of something that happened in the organization. Audit is never rewritten.

- `id` (string) — Event ID.
- `action` (string) — What happened, e.g. `api_key.created`.
- `actor_user_id` (string, may be null) — Who did it; null when the actor was a key or the system.
- `target` (string, may be null) — What it happened to.
- `metadata` (object) — Extra context for this action. Never contains recipient PII.
- `created_at` (string) — When it happened (UTC).

### `Lista<Domain>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (Domain[]) — Every record in the collection. → see `Domain` under **Structures**.

### `Domain`

A sending domain. State is only ever what was OBSERVED at SES and DNS — this product does not infer it.

- `id` (string) — Domain ID.
- `domain` (string) — The domain itself, e.g. `example.com`.
- `status` (string) — Last observed state.
- `dkim_tokens` (string[]) — CNAME records to publish for DKIM.
- `dmarc` (object, may be null) — DMARC policy observed at the domain.
- `mail_from` (object, may be null) — Custom MAIL FROM subdomain and its observed state.
- `last_observed_at` (string, may be null) — When SES and DNS were last actually checked (UTC).
- `created_at` (string) — Registration time (UTC).

### `Provisioning`

The idempotent SES provisioning queued for a domain. Asking twice does not provision twice.

- `queued` (bool) — Whether this call enqueued provisioning work.
- `job_id` (string, may be null) — The provisioning job, when one was created.

### `Delivery`

One queued message. It never carries the recipient address or the body — that is deliberate, not an omission.

- `id` (string) — Delivery ID.
- `status` (string) — Delivery state, authoritative in D1.
- `domain_id` (string) — Domain it was sent from.
- `template_id` (string, may be null) — Template used.
- `template_version` (int, may be null) — Immutable template version used.
- `ses_message_id` (string, may be null) — SES MessageId, for correlating with AWS.
- `created_at` (string) — When it was queued (UTC).

### `Capacity`

What is left to send. The bootstrap global cap always prevails over any tenant allowance.

- `remaining` (int) — Sends still available to this organization.
- `global_remaining` (int) — Sends still available across the whole platform this month.
- `hard_cap` (int) — The global monthly cap on real recipients. Nothing raises it.

### `Dispatch`

What actually happened to the queue message behind this send.

- `queued` (bool) — Whether a Queue message was produced.
- `job_id` (string, may be null) — Dispatch job ID, when one was created.

### `Lista<Delivery>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (Delivery[]) — Every record in the collection. → see `Delivery` under **Structures**.

### `Lista<DeliveryEvent>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (DeliveryEvent[]) — Every record in the collection. → see `DeliveryEvent` under **Structures**.

### `DeliveryEvent`

A normalized SES feedback event. Open and Click are ADDITIVE — they never overwrite delivery state.

- `id` (string) — Event ID.
- `event_type` (string) — What SES reported.
- `occurred_at` (string) — When SES says it happened (UTC).
- `detail` (object) — Normalized detail for this event type, without recipient PII.

### `Page<Contact>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Contact[]) — The records on this page. → see `Contact` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Contact`

A person in the tenant CRM. Marketing consent is a separate resource — being in the CRM is not permission to email.

- `id` (string) — Contact ID.
- `email` (string) — Email address, normalized and never truncated.
- `first_name` (string, may be null) — Given name.
- `last_name` (string, may be null) — Family name.
- `company_id` (string, may be null) — Company this contact belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this contact — agents never build the path by hand.

### `Page<Company>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Company[]) — The records on this page. → see `Company` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Company`

An organization in the tenant CRM — a customer of the customer, not a tenant of this product.

- `id` (string) — Company ID.
- `name` (string) — Company name.
- `domain` (string, may be null) — Primary domain.
- `website` (string, may be null) — Website URL.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this company.

### `Page<Pipeline>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Pipeline[]) — The records on this page. → see `Pipeline` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Pipeline`

A named sequence of stages that deals move through.

- `id` (string) — Pipeline ID.
- `name` (string) — Pipeline name.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this pipeline.

### `Page<Deal>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Deal[]) — The records on this page. → see `Deal` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Deal`

An opportunity moving through a pipeline. Money is stored in minor units to avoid float rounding.

- `id` (string) — Deal ID.
- `title` (string) — What the deal is.
- `pipeline_id` (string) — Pipeline the deal lives in.
- `stage_id` (string) — Current stage.
- `status` (string) — Where it stands.
- `value_minor` (int, may be null) — Value in the currency's minor unit — cents, not dollars.
- `currency` (string, may be null) — ISO 4217 code for `value_minor`.
- `contact_id` (string, may be null) — Main contact on the deal.
- `company_id` (string, may be null) — Company on the deal.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this deal.

### `Page<Activity>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Activity[]) — The records on this page. → see `Activity` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Activity`

Something that happened with a contact, company or deal — a note, a call, a meeting.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`, `call`, `meeting`.
- `note` (string) — The text of the activity.
- `deal_id` (string, may be null) — Deal it refers to.
- `contact_id` (string, may be null) — Contact it refers to.
- `company_id` (string, may be null) — Company it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

### `Page<Task>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Task[]) — The records on this page. → see `Task` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Task`

Work someone still has to do, inside the tenant CRM.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Member responsible for it.
- `deal_id` (string, may be null) — Deal the task belongs to.
- `contact_id` (string, may be null) — Contact the task belongs to.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

### `Page<Stage>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Stage[]) — The records on this page. → see `Stage` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Stage`

One step of a pipeline. Stages belong to a pipeline and are addressed under it.

- `id` (string) — Stage ID.
- `pipeline_id` (string) — Pipeline this stage belongs to.
- `name` (string) — Stage name, e.g. `Proposal`.
- `position` (int) — Order within the pipeline, lowest first.
- `probability` (int, may be null) — Chance of winning at this stage, 0 to 100.
- `url` (string) — Absolute URL of this stage.

### `Page<Lead>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Lead[]) — The records on this page. → see `Lead` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Lead`

A prospective ORGANIZATION in the platform CRM. This is our own pipeline about tenants — it is not tenant data, and it is only reachable with an explicit platform grant.

- `id` (string) — Lead ID.
- `email` (string) — Contact email for the lead.
- `name` (string) — Who to talk to.
- `company_name` (string, may be null) — Name of the prospective organization.
- `source` (string, may be null) — Where the lead came from, e.g. `manual`.
- `stage` (string) — Where the lead is in our own funnel, e.g. `new`.
- `organization_id` (string, may be null) — The organization this lead became, once it converted.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this lead.

### `Page<PlatformTask>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (PlatformTask[]) — The records on this page. → see `PlatformTask` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `PlatformTask`

Work on a platform lead. Same idea as a CRM task, different subject: this one is about a prospective tenant, not about a tenant's customer.

- `id` (string) — Task ID.
- `title` (string) — What has to be done.
- `status` (string) — Current state.
- `lead_id` (string, may be null) — Lead the task belongs to.
- `due_at` (string, may be null) — When it is due (UTC).
- `assignee_user_id` (string, may be null) — Who is responsible.
- `created_at` (string) — Creation time (UTC).
- `updated_at` (string, may be null) — Last change (UTC).
- `url` (string) — Absolute URL of this task.

### `Page<PlatformActivity>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (PlatformActivity[]) — The records on this page. → see `PlatformActivity` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `PlatformActivity`

Something that happened with a platform lead — our note about a prospective tenant.

- `id` (string) — Activity ID.
- `activity_type` (string) — What kind of activity it was, e.g. `note`.
- `note` (string) — The text of the activity.
- `lead_id` (string) — Lead it refers to.
- `created_at` (string) — Creation time (UTC).
- `url` (string) — Absolute URL of this activity.

### `Marketing`

Consent and preference for one contact. Recording consent NEVER restores a previous unsubscribe — that asymmetry is the point.

- `marketing_enabled` (bool) — Whether marketing may be sent to this contact right now.
- `basis` (string, may be null) — Why sending is allowed.
- `source` (string, may be null) — Where the consent came from, e.g. a signup form.
- `captured_at` (string, may be null) — When consent was captured (UTC).
- `unsubscribed_at` (string, may be null) — When the contact unsubscribed; null when they never did.

### `PreferenceToken`

Signed URLs for the preference centre and one-click unsubscribe, plus the headers to put in the message.

- `api_url` (string) — Machine-readable preference endpoint.
- `preferences_url` (string) — Human preference page.
- `unsubscribe_url` (string) — RFC 8058 one-click unsubscribe endpoint.
- `marketing_headers` (object) — `List-Unsubscribe` and `List-Unsubscribe-Post`, ready to add to the message.

### `PreferenceState`

What the signed capability reveals. No login, and no email address is exposed.

- `marketing_enabled` (bool) — Whether marketing may be sent.
- `unsubscribed_at` (string, may be null) — When the contact unsubscribed.
- `expires_at` (string) — When this capability stops working (UTC).

### `Send`

The result of queueing one message. `replayed` true means an equivalent Idempotency-Key already existed and NO second message was produced.

- `delivery` (Delivery) — The delivery record. → see `Delivery` under **Structures**.
- `capacity` (Capacity) — What is left after this send. → see `Capacity` under **Structures**.
- `dispatch` (Dispatch) — The queue work behind it. → see `Dispatch` under **Structures**.
- `replayed` (bool) — True when this was a replay of an earlier identical request.

### `Page<ContactImport>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (ContactImport[]) — The records on this page. → see `ContactImport` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `ContactImport`

A CSV import of contacts, with the consent declaration that made it legal to import them.

- `id` (string) — Import ID.
- `status` (string) — Where the import stands.
- `rows` (int) — Rows found in the CSV.
- `accepted` (int) — Rows that will be imported.
- `rejected` (int) — Rows rejected, with reasons in the errors listing.
- `basis` (string) — Declared consent basis for every row.
- `file_id` (string, may be null) — Stored file, downloadable for seven days.
- `created_at` (string) — Upload time (UTC).

### `ImportError`

One rejected row, addressed by line number so it can be fixed in the source file.

- `row` (int) — 1-based row number in the uploaded CSV.
- `code` (string) — Why it was rejected, e.g. `invalid_email`.
- `message` (string) — The reason in a sentence.

### `Page<ImportError>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (ImportError[]) — The records on this page. → see `ImportError` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Page<Suppression>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Suppression[]) — The records on this page. → see `Suppression` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Suppression`

A recipient that must not be emailed. Suppressions are checked BEFORE quota and before any queue work.

- `id` (string) — Suppression ID.
- `scope` (string) — How far it reaches.
- `reason` (string) — Why it exists, e.g. `bounce`, `complaint`, `manual`.
- `contact_id` (string, may be null) — CRM contact it matches, when known.
- `created_at` (string) — When it was added (UTC).

### `Page<Audience>`

Cursor-paginated listing. A null cursor means this was the last page.

- `items` (Audience[]) — The records on this page. → see `Audience` under **Structures**.
- `next_cursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Audience`

Who a campaign goes to: a static list or a saved segment with an allowlisted filter.

- `id` (string) — Audience ID.
- `name` (string) — Audience name.
- `kind` (string) — How membership is decided.
- `filter` (object, may be null) — The saved filter, for `saved_segment`. Only allowlisted fields are accepted.
- `member_count` (int, may be null) — Contacts currently in the audience.
- `created_at` (string) — Creation time (UTC).

### `PageCamel<Template>`

The same listing with the cursor in camelCase. Older resources ship it this way and the name is kept because changing it would break clients already reading it.

- `items` (Template[]) — The records on this page. → see `Template` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Template`

An email template as a draft. Published versions are immutable and live in their own resource.

- `id` (string) — Template ID.
- `name` (string) — Template name.
- `message_type` (string) — What it may be used for.
- `subject` (string) — Subject line, with `{{variable}}` placeholders.
- `variables` (object[]) — Typed variables the template declares: name, type and whether it is required.
- `blocks` (object[]) — Canonical content blocks. Imported HTML is converted into these.
- `status` (string) — Draft state.
- `latest_version` (int, may be null) — Highest published version; null while never published.
- `updated_at` (string, may be null) — Last change (UTC).

### `TemplateVersion`

A published version. Immutable and identified by the hash of its content — republishing identical content does not create a new one.

- `version` (int) — Version number, increasing.
- `content_hash` (string) — Hash of the compiled content; it is the version's identity.
- `subject` (string) — Subject at this version.
- `published_at` (string) — Publication time (UTC).

### `Lista<TemplateVersion>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (TemplateVersion[]) — Every record in the collection. → see `TemplateVersion` under **Structures**.

### `TemplatePreview`

A draft compiled and rendered safely, without publishing anything.

- `subject` (string) — Subject with variables applied.
- `html` (string) — Rendered HTML.
- `text` (string) — Plain-text alternative.
- `warnings` (string[]) — What was stripped or would not render — active content, forms, unsafe URLs.

### `TemplateExport`

The latest published version in every form it exists.

- `template_id` (string) — ID of the exported template.
- `version` (int) — Exported version number.
- `subject` (string) — Subject at that version.
- `html` (string) — Compiled HTML.
- `text` (string) — Plain-text alternative.
- `mjml` (string) — MJML source of the compiled blocks.
- `content_hash` (string) — Hash identifying the version.

### `PageCamel<Campaign>`

The same listing with the cursor in camelCase. Older resources ship it this way and the name is kept because changing it would break clients already reading it.

- `items` (Campaign[]) — The records on this page. → see `Campaign` under **Structures**.
- `nextCursor` (string, may be null) — Cursor for the next page; null when there are no more.

### `Campaign`

A marketing send to an audience. Launching freezes the eligible recipients exactly once — the frozen set is what gets sent, no matter what changes afterwards.

- `id` (string) — Campaign ID.
- `name` (string) — Campaign name.
- `status` (string) — Where the campaign is.
- `domain_id` (string) — Domain it sends from.
- `audience_id` (string) — Audience it goes to.
- `template_id` (string) — Published marketing template used.
- `template_version` (int) — Frozen template version.
- `scheduled_for` (string, may be null) — When it is scheduled, in the organization's timezone.
- `frozen_recipients` (int, may be null) — How many recipients were frozen at launch.
- `created_at` (string) — Creation time (UTC).

### `CampaignReport`

Campaign reconciliation: what was delivered and what came back. Counts only — no recipient data.

- `campaign` (Campaign) — The campaign being reported on. → see `Campaign` under **Structures**.
- `deliveries` (object) — Delivery counts by state.
- `events` (object) — Normalized feedback counts by event type.

### `MessagingSettings`

Timezone and marketing pause state. A reputation or SES tenant risk pauses marketing automatically, and resuming requires a healthy observation first.

- `timezone` (string) — IANA timezone used to schedule campaigns, e.g. `America/Sao_Paulo`.
- `marketing_state` (string) — Whether marketing may go out.
- `paused_reason` (string, may be null) — Why marketing was paused, when it was.

### `Lista<Webhook>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (Webhook[]) — Every record in the collection. → see `Webhook` under **Structures**.

### `Webhook`

An HTTPS endpoint that receives delivery events. The signing secret is revealed once, at creation.

- `id` (string) — Webhook ID.
- `url` (string) — HTTPS destination.
- `event_types` (string[]) — Which events are delivered to it.
- `status` (string) — Whether it is receiving.
- `created_at` (string) — Creation time (UTC).
- `secret` (string, optional) — Signing secret for timestamped HMAC-SHA256. Present only on the response that created it.

### `BillingPublic`

The public billing view: catalog, x402 configuration and whether signup is invite-only.

- `catalog` (BillingCatalog) — Plans and prices in force. → see `BillingCatalog` under **Structures**.
- `payment` (PlanoX402) — x402 configuration: network, asset, facilitator and where to pay. → see `PlanoX402` under **Structures**.
- `invite_only` (bool) — Whether new organizations require an invitation.

### `BillingTenant`

What THIS organization is entitled to, and how close it is to running out.

- `catalog` (BillingCatalog) — Plans and prices in force. → see `BillingCatalog` under **Structures**.
- `state` (object) — Current entitlement: what is active, how many sends remain and when it expires.
- `warning` (object, may be null) — Expiration or exhaustion warning, when one applies.
- `payment` (PlanoX402) — x402 configuration for paying. → see `PlanoX402` under **Structures**.

### `Operations`

Operational alerts for the organization — DLQ, backlog, worker and SNS failures, reputation, paused sending, quota and SES/SNS cost capacity. Never contains recipient PII.

- `alerts` (object[]) — Current alerts, each with a kind, a severity and what to do.
- `billing` (object) — Quota position at the time of the observation.
- `capacity` (object) — Conservative SES and SNS capacity observations.

### `Lista<DataExport>`

A complete, unpaginated collection — used where the set is bounded by design.

- `items` (DataExport[]) — Every record in the collection. → see `DataExport` under **Structures**.

### `DataExport`

A tenant-scoped JSON export, retained for seven days.

- `id` (string) — Export ID.
- `status` (string) — Where the export stands.
- `expires_at` (string) — When the file is deleted (UTC).
- `created_at` (string) — Creation time (UTC).

### `Deletion`

A scheduled tenant erasure. It waits seven days, and what survives is pseudonymous financial and audit evidence only.

- `id` (string, may be null) — Deletion request ID.
- `status` (string) — Where the request stands.
- `scheduled_for` (string, may be null) — When erasure runs, after the grace period (UTC).
- `requested_by` (string, may be null) — Who scheduled it.

### `Metricas`

7-day operator dashboard. `payments` only appears with the token and only on Base mainnet.

- `app` (string) — Product name.
- `today` (string) — Reference day (UTC, YYYY-MM-DD).
- `today_visits` (int) — Interface visits counted today.
- `today_contacts` (int, optional) — Contact messages today. Only with `METRICS_TOKEN`: contact counts never leave without the token.
- `days` (object[]) — One row per day of the window, with each metric's count.
- `usage` (object) — `entregas`: deliveries per day — real product usage, not catalog load.
- `accounts` (object) — `organizacoes`: total organizations registered.
- `financeiro` (object, optional) — Day aggregate: `hoje_usd`, `hoje_count`, `rede`. Only with `METRICS_TOKEN`: money never leaves without the token; the full series is `payments`.
- `payments` (object, optional) — x402 financial summary; METRICS_TOKEN only.

### `BillingCatalog`

Plans and prices, versioned. Nothing here auto-renews — a pass or a top-up is bought once and runs out.

- `version` (string) — Catalog version, so a client can tell prices changed.
- `trial` (object) — What a new organization gets for free.
- `pass` (object) — The paid pass: what it grants and what it costs.
- `topup` (object) — One-off send top-up: size and price.
- `checkout_live` (bool) — Whether live checkout is enabled. While false, a purchase returns an x402 challenge.
- `global_recipient_hard_cap` (int) — Real recipients per month across the whole platform. This always prevails.
- `auto_renew` (bool) — Always false — nothing here renews by itself.

### `PlanoX402`

x402 payment configuration in force. Comes from `planPublic` and is the same across the products.

- `provider` (string) — Always `x402` — the only billing protocol accepted.
- `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid.
- `network` (string) — USDC network: `base` in production, `base-sepolia` in staging.
- `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain.
- `pay_to` (string, may be null) — Address that receives the payment.
- `homolog` (bool) — Staging seam on: the loop can be closed without spending USDC.
- `dev` (bool) — Development mode: the 402 is simulated.
- `dev_gate` (string, may be null) — How dev mode is unlocked, when it exists.
- `facilitator` (string) — URL of the facilitator that verifies and settles the payment.
- `asset` (string) — Accepted currency — always `USDC`.
- `asset_address` (string) — USDC contract on the network above.
- `faucet` (string, may be null) — Test-USDC faucet; only on base-sepolia.
- `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app).