---
title: "API reference"
description: "The Solacia REST API: read leads, demos, transcripts, questions and knowledge gaps, make personal demo links, and run agents, the team and API keys. Every endpoint, record, error and MCP tool, version 1."
---

# The Solacia API

What Solacia's demo agents produced for one account: leads, demos, transcripts, questions, gaps and analytics. Send an API key as `Authorization: Bearer <key>`; a key reads one account. Every error is application/problem+json. Fields are only ever added under /v1; a record's `schema` names its shape.

- Base URL: `https://app.solacia.ai/v1`
- Version: 1 (OpenAPI 3.1.0: /docs/openapi.v1.json)
- Auth: `Authorization: Bearer <key>`; an owner makes keys in the console (Team, API keys)
- Scopes: `agents:admin`, `agents:read`, `demos:read`, `foundation:read`, `foundation:write`, `gaps:write`, `integrations:admin`, `integrations:read`, `keys:admin`, `leads:read`, `leads:write`, `links:write`, `mail:events`, `team:admin`
- MCP: `https://app.solacia.ai/mcp`, with the same key, or by signing in from Claude, ChatGPT or any MCP client
- Status: https://status.solacia.ai

## Make your first call

```sh
curl https://app.solacia.ai/v1/account/me \
  -H "Authorization: Bearer $SOLACIA_API_KEY"

curl "https://app.solacia.ai/v1/leads?priority=hot&limit=20" \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Keys and scopes

- Made in the console: An owner makes a key on the console's Team page, with the scopes it needs. It is shown once; Solacia keeps only its hash.
- It says where it works: `sol_live_halden_…` works on production, `sol_dev_halden_…` on dev, for the account it names. Its last six characters check the rest, so a mistyped key is refused at once. Secret scanners know the `sol_` prefix.
- Every key ends: In 7, 30 or 90 days (90 unless you pick another), or never. Every response to a key says when in `Solacia-Key-Expires`; `GET /v1/api-keys/self` says the rest.
- Roll it without downtime: A roll makes a new key with the same name and scopes, and keeps the old one working now, for 1 hour, 24 hours or 7 days, while you switch.
- Revoke it at once: On the Team page, or with `DELETE /v1/api-keys/{id}`. Its next call gets a 401 with `key_revoked`, and what it did stays on record.
- See what it did: Every call a key makes is recorded with its status, time and request id, refused ones too. `GET /v1/api-keys/self/usage` reads the last 30 days, with the demo links it made and the demos they brought.

## How the API behaves

- Records name their shape: Every record carries `schema`, such as `solacia.lead.v1`. Under one name, fields are only ever added: never removed, renamed or made required. `solacia.analytics.v0` may still change.
- One lead record: <a href="#record-lead">`Lead`</a> is the same record your CRM webhook and HubSpot receive. What the API returns is what your team sees.
- Lists page by cursor: Every list pages the same way: pass `limit` and the previous page's `next_cursor` as `cursor`. A page with `next_cursor: null` is the last, and `total` says how many matched over every page. A record that arrives while you page is never repeated or skipped. Leads, demos and questions send 50 rows unless asked (up to 200); buyers, demo links, unanswered questions and team requests send every row unless asked (up to 500).
- Test demos stay out: Demos marked as tests are left out of every list unless you pass `tests=true`.
- A budget per key: 120 units a minute and 5,000 a day. A read costs one unit, `/analytics` two, `fresh=true` one more, and a page one more per 50 records past the first 50. `RateLimit-Remaining` and `RateLimit-Reset` are on every response; past the budget you get a 429 with `Retry-After`.
- Every response has an id: `X-Request-Id` is yours if you sent one (up to 64 plain characters), or ours. Errors repeat it. Quote it when you ask us about a request.

## Errors

Every error is `application/problem+json` with a stable `code`:

- `unauthorized` (401): No key, a mistyped one, or a key this host does not know.
- `key_expired` (401): The key passed its end. Make a new one or roll it before it ends.
- `key_revoked` (401): The key was revoked, or replaced by a roll and its overlap is over.
- `wrong_environment` (401): A `sol_dev_` key on production, or a `sol_live_` key on dev.
- `wrong_account` (403): A key of another account.
- `forbidden` (403): The key lacks the scope, or the user the role, the operation needs.
- `not_found` (404): No record with that id in this account.
- `key_ended` (409): The key already stopped working; there is nothing to change.
- `invalid` (422): A parameter or body field is not right; `detail` says which.
- `wider_scopes` (422): An edit asked for a scope the key does not have. Keys are narrowed, never widened.
- `bad_cursor` (400): A `cursor` that did not come from this API.
- `bad_include` (400): An `include` value the operation does not offer.
- `rate_limited` (429): The key has used its budget for the minute or the day; `Retry-After` says when.

## Account

Who a key belongs to and what it may do. The first call to make with a new key.

### GET /v1/account/me

Who this key or session is, and what it may do.

Console role `member`.

Returns: [Me](#record-me).

```sh
curl https://app.solacia.ai/v1/account/me \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Leads

One record per buyer: who they are, what they asked, saw and objected to, and the next step. The same `solacia.lead.v1` record your CRM receives.

### GET /v1/leads

Every buyer as a lead record, hottest first.

Scope `leads:read`. Console role `member`.

Parameters:

- `q` (string, query): Words to find in what the buyer asked, their email, company or fit. Up to 200 characters.
- `since` (string, query): Only demos active at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Up to 40 characters.
- `priority` ("hot" | "warm" | "nurture" | "cold" | null, query)
- `campaign` (string | null, query): Only buyers who came in by a demo link of this campaign; an empty value, buyers with none.
- `tests` (boolean, query): Include test demos. Default `false`.
- `fresh` (boolean, query): Read the record again instead of the last few seconds' copy. Costs one more unit. Default `false`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `limit` (integer, query): Records per page; 50 per unit. 1 to 200. Default `50`.

Returns: [LeadPage](#record-leadpage).

```sh
curl "https://app.solacia.ai/v1/leads?priority=hot&limit=20" \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/leads/{id}

One buyer's lead record, with the transcript, calls and CRM deals on request.

Scope `leads:read`. Console role `member`. MCP tool `get_buyer`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `include` (string, query): Comma-separated: transcript, calls, deals. Up to 40 characters.

Returns: [Lead](#record-lead).

```sh
curl "https://app.solacia.ai/v1/leads/web-7f3a9c?include=transcript,calls" \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Demos

Every run of the demo, the buyers in them, and the conversation in each.

### GET /v1/buyers

The Buyers list: one row per buyer that reads as a short brief, newest first. In preview.

Scope `demos:read`. Console role `member`. MCP tool `find_buyers`.

Parameters:

- `days` (integer, query): Demos that began in the last `days` days, today included. 1 to 365. Default `90`.
- `tests` (boolean, query): Default `false`.
- `q` (string, query): Only the buyers whose name, address, company, role, or anything they said or told the demo (calls included) holds every word of it; case and accents don't matter. Up to 120 characters.
- `order` ("newest" | "promising", query): newest: by their latest demo. promising: meetings first, then qualified, nurture and no email, each by score. Default `"newest"`.
- `limit` (integer, query): At most this many buyers; 0 for all of them. 0 to 500. Default `0`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `language` ("en" | "es" | "pt", query): The language the rows' roles and facts are written in: English, Spanish or Portuguese. Default `"en"`.

Returns: [Buyers](#record-buyers).

```sh
curl https://app.solacia.ai/v1/buyers \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/buyers/{id}/done

Mark the one thing to do for a buyer done, or take the mark back. In preview.

Scope `leads:write`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([BuyerDoneIn](#record-buyerdonein)):

- `action` ("book" | "prep" | "follow_up", required): The action they did, as the row gave it.
- `done` (boolean): False takes the mark back (Undo). Default `true`.

Returns: [BuyerDone](#record-buyerdone).

```sh
curl -X PUT https://app.solacia.ai/v1/buyers/{id}/done \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos

Every run of the demo, newest first.

Scope `demos:read`. Console role `member`.

Parameters:

- `since` (string, query): Only demos active at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Up to 40 characters.
- `tests` (boolean, query): Default `false`.
- `fresh` (boolean, query): Default `false`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `limit` (integer, query): 1 to 200. Default `50`.

Returns: [DemoPage](#record-demopage).

```sh
curl "https://app.solacia.ai/v1/demos?since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos/{id}

One run of the demo.

Scope `demos:read`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [Demo](#record-demo).

```sh
curl https://app.solacia.ai/v1/demos/web-7f3a9c \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/demos/{id}/brief-link

A new link to the demo's brief, for 30 days, to send a rep by hand: it opens to a work email at the account proven by a code; Handoff ends it. In preview.

Scope `leads:write`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [BriefLinkMade](#record-brieflinkmade).

```sh
curl -X POST https://app.solacia.ai/v1/demos/{id}/brief-link \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/demos/{id}/follow-up

Keep the demo's follow-up email as a teammate edited it. In preview.

Scope `leads:write`. Console role `member`. MCP tool `edit_follow_up`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([FollowUpIn](#record-followupin)):

- `body` (string, required): Up to 10000 characters.
- `subject` (string, required): Up to 300 characters.

Returns: [FollowUpDraft](#record-followupdraft).

```sh
curl -X PUT https://app.solacia.ai/v1/demos/{id}/follow-up \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos/{id}/recordings

The demo's calls as recorded, each with a link that plays it for an hour. In preview.

Scope `leads:read`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [Recordings](#record-recordings).

```sh
curl https://app.solacia.ai/v1/demos/{id}/recordings \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/demos/{id}/recordings/{n}

Delete one of the demo's recordings now, before its 90 days are up. In preview.

Scope `leads:write`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `n` (string, path, required): Up to 200 characters.

Returns: [Deleted](#record-deleted).

```sh
curl -X DELETE https://app.solacia.ai/v1/demos/{id}/recordings/{n} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos/{id}/recordings/{n}/chapters

A recorded call's parts, each named in a few words, in order. In preview.

Scope `leads:read`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `n` (string, path, required): Up to 200 characters.
- `language` ("en" | "es" | "pt", query): The language events and notes are written in: English, Spanish or Portuguese. Default `"en"`.

Returns: [Chapters](#record-chapters).

```sh
curl https://app.solacia.ai/v1/demos/{id}/recordings/{n}/chapters \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos/{id}/standing

Where one demo stands: its outcome, the meeting time picked, its agent and door. In preview.

Scope `demos:read`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [Standing](#record-standing).

```sh
curl https://app.solacia.ai/v1/demos/{id}/standing \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demos/{id}/transcript

The conversation of one demo: what the buyer wrote or said, what the guide answered and showed.

Scope `leads:read`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `language` ("en" | "es" | "pt", query): The language events and notes are written in: English, Spanish or Portuguese. Default `"en"`.

Returns: [Transcript](#record-transcript).

```sh
curl https://app.solacia.ai/v1/demos/web-7f3a9c/transcript \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Questions

Everything buyers asked, and how well it was answered.

### GET /v1/questions

Every question buyers asked, newest first, with how well it was answered.

Scope `demos:read`. Console role `member`. MCP tool `list_questions`.

Parameters:

- `q` (string, query): Up to 200 characters.
- `since` (string, query): Only demos active at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Up to 40 characters.
- `answered` (boolean | null, query): true: answered from a source or in the call; false: not.
- `tests` (boolean, query): Default `false`.
- `fresh` (boolean, query): Default `false`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `limit` (integer, query): 1 to 200. Default `50`.

Returns: [QuestionPage](#record-questionpage).

```sh
curl https://app.solacia.ai/v1/questions \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Knowledge gaps

What the agent could not answer from your sources, most asked first. Close a gap by adding the answer to your docs.

### POST /v1/dictation

Write down a recorded answer: the recording in, the words out. In preview.

Scope `gaps:write`. Console role `member`.

Body ([DictationIn](#record-dictationin)):

- `audio` (string, required): The recording, base64, up to 3 MB Up to 4200000 characters.
- `type` (string): Up to 100 characters. Default `"audio/webm"`.

Returns: [Dictation](#record-dictation).

```sh
curl -X POST https://app.solacia.ai/v1/dictation \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/gaps

What the agent could not answer from the vendor's sources, most asked first.

Scope `demos:read`. Console role `member`. MCP tool `list_unanswered_questions`.

Parameters:

- `status` ("open" | "closed" | "dismissed" | "all", query): Default `"open"`.
- `fresh` (boolean, query): Default `false`.
- `language` ("en" | "es" | "pt", query): The language who asked is described in: English, Spanish or Portuguese. Default `"en"`.
- `limit` (integer, query): At most this many questions; 0 for all of them. 0 to 500. Default `0`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [GapList](#record-gaplist).

```sh
curl https://app.solacia.ai/v1/gaps \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/gaps/answer

Answer a gap, or give it a new answer: the agent gives it to every buyer who asks after, in any wording.

Scope `gaps:write`. Console role `member`. MCP tool `answer_question`.

Body ([GapAnswerIn](#record-gapanswerin)):

- `answer` (string, required): What buyers should be told, as the team would say it: facts only, no quotes. Up to 2000 characters.
- `key` (string, required): The gap's key Up to 2000 characters.

Returns: [Gap](#record-gap).

```sh
curl -X POST https://app.solacia.ai/v1/gaps/answer \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/gaps/calls

Check a gap against the sales calls read from Granola: whether a rep answered it, and the answer drafted from the rep's when one did. In preview.

Scope `gaps:write`. Console role `member`.

Body ([GapCallsIn](#record-gapcallsin)):

- `key` (string, required): The gap's key Up to 2000 characters.
- `question` (string): The question as asked; left out: the gap's Up to 2000 characters.

Returns: [GapDocument](#record-gapdocument).

```sh
curl -X POST https://app.solacia.ai/v1/gaps/calls \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/gaps/dismiss

Dismiss a gap, or restore it with dismissed=false: it leaves the open list and count, and the guide's answers stay as they are. In preview.

Scope `gaps:write`. Console role `member`. MCP tool `dismiss_question`.

Body ([GapDismissIn](#record-gapdismissin)):

- `dismissed` (boolean): false restores it to the open list Default `true`.
- `key` (string, required): The gap's key Up to 2000 characters.
- `reason` ("unpublished" | null): unpublished: the vendor deliberately doesn't publish this (a margin, a custom price), so the agent keeps handing it to the team (ADR 0009)

Returns: [Gap](#record-gap).

```sh
curl -X POST https://app.solacia.ai/v1/gaps/dismiss \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/gaps/documents

Attach a document to a gap: kept with the vendor's docs, checked against the question, and the answer drafted from it when it answers. In preview.

Scope `gaps:write`. Console role `member`.

Body ([GapDocumentIn](#record-gapdocumentin)):

- `content` (string): The file, base64: .pdf, .docx, .html, .md or .txt, up to 3 MB Up to 4200000 characters.
- `key` (string, required): The gap's key Up to 2000 characters.
- `name` (string, required): Up to 200 characters.
- `question` (string): The question as asked; left out: the gap's Up to 2000 characters.
- `text` (string): Or its text, instead of the file Up to 1000000 characters.

Returns: [GapDocument](#record-gapdocument).

```sh
curl -X POST https://app.solacia.ai/v1/gaps/documents \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Analytics

What the demos add up to over a period.

### GET /v1/analytics

What the demos add up to over a period: KPIs, funnel, topics, sessions.

Scope `demos:read`. Console role `member`. MCP tool `get_numbers`.

Parameters:

- `days` (integer, query): 1 to 365. Default `30`.
- `tests` (boolean, query): Default `false`.
- `fresh` (boolean, query): Default `false`.
- `demos` (boolean, query): false leaves out each demo's row and the demos behind each question: the numbers alone. Default `true`.

Returns: [Analytics](#record-analytics).

```sh
curl "https://app.solacia.ai/v1/analytics?days=30" \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/analytics/flow

Where every buyer went, from opening the demo to where they are now, counted by way.

Scope `demos:read`. Console role `member`.

Parameters:

- `days` (integer, query): The last `days` days, today included; `start` overrides it. 1 to 365. Default `30`.
- `start` (string (date) | null, query): A range of your own: its first day (UTC). Ends today unless `end` says.
- `end` (string (date) | null, query): The range's last day, included (UTC); with `start` only.
- `tests` (boolean, query): Default `false`.
- `agent` (string[], query): Only the demos these agents ran; repeat for several. All when none.
- `door` (string[], query): Only the demos opened through these doors; repeat for several: "outbound" (a personal link), "site:<host>" (the embed on that website), "site" (the embed, page not known), "link" (the demo's own address), or "unknown". All when none.

Returns: [Flow](#record-flow).

```sh
curl https://app.solacia.ai/v1/analytics/flow \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Demo links

A personal demo link per prospect, for your outbound email. The agent reads who they are before the call.

### GET /v1/clay

Whether Clay can make this account's links, where its column sends them, and what it has made.

Scope `integrations:admin`. Console role `owner`.

Returns: [ClayStatus](#record-claystatus).

```sh
curl https://app.solacia.ai/v1/clay \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/clay/key

Stop the Clay key working at once.

Scope `integrations:admin`. Console role `owner`.

Returns: [ClayStatus](#record-claystatus).

```sh
curl -X DELETE https://app.solacia.ai/v1/clay/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/clay/key

A key for a Clay HTTP column that can only make demo links, shown once; the one before it stops working.

Scope `integrations:admin`. Console role `owner`.

Returns: [ClayKeyMade](#record-claykeymade).

```sh
curl -X POST https://app.solacia.ai/v1/clay/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/crm/lists

The lists in the account's CRM that personal demo links can be made for: HubSpot's contact lists, Salesforce's campaigns.

Scope `links:write`. Console role `member`. MCP tool `list_crm_lists`.

Parameters:

- `q` (string, query): Words in the list's name. Up to 80 characters.

Returns: [CrmLists](#record-crmlists).

```sh
curl https://app.solacia.ai/v1/crm/lists \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demo-links

The personal demo links made so far, newest first, one per prospect, with what each brought and a result per campaign.

Scope `links:write`. Console role `member`. MCP tool `list_demo_links`.

Parameters:

- `campaign` (string | null, query): Only this campaign's links; an empty value, those without one.
- `limit` (integer, query): At most this many links, newest first; 0 for all of them. 0 to 500. Default `0`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [DemoLinks](#record-demolinks).

```sh
curl https://app.solacia.ai/v1/demo-links \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/demo-links

Make a personal demo link for one prospect, with who they are for the guide.

Scope `links:write`. Console role `member`.

Body ([DemoLinkIn](#record-demolinkin)):

- `agent` (string | null): The agent the prospect meets: its id. Left out: the sender's default agent, else the outbound channel's.
- `anonymous` (boolean): A link for someone unnamed: its demos are filed under an address made up for it, and a buyer who asks for your team gives their own email. Default `false`.
- `campaign` (string): The list, segment or sequence the link goes out in, such as CFOs Mexico Q4. Your team's label: the agent never sees it; the lead record carries it. Up to 80 characters.
- `company` (string): Up to 80 characters.
- `days` (integer): How long the link opens the demo. 1 to 90. Default `30`.
- `email` (string): The prospect's work email; none for an anonymous link. Up to 254 characters.
- `name` (string): Their name, to greet them by. Up to 80 characters.
- `notes` (string): What the rep knows that should shape the demo. The agent checks it with the buyer before relying on it and never quotes it. Up to 600 characters.
- `role` (string): Their job, such as CFO. Up to 80 characters.
- `sent_to` (string): Who you sent the link to: a company, a person or both. Your team's label: the agent never sees it. Up to 80 characters.
- `try_out` (boolean): A try link, Solacia's team only: one we keep to try the demo ourselves, never sent to a buyer. Its demos never post to Slack or reach the CRM. Anyone else is refused. Default `false`.

Returns: [DemoLink](#record-demolink).

```sh
curl -X POST https://app.solacia.ai/v1/demo-links \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maya.chen@arbor.example",
    "name": "Maya Chen",
    "role": "VP Finance",
    "company": "Arbor",
    "campaign": "Finance leaders Q4",
    "notes": "Asked about forecasting by region on LinkedIn."
  }'
```

### POST /v1/demo-links/batch

Make personal demo links for a list of prospects in one request, up to 500 at a time; rows that are not a work email come back refused, with why.

Scope `links:write`. Console role `member`. MCP tool `make_demo_links`.

Body ([DemoLinksIn](#record-demolinksin)):

- `rows` ([DemoLinkIn](#record-demolinkin)[], required): Up to 500 prospects.

Returns: [DemoLinksMade](#record-demolinksmade).

```sh
curl -X POST https://app.solacia.ai/v1/demo-links/batch \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/demo-links/from-crm-list

Make personal demo links for one page of a CRM list's people and write each onto their record (HubSpot's Solacia demo link property, Salesforce's Solacia Demo Link field); call again with `next` until it is empty.

Scope `links:write`. Console role `member`. MCP tool `make_crm_list_links`.

Body ([CrmListLinksIn](#record-crmlistlinksin)):

- `after` (string): Where this page starts: the last answer's `next`. Up to 256 characters.
- `agent` (string | null): The agent they meet; left out: the sender's default.
- `campaign` (string): Up to 80 characters.
- `days` (integer): How long the links open the demo. 1 to 90. Default `30`.
- `list_id` (string, required): Up to 64 characters.

Returns: [CrmListLinks](#record-crmlistlinks).

```sh
curl -X POST https://app.solacia.ai/v1/demo-links/from-crm-list \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/demo-links/try-out

Solacia's team only: mark a link already made as a try link, kept to try the demo, whose demos never post to Slack or reach the CRM; or as one sent to a buyer again.

Scope `links:write`. Console role `member`.

Body ([TryLinkIn](#record-trylinkin)):

- `email` (string, required): The email the link was made for, as the list of links gives it. Up to 254 characters.
- `try_out` (boolean): True: a try link, whose demos never post to Slack or reach your CRM. False: a link sent to a buyer. Default `true`.

Returns: [TryLinkMarked](#record-trylinkmarked).

```sh
curl -X POST https://app.solacia.ai/v1/demo-links/try-out \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Agents

Your demo agents: what each says and shows, where it runs, and its test calls.

### PUT /v1/agent-default

Set the agent your personal links carry unless you pick another. In preview.

Scope `agents:admin`. Console role `member`.

Body ([AgentDefaultIn](#record-agentdefaultin)):

- `agent` (string | null): Null: the outbound channel's

Returns: [Agents](#record-agents).

```sh
curl -X PUT https://app.solacia.ai/v1/agent-default \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/agent-routes/{channel}

Give a channel's demos to an agent, from the next demo that starts. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `channel` (string, path, required): Up to 200 characters.

Body ([AgentRouteIn](#record-agentroutein)):

- `agent` (string, required): The id of the agent to run the channel's demos Up to 80 characters.

Returns: [Agents](#record-agents).

```sh
curl -X PUT https://app.solacia.ai/v1/agent-routes/{channel} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/agent-rules

Set the website's rules: which agent a buyer meets by where they came from, then by the page the demo opened on. In preview.

Scope `agents:admin`. Console role `owner`.

Body ([AgentRulesIn](#record-agentrulesin)):

- `rules` ([AgentRule](#record-agentrule)[], required)

Returns: [Agents](#record-agents).

```sh
curl -X PUT https://app.solacia.ai/v1/agent-rules \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agent-tests

Split one channel's buyers between two or three agents, each buyer always on the same side. In preview.

Scope `agents:admin`. Console role `owner`.

Body ([AgentTestIn](#record-agenttestin)):

- `arms` ([TestArmIn](#record-testarmin)[], required)
- `channel` ("embed" | "outbound" | "link", required)
- `min_buyers` (integer): Buyers each side needs before any verdict 20 to 100000. Default `20`.
- `question` (string): Up to 200 characters.
- `weeks` (integer | null): How long it takes buyers; left out: until stopped

Returns: [Agents](#record-agents).

```sh
curl -X POST https://app.solacia.ai/v1/agent-tests \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agent-tests/{id}/check-crm

Read from your CRM which prospects of an outreach test against no demo have had a meeting booked since their link was made, on both sides. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([Nothing](#record-nothing)):

None.

Returns: [AgentTestCrmCheck](#record-agenttestcrmcheck).

```sh
curl -X POST https://app.solacia.ai/v1/agent-tests/{id}/check-crm \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agent-tests/{id}/stop

Stop a test; with `keep`, that agent runs the channel from the next demo. In preview.

Scope `agents:admin`. Console role `owner`. MCP tool `stop_agent_test`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentTestStopIn](#record-agentteststopin)):

- `keep` (string | null): The agent to run the channel from now on; in a test between an agent's versions, the side (A, B or C) whose version goes live

Returns: [Agents](#record-agents).

```sh
curl -X POST https://app.solacia.ai/v1/agent-tests/{id}/stop \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents

The account's agents, what each runs and costs, and the agent of each channel. In preview.

Scope `agents:read`. Console role `member`. MCP tool `list_agents`.

Returns: [Agents](#record-agents).

```sh
curl https://app.solacia.ai/v1/agents \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents

Make an agent: the pack run another way, with its own name and face or none. In preview.

Scope `agents:admin`. Console role `owner`.

Body ([AgentIn](#record-agentin)):

- `copy_of` (string | null): Start from this agent's tone, instructions, facts and voices
- `name` (string, required): Up to 200 characters.
- `price` (integer | null): US cents a demo; Solacia only. Left out: the list price
- `renderer` ("voice" | "face"): Default `"voice"`.

Returns: [Agents](#record-agents).

```sh
curl -X POST https://app.solacia.ai/v1/agents \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents/{id}

One agent: its live version, its draft, every version and the script a buyer meets. In preview.

Scope `agents:read`. Console role `member`. MCP tool `get_agent`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [AgentDetail](#record-agentdetail).

```sh
curl https://app.solacia.ai/v1/agents/{id} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/agents/{id}

Rename an agent, change its face, how it talks, its voice, its price (Solacia only), or retire it. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentChangeIn](#record-agentchangein)):

- `facts` ([AgentFact](#record-agentfact)[] | null): Replaces all its facts
- `instructions` (string | null)
- `list_price` (boolean): Back to the list price for its renderer; Solacia only Default `false`.
- `name` (string | null)
- `price` (integer | null): US cents a demo; Solacia only
- `renderer` ("voice" | "face" | null)
- `retired` (boolean | null): true pauses it everywhere: its website rules and links send buyers to the next rule or the default until false resumes it. Refused while it holds a default or is in a test
- `tone` ("brief" | "warm" | "expert" | "pack" | null): pack: as the brief says
- `voices` (object<string, string> | null): Voice id per language; Solacia only. Empty: the product's

Returns: [Agents](#record-agents).

```sh
curl -X PUT https://app.solacia.ai/v1/agents/{id} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/changes

Turn the agent's open notes into changes to its next version: each with what it replaces, why, and whether its words meet the demo-lines standard. Drafted by a model; nothing changes until kept. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentChangesIn](#record-agentchangesin)):

- `notes` (string[] | null): The notes to read; all the open ones when left out

Returns: [AgentChanges](#record-agentchanges).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/changes \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/changes/apply

Put the kept changes into the agent's draft and close their notes, and the ones dropped. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentChangesApplyIn](#record-agentchangesapplyin)):

- `dropped` (string[]): Notes closed with no change
- `kept` ([AgentChangeKept](#record-agentchangekept)[]): Into the draft

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/changes/apply \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/agents/{id}/draft

Throw the agent's draft away. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X DELETE https://app.solacia.ai/v1/agents/{id}/draft \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/agents/{id}/draft

Change the agent's draft: how it talks, who it's for, its goal and its script. Buyers never meet a draft. In preview.

Scope `agents:admin`. Console role `owner`. MCP tool `change_agent`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentDraftIn](#record-agentdraftin)):

- `audience` (string | null)
- `counts` ("qualified" | "meeting" | null): What reaching the goal is: the buyer qualifies, or asks to meet the team
- `facts` ([AgentFact](#record-agentfact)[] | null): Replaces all its facts
- `goal` (string | null)
- `instructions` (string | null)
- `script` ([AgentScriptIn](#record-agentscriptin) | null)
- `tone` ("brief" | "warm" | "expert" | "pack" | null): pack: as the brief says
- `voices` (object<string, string> | null): Voice id per language; Solacia only

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X PUT https://app.solacia.ai/v1/agents/{id}/draft \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/draft/publish

Make the draft the agent's next version, from the next demo that starts; refused while its own lines miss the demo-lines standard. In preview.

Scope `agents:admin`. Console role `owner`. MCP tool `publish_agent`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/draft/publish \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents/{id}/levers

What a test on the agent can learn, one lever at a time (its message, the features it shows first, its pricing, its offer, its qualification): each with the goal its test is read on, the parts of a version it changes, and what the agent's buyers of the last 30 days did that it starts from. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [AgentLevers](#record-agentlevers).

```sh
curl https://app.solacia.ai/v1/agents/{id}/levers \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/notes

Leave a note on one turn of a rehearsal, for the agent's next version. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentNoteIn](#record-agentnotein)):

- `session` (string, required): Up to 80 characters.
- `text` (string, required): Up to 1000 characters.
- `turn` (integer, required)

Returns: [AgentRehearsal](#record-agentrehearsal).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/notes \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/agents/{id}/notes/{note}

Take a note back. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `note` (string, path, required): Up to 200 characters.

Returns: [AgentNotes](#record-agentnotes).

```sh
curl -X DELETE https://app.solacia.ai/v1/agents/{id}/notes/{note} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/rehearsals

Rehearse the agent: a demo of its draft as it is now, or of one of its versions, for the team to run as a buyer would. Never counted in results, and nothing in it reaches the team, the CRM or the calendar. Open `url` to run it. In preview.

Scope `agents:admin`. Console role `member`. MCP tool `rehearse_agent`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentRehearseIn](#record-agentrehearsein)):

- `of` (integer | "draft"): A version's number, or the draft as it is now Default `"draft"`.

Returns: [AgentRehearsal](#record-agentrehearsal).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/rehearsals \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents/{id}/rehearsals/{session}

A rehearsal read back: each turn tagged script (said as written), answer (the agent's own words, with what the docs made of them), screen or buyer, with the notes on it. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `session` (string, path, required): Up to 200 characters.

Returns: [AgentRehearsal](#record-agentrehearsal).

```sh
curl https://app.solacia.ai/v1/agents/{id}/rehearsals/{session} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents/{id}/suggestions

Tests worth running on the agent, read from what its buyers did in the last 30 days: the part most of the ones who left without its goal left on, or its opening when many leave in the first minute. At most 3, the strongest first. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [AgentSuggestions](#record-agentsuggestions).

```sh
curl https://app.solacia.ai/v1/agents/{id}/suggestions \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/suggestions/{sid}/draft

Have a model draft a suggestion's change into the agent's draft, from the buyers behind it, checked as any draft: read it, then test it against the live version. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `sid` (string, path, required): Up to 200 characters.

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/suggestions/{sid}/draft \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/agents/{id}/test-plan

Before testing an agent's versions: its pace, and how soon a test would make a better draft live, or how often a worse one, under each rule. `share`: percent on the challenger. In preview.

Scope `agents:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `share` (integer, query): Percent of buyers on the challenger 10 to 90. Default `50`.
- `lever` ("message" | "features" | "pricing" | "offer" | "qualification" | null, query): What it would learn: it is read on that lever's goal, else the agent's own

Returns: [AgentTestPlan](#record-agenttestplan).

```sh
curl https://app.solacia.ai/v1/agents/{id}/test-plan \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/tests

Test an agent's versions against each other, or its draft against its live version, across every place it runs; each buyer always on the same side, read on who qualified. In preview.

Scope `agents:admin`. Console role `owner`. MCP tool `test_agent`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([AgentVersionTestIn](#record-agentversiontestin)):

- `lever` ("message" | "features" | "pricing" | "offer" | "qualification" | null): What it is to learn (GET /agents/{id}/levers): it is read on that lever's goal
- `min_buyers` (integer): Buyers each side needs before any verdict 20 to 100000. Default `20`.
- `question` (string): Up to 200 characters.
- `rule` ("unless_worse" | "proven"): unless_worse: a challenger may go live unless it is worse; proven: only once it is proven better Default `"unless_worse"`.
- `sides` ([VersionSideIn](#record-versionsidein)[], required)
- `weeks` (integer | null): How long it takes buyers; left out: until stopped

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/tests \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/agents/{id}/versions/{number}/publish

Put an earlier version back as the agent's next version: the rollback. In preview.

Scope `agents:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.
- `number` (string, path, required): Up to 200 characters.

Returns: [AgentDetail](#record-agentdetail).

```sh
curl -X POST https://app.solacia.ai/v1/agents/{id}/versions/{number}/publish \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/voice-samples

Hear a voice an agent can have: it says the start of the account's opening in that language. In preview.

Scope `agents:admin`. Console role `owner`.

Body ([VoiceSampleIn](#record-voicesamplein)):

- `agent` (string | null): Say this agent's own opening, when it has one
- `language` (string, required): Up to 8 characters.
- `voice` (string, required): An id from the agents' voice_pool Up to 100 characters.

Returns: [VoiceSample](#record-voicesample).

```sh
curl -X POST https://app.solacia.ai/v1/voice-samples \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Knowledge

The sources an agent answers from, and the claims read from them.

### GET /v1/docs-versions

Which version of the vendor's docs the agent answers from, and the latest ones kept.

Scope `foundation:read`. Console role `member`.

Returns: [DocsVersions](#record-docsversions).

```sh
curl https://app.solacia.ai/v1/docs-versions \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/docs-versions/live

Answer from a kept docs version: go back to an earlier one, or forward again. Calls pick it up within a minute.

Scope `foundation:write`. Console role `owner`.

Body ([DocsLiveIn](#record-docslivein)):

- `version` (string, required): The id of a kept version. Up to 64 characters.
- `why` (string): Why: shown with the version. Up to 300 characters.

Returns: [DocsVersions](#record-docsversions).

```sh
curl -X PUT https://app.solacia.ai/v1/docs-versions/live \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/foundation

What the account's customers say, quote by quote, graded by who said it, and what nobody has said yet. In preview.

Scope `foundation:read`. Console role `member`.

Returns: [Foundation](#record-foundation).

```sh
curl https://app.solacia.ai/v1/foundation \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/foundation/claims/{id}

Reword a claim, fold it into another of its kind, or drop it. In preview.

Scope `foundation:write`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([FoundationClaimIn](#record-foundationclaimin)):

- `gone` (boolean): Drop it Default `false`.
- `into` (string | null): Fold it into this claim: its quotes count there
- `text` (string | null): Its new wording

Returns: [Foundation](#record-foundation).

```sh
curl -X PUT https://app.solacia.ai/v1/foundation/claims/{id} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/foundation/quotes/{id}/remove

Take one quote off its claim. In preview.

Scope `foundation:write`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [Foundation](#record-foundation).

```sh
curl -X POST https://app.solacia.ai/v1/foundation/quotes/{id}/remove \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/foundation/sources

Add raw evidence (a call, an interview, a note, a ticket, a review, usage, a page); its first part is read at once. In preview.

Scope `foundation:write`. Console role `member`.

Body ([FoundationSourceIn](#record-foundationsourcein)):

- `customer` (string): Whose words: the company Up to 80 characters.
- `date` (string): YYYY-MM-DD Up to 10 characters.
- `kind` ("won_call" | "lost_call" | "interview" | "crm_note" | "ticket" | "review" | "usage" | "case_study" | "vendor_page" | "our_note", required)
- `public` (boolean | null): May be quoted to buyers; left out: by its kind
- `role` (string): Who spoke Up to 80 characters.
- `text` (string, required): Up to 200000 characters.
- `title` (string): Up to 120 characters.

Returns: [FoundationAdded](#record-foundationadded).

```sh
curl -X POST https://app.solacia.ai/v1/foundation/sources \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/foundation/sources/{id}/read

Read one more part of a source (its `left`), keeping only quotes that are its own words. In preview.

Scope `foundation:write`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([FoundationReadIn](#record-foundationreadin)):

- `part` (integer, required): 0 to 100.

Returns: [FoundationAdded](#record-foundationadded).

```sh
curl -X POST https://app.solacia.ai/v1/foundation/sources/{id}/read \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/foundation/sources/{id}/remove

Take a source out, with every quote cut from it. In preview.

Scope `foundation:write`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [Foundation](#record-foundation).

```sh
curl -X POST https://app.solacia.ai/v1/foundation/sources/{id}/remove \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Demo page

How the demo looks to buyers.

### DELETE /v1/demo/theme

Put the demo back in the product's own colours.

Scope `agents:admin`. Console role `owner`.

Returns: [DemoTheme](#record-demotheme).

```sh
curl -X DELETE https://app.solacia.ai/v1/demo/theme \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/demo/theme

The demo's colours, and the product's own.

Scope `agents:admin`. Console role `owner`.

Returns: [DemoTheme](#record-demotheme).

```sh
curl https://app.solacia.ai/v1/demo/theme \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/demo/theme

Recolour the demo (the call around the product and the popup's loading screen).

Scope `agents:admin`. Console role `owner`.

Body ([ThemeIn](#record-themein)):

- `accent` (string | null): Links, the active item, focus rings
- `accent_deep` (string | null): The accent under the pointer, and on a tint
- `accent_soft` (string | null): Tints behind highlighted things
- `background` (string | null): Behind everything
- `button` (string | null): The main button, with white words on it
- `line` (string | null): Borders and dividers
- `muted` (string | null): Secondary words: hints, labels, times
- `surface` (string | null): Cards and panels
- `text` (string | null): The words

Returns: [DemoTheme](#record-demotheme).

```sh
curl -X PUT https://app.solacia.ai/v1/demo/theme \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/demo/theme/suggestion

Colours for the demo, read from a website; nothing is saved.

Scope `agents:admin`. Console role `owner`.

Body ([ThemeSiteIn](#record-themesitein)):

- `url` (string, required): Up to 300 characters.

Returns: [ThemeSuggestion](#record-themesuggestion).

```sh
curl -X POST https://app.solacia.ai/v1/demo/theme/suggestion \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Integrations

Connect your CRM, scheduler and alerts, and say who hears about each buyer. The console uses these; most teams never call them.

### DELETE /v1/app

Forget the vendor's app and its login. In preview.

Scope `integrations:admin`. Console role `owner`.

Returns: [AppConnection](#record-appconnection).

```sh
curl -X DELETE https://app.solacia.ai/v1/app \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/app

The vendor's app the explorer checks the demo against, and what its last check found. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [AppConnection](#record-appconnection).

```sh
curl https://app.solacia.ai/v1/app \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/app

Connect the vendor's app: its sign-in page and a sandbox login, the password kept sealed. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([AppConnectionIn](#record-appconnectionin)):

- `email` (string, required): A sandbox user made for Solacia. Up to 200 characters.
- `password` (string, required): That user's password: kept sealed. Up to 200 characters.
- `url` (string, required): The app's sign-in page, https://. Up to 500 characters.

Returns: [AppConnection](#record-appconnection).

```sh
curl -X PUT https://app.solacia.ai/v1/app \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/embed

The website embeds: each key's script tag for the site's HTML, the sites it answers on, and whether it is paused. In preview.

Console role `member`. MCP tool `get_website_embed`.

Returns: [Embeds](#record-embeds).

```sh
curl https://app.solacia.ai/v1/embed \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/handoff

Every buyer who asked for the team in the last `days` days (30 by default), each step of the hand-off with why one didn't go, and where today's rules send them. In preview.

Scope `integrations:admin`. Console role `member`.

Parameters:

- `days` (integer, query): How many days back: 30 by default, up to 365. 1 to 365. Default `30`.
- `language` ("en" | "es" | "pt", query): The language each step's why and each rule's reason are written in: English, Spanish or Portuguese. Default `"en"`.
- `tests` (boolean, query): Include test demos: try links, test addresses, demos Solacia opened. Default `false`.
- `limit` (integer, query): At most this many requests, newest first; 0 for all of them. 0 to 500. Default `0`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [Handoff](#record-handoff).

```sh
curl https://app.solacia.ai/v1/handoff \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/handoff/brief-link/end

End every link a demo's brief went out with, so a forwarded or leaked one opens nothing; the next hand-off makes a new one. In preview.

Scope `integrations:admin`. Console role `member`.

Body ([BriefLinkEndIn](#record-brieflinkendin)):

- `demo` (string, required): Up to 120 characters.

Returns: [BriefLink](#record-brieflink).

```sh
curl -X POST https://app.solacia.ai/v1/handoff/brief-link/end \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations

Every integration with its state, grouped as the console's Integrations page shows them, and the scheduler and CRM the account picked.

Scope `integrations:read`. Console role `member`. MCP tool `list_integrations`.

Parameters:

- `language` ("en" | "es" | "pt", query): The language its words are in. Default `"en"`.

Returns: [Integrations](#record-integrations).

```sh
curl https://app.solacia.ai/v1/integrations \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/chilipiper/key

Connect Chili Piper by an Edge API token with Concierge permissions; pick the router next. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([ChiliPiperIn](#record-chilipiperin)):

- `token` (string, required): Up to 2000 characters.

Returns: [IntegrationConnection](#record-integrationconnection).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/chilipiper/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/chilipiper/router

The Chili Piper router buyers go through, and the token's routers with what each field gets. In preview.

Scope `integrations:admin`. Console role `owner`.

Returns: [ChiliPiperRouters](#record-chilipiperrouters).

```sh
curl https://app.solacia.ai/v1/integrations/chilipiper/router \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/chilipiper/router

Pick the Chili Piper router buyers go through and what each of its fields gets; it becomes the account's scheduler. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([ChiliPiperRouterIn](#record-chilipiperrouterin)):

- `fields` (object<string, string> | null)
- `router` (string, required): Up to 300 characters.

Returns: [ChiliPiperRouters](#record-chilipiperrouters).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/chilipiper/router \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/craft/link

Connect Craft by the link of an API connection made there for the documents the agent may answer from. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([CraftLinkIn](#record-craftlinkin)):

- `key` (string): The connection's API key, when it has one. Up to 500 characters.
- `url` (string, required): Up to 300 characters.

Returns: [InternalDocs](#record-internaldocs).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/craft/link \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/fathom/calls

The sales calls read from Fathom: what buyers asked and how reps answered, objections and how they were handled, how reps pitched. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [SalesCalls](#record-salescalls).

```sh
curl https://app.solacia.ai/v1/integrations/fathom/calls \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/fathom/calls

Read the Fathom sales calls not yet read, for up to 40 seconds; call again while unread is above 0. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([SalesCallsReadIn](#record-salescallsreadin)):

- `listed_within` (integer): Once every call is read, list the picked folders again only when the last listing is older than this many seconds (0: always). Above 0, a connection with no folders picked is no error. 0 to 86400. Default `0`.

Returns: [SalesCalls](#record-salescalls).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/fathom/calls \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/fathom/key

Connect Fathom by a user's API key made there: kept sealed, only ever read. Returns the teams and meeting types it reaches, to pick from. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([FathomKeyIn](#record-fathomkeyin)):

- `key` (string, required): The key, as Fathom showed it. Up to 500 characters.

Returns: [CallPlaces](#record-callplaces).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/fathom/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/fathom/places

The Fathom teams and meeting types the connected key reaches, and those picked as holding the sales calls. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [CallPlaces](#record-callplaces).

```sh
curl https://app.solacia.ai/v1/integrations/fathom/places \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/fathom/places

Pick the Fathom teams or meeting types holding the sales calls; their calls with someone from outside the company are listed, to be read. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([CallPicksIn](#record-callpicksin)):

- `picked` (string[], required): The refs of the folders or spaces picked.

Returns: [SalesCalls](#record-salescalls).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/fathom/places \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/granola/calls

The sales calls read from Granola: what buyers asked and how reps answered, objections and how they were handled, how reps pitched. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [SalesCalls](#record-salescalls).

```sh
curl https://app.solacia.ai/v1/integrations/granola/calls \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/granola/calls

Read the sales calls not yet read, for up to 40 seconds; call again while unread is above 0. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([SalesCallsReadIn](#record-salescallsreadin)):

- `listed_within` (integer): Once every call is read, list the picked folders again only when the last listing is older than this many seconds (0: always). Above 0, a connection with no folders picked is no error. 0 to 86400. Default `0`.

Returns: [SalesCalls](#record-salescalls).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/granola/calls \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/granola/key

Connect Granola by an API key made there: kept sealed, only ever read. Returns the folders and spaces it reaches, to pick from. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([GranolaKeyIn](#record-granolakeyin)):

- `key` (string, required): The key, as Granola showed it. Up to 500 characters.

Returns: [CallPlaces](#record-callplaces).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/granola/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/granola/places

The Granola folders and spaces the connected key reaches, and those picked as holding the sales calls. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [CallPlaces](#record-callplaces).

```sh
curl https://app.solacia.ai/v1/integrations/granola/places \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/granola/places

Pick the Granola folders or spaces holding the sales calls; the calls there are listed, to be read. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([CallPicksIn](#record-callpicksin)):

- `picked` (string[], required): The refs of the folders or spaces picked.

Returns: [SalesCalls](#record-salescalls).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/granola/places \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/hubspot_meetings/link

The HubSpot meeting link buyers book, and the connected HubSpot's links.

Scope `integrations:admin`. Console role `owner`.

Returns: [MeetingLinks](#record-meetinglinks).

```sh
curl https://app.solacia.ai/v1/integrations/hubspot_meetings/link \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/hubspot_meetings/link

Pick which of the connected HubSpot's meeting links buyers book.

Scope `integrations:admin`. Console role `owner`.

Body ([MeetingLinkIn](#record-meetinglinkin)):

- `url` (string, required): Up to 500 characters.

Returns: [MeetingLinks](#record-meetinglinks).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/hubspot_meetings/link \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meetings.hubspot.com/your-team/demo"
  }'
```

### GET /v1/integrations/zendesk/audiences

Who the connected Zendesk help center's articles are for (its user segments, or everyone), and those picked. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [ZendeskAudiences](#record-zendeskaudiences).

```sh
curl https://app.solacia.ai/v1/integrations/zendesk/audiences \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/zendesk/audiences

Pick the audiences whose published Zendesk articles the agent may answer from; their articles are read. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([AudiencePicksIn](#record-audiencepicksin)):

- `picked` (string[], required): The refs of the audiences picked.

Returns: [InternalDocs](#record-internaldocs).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/zendesk/audiences \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/zendesk/key

Refused (404): Zendesk no longer connects by an API token. It connects by signing in (POST /integrations/zendesk/sign-in). In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([ZendeskKeyIn](#record-zendeskkeyin)):

- `address` (string, required): Up to 300 characters.
- `email` (string, required): Someone who can see the articles. Up to 320 characters.
- `token` (string, required): The API token, as Zendesk showed it. Up to 500 characters.

Returns: [ZendeskAudiences](#record-zendeskaudiences).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/zendesk/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/zendesk/sign-in

Start connecting Zendesk at its address: where to send the owner to sign in and approve Solacia's read-only access to its help center. The address is checked with Zendesk first: 422 when no Zendesk account holds it. Finished like any sign-in (PUT /integrations/zendesk/connection); then pick the audiences, which a connection by API token to the same account hands over. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([ZendeskSignInIn](#record-zendesksigninin)):

- `address` (string, required): Up to 300 characters.

Returns: [IntegrationConnect](#record-integrationconnect).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/zendesk/sign-in \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/{crm}/field-map

Which of your own CRM fields get where each buyer came from (your UTM tags, ad click ids, the page and the site), each checked against your CRM. In preview.

Scope `integrations:read`. Console role `member`.

Parameters:

- `crm` (string, path, required): Up to 200 characters.
- `limit` (integer, query): 1 to 200. Default `50`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [FieldMap](#record-fieldmap).

```sh
curl https://app.solacia.ai/v1/integrations/{crm}/field-map \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/{crm}/field-map

Save which of your own CRM fields get where each buyer came from: the whole map, replacing the one before. In preview.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `crm` (string, path, required): Up to 200 characters.

Body ([FieldMapIn](#record-fieldmapin)):

- `rows` ([FieldMapRow](#record-fieldmaprow)[], required)

Returns: [FieldMap](#record-fieldmap).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/{crm}/field-map \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/{crm}/field-map/draft

Draft your field map from your account of your CRM process (a PDF, a Word file or text): which of your own CRM fields get where the buyer came from, how the demo went and the lead's stage, checked against your CRM, with what the document leaves open. Saves nothing. In preview.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `crm` (string, path, required): Up to 200 characters.

Body ([FieldMapDraftIn](#record-fieldmapdraftin)):

- `answers` ([FieldMapAnswer](#record-fieldmapanswer)[]): Your answers to the draft's questions.
- `content` (string): The file, base64: .pdf, .docx, .html, .md or .txt, up to 3 MB Up to 4200000 characters.
- `language` ("en" | "es" | "pt"): The language the questions are written in. Default `"en"`.
- `name` (string, required): Up to 200 characters.
- `rows` ([FieldMapRow](#record-fieldmaprow)[]): The draft as you edited it, to change only where your answers do.
- `text` (string): Or its text, instead of the file Up to 200000 characters.

Returns: [FieldMapDraft](#record-fieldmapdraft).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/{crm}/field-map/draft \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/{crm}/field-map/preview

What a new lead from a buyer who opens a link would get in each of your own CRM fields, by your saved map, and why a field stays empty. Writes nothing. In preview.

Scope `integrations:read`. Console role `member`.

Parameters:

- `crm` (string, path, required): Up to 200 characters.

Body ([FieldMapPreviewIn](#record-fieldmappreviewin)):

- `meeting` ("none" | "asked" | "booked"): Whether the buyer asked for a meeting in the demo, or booked one. Default `"none"`.
- `page` (string, required): The page the buyer opens, with its tags. Up to 2000 characters.
- `priority` ("hot" | "warm" | "nurture" | "cold" | null): How Solacia rated the buyer after the demo.
- `referrer` (string | null): The site that sent them.
- `rows` ([FieldMapRow](#record-fieldmaprow)[] | null): A map to preview instead of the saved one, such as a draft before it is saved.

Returns: [FieldMapPreview](#record-fieldmappreview).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/{crm}/field-map/preview \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/{crm}/fields

Your CRM's fields Solacia may write (Salesforce's Lead fields, HubSpot's contact properties), with each closed list's values: what your field map's rows are picked from. In preview.

Scope `integrations:read`. Console role `member`.

Parameters:

- `crm` (string, path, required): Up to 200 characters.
- `limit` (integer, query): 1 to 200. Default `50`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [CrmFields](#record-crmfields).

```sh
curl https://app.solacia.ai/v1/integrations/{crm}/fields \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/{id}/connect

Start connecting a provider by its owner signing in there: where to send them.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [IntegrationConnect](#record-integrationconnect).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/hubspot/connect \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/integrations/{id}/connection

Remove a connection the owner made, and Solacia's app from their account.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [IntegrationConnection](#record-integrationconnection).

```sh
curl -X DELETE https://app.solacia.ai/v1/integrations/hubspot/connection \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/{id}/connection

Finish connecting a provider with what it sent the owner back with.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([IntegrationConnectionIn](#record-integrationconnectionin)):

- `code` (string, required): Up to 2000 characters.
- `picked` (string): Google Drive: the ids of the files picked in Google's picker, comma-separated (picked_file_ids), as Google sent them back. Up to 20000 characters.
- `state` (string, required): Up to 500 characters.

Returns: [IntegrationConnection](#record-integrationconnection).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/hubspot/connection \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "CODE_FROM_THE_PROVIDER",
    "state": "STATE_FROM_CONNECT"
  }'
```

### GET /v1/integrations/{id}/docs

The internal documents a connected source (drive, craft or zendesk) lets the agent answer from. In preview.

Scope `integrations:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [InternalDocs](#record-internaldocs).

```sh
curl https://app.solacia.ai/v1/integrations/{id}/docs \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/integrations/{id}/docs

Read a source of internal docs (drive, craft or zendesk) again, so the agent answers from what it holds now. In preview.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [InternalDocs](#record-internaldocs).

```sh
curl -X POST https://app.solacia.ai/v1/integrations/{id}/docs \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/integrations/{id}/event_type

The event buyers book in a connected scheduler, and its event types.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [EventTypes](#record-eventtypes).

```sh
curl https://app.solacia.ai/v1/integrations/calendly/event_type \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/integrations/{id}/event_type

Pick which of the connected scheduler's event types buyers book.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([EventTypeIn](#record-eventtypein)):

- `id` (string, required): Up to 500 characters.

Returns: [EventTypes](#record-eventtypes).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/calendly/event_type \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "EVENT_TYPE_ID_FROM_THE_LIST"
  }'
```

### PUT /v1/integrations/{kind}

Pick the one provider the account uses for a kind: crm or scheduling.

Scope `integrations:admin`. Console role `owner`.

Parameters:

- `kind` (string, path, required): Up to 200 characters.

Body ([IntegrationChoiceIn](#record-integrationchoicein)):

- `provider` (string, required): Up to 40 characters.

Returns: [IntegrationChoice](#record-integrationchoice).

```sh
curl -X PUT https://app.solacia.ai/v1/integrations/crm \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hubspot"
  }'
```

### GET /v1/internal-docs

Where the internal docs and the public docs state one thing two ways, and which side the agent follows. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [DocsDisputes](#record-docsdisputes).

```sh
curl https://app.solacia.ai/v1/internal-docs \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/internal-docs

Pick the side the agent follows where the internal docs and the public docs disagree: internal or public. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([InternalDocsChoice](#record-internaldocschoice)):

- `prefer` ("internal" | "public", required)

Returns: [DocsDisputes](#record-docsdisputes).

```sh
curl -X PUT https://app.solacia.ai/v1/internal-docs \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/internal-docs/check

Check the internal docs not yet checked against the public docs, for up to 35 seconds; call again while unchecked is above 0. In preview.

Scope `integrations:admin`. Console role `owner`.

Returns: [DocsDisputes](#record-docsdisputes).

```sh
curl -X POST https://app.solacia.ai/v1/internal-docs/check \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/mail/events

Whether SES's events on the routed emails reach Solacia: the key, the configuration set and SNS's last post.

Scope `integrations:admin`. Console role `solacia`.

Returns: [MailEventsStatus](#record-maileventsstatus).

```sh
curl https://app.solacia.ai/v1/mail/events \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/mail/events

SES's events on the emails routed to the team (delivered, bounced, opened), as SNS posts them; each is kept with the buyer it names. For Solacia's own SNS subscription.

Scope `mail:events`. Console role `solacia`.

Body ([SnsPost](#record-snspost)):

- `Message` (string): Up to 200000 characters.
- `MessageId` (string): Up to 100 characters.
- `Signature` (string): Up to 1000 characters.
- `SignatureVersion` (string): Up to 4 characters.
- `SigningCertURL` (string): Up to 500 characters.
- `Subject` (string | null)
- `SubscribeURL` (string): Up to 2000 characters.
- `Timestamp` (string): Up to 40 characters.
- `Token` (string): Up to 1000 characters.
- `TopicArn` (string): Up to 300 characters.
- `Type` (string, required): Up to 40 characters.
- `UnsubscribeURL` (string): Up to 2000 characters.

Returns: [MailEventTaken](#record-maileventtaken).

```sh
curl -X POST https://app.solacia.ai/v1/mail/events \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/mail/events/key

A key for SNS to post SES's events with, shown once; the one before it stops working.

Scope `integrations:admin`. Console role `solacia`.

Returns: [MailEventsKeyMade](#record-maileventskeymade).

```sh
curl -X POST https://app.solacia.ai/v1/mail/events/key \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/routing

Who on the team hears about which buyers, and where the latest buyers went. In preview.

Scope `integrations:admin`. Console role `member`.

Returns: [Routing](#record-routing).

```sh
curl https://app.solacia.ai/v1/routing \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/routing

Keep the account's routing rules, in order: the first that fits a buyer decides. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([RoutingIn](#record-routingin)):

- `routes` ([RoutingRule](#record-routingrule)[], required)

Returns: [Routing](#record-routing).

```sh
curl -X PUT https://app.solacia.ai/v1/routing \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/routing/preview

Where the latest buyers would go under rules not saved yet. In preview.

Scope `integrations:admin`. Console role `member`.

Body ([RoutingIn](#record-routingin)):

- `routes` ([RoutingRule](#record-routingrule)[], required)

Returns: [RoutingPreview](#record-routingpreview).

```sh
curl -X POST https://app.solacia.ai/v1/routing/preview \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/routing/test

Email one saved rule's people the latest buyer's brief, marked as a test. In preview.

Scope `integrations:admin`. Console role `owner`.

Body ([RoutingTestIn](#record-routingtestin)):

- `route` (string, required): Up to 64 characters.

Returns: [RoutingTest](#record-routingtest).

```sh
curl -X POST https://app.solacia.ai/v1/routing/test \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Team

The people who sign in to your console and hear about buyers.

### GET /v1/me

The caller's own account: name, email and access. For a person signed in to the console.

Console role `member`.

Returns: [Person](#record-person).

```sh
curl https://app.solacia.ai/v1/me \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/me

Change the caller's own name, as the team sees it.

Console role `member`.

Body ([MeNameIn](#record-menamein)):

- `name` (string, required): How the team sees them on Team and in Handoff. Up to 80 characters.

Returns: [Person](#record-person).

```sh
curl -X PUT https://app.solacia.ai/v1/me \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/me/language

Pick the language the caller's own console speaks: en, es or pt. In preview.

Console role `member`.

Body ([MeLanguageIn](#record-melanguagein)):

- `language` ("en" | "es" | "pt", required): English, Spanish or Portuguese.

Returns: [Person](#record-person).

```sh
curl -X PUT https://app.solacia.ai/v1/me/language \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/password

Change the caller's own password, given the current one. Every session of theirs ends, this one too; the console's own form keeps its browser signed in.

Console role `member`.

Body ([MePasswordIn](#record-mepasswordin)):

- `current` (string, required): Up to 200 characters.
- `new` (string, required): At least 10 characters. Up to 200 characters.

Returns: [Person](#record-person).

```sh
curl -X POST https://app.solacia.ai/v1/me/password \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/me/picture

Change the caller's own picture, as the team sees it; an empty image takes it away.

Console role `member`.

Body ([MePictureIn](#record-mepicturein)):

- `image` (string, required): A JPEG, PNG or WebP as a base64 data: URL, at most 48 KB decoded (a square of about 160 px); empty takes the picture away. Up to 65536 characters.

Returns: [Person](#record-person).

```sh
curl -X PUT https://app.solacia.ai/v1/me/picture \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/sign-out-everywhere

End every session of the caller's, this one too. In preview.

Console role `member`.

Returns: [Person](#record-person).

```sh
curl -X POST https://app.solacia.ai/v1/me/sign-out-everywhere \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/me/started

The caller's first steps in the console, each done or not, ticked off from what is true; none once all were done. For a person signed in to the console. In preview.

Console role `member`.

Returns: [Started](#record-started).

```sh
curl https://app.solacia.ai/v1/me/started \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/me/two-step

The caller's two-step sign-in: whether it is on, and the backup codes left. In preview.

Console role `member`.

Returns: [TwoStepState](#record-twostepstate).

```sh
curl https://app.solacia.ai/v1/me/two-step \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/two-step

Start two-step sign-in: a new secret for the caller's authenticator app. In preview.

Console role `member`.

Returns: [TwoStepSetup](#record-twostepsetup).

```sh
curl -X POST https://app.solacia.ai/v1/me/two-step \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/two-step/backup-codes

Ten new backup codes in place of the old ones, for a right code. In preview.

Console role `member`.

Body ([TwoStepCodeIn](#record-twostepcodein)):

- `code` (string, required): A code from the app, or a backup code. Up to 40 characters.

Returns: [TwoStepCodes](#record-twostepcodes).

```sh
curl -X POST https://app.solacia.ai/v1/me/two-step/backup-codes \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/two-step/confirm

Turn two-step sign-in on with the app's first code; answers the backup codes, once. In preview.

Console role `member`.

Body ([TwoStepCodeIn](#record-twostepcodein)):

- `code` (string, required): A code from the app, or a backup code. Up to 40 characters.

Returns: [TwoStepCodes](#record-twostepcodes).

```sh
curl -X POST https://app.solacia.ai/v1/me/two-step/confirm \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/me/two-step/off

Turn the caller's two-step sign-in off, with a code from the app or a backup code. In preview.

Console role `member`.

Body ([TwoStepCodeIn](#record-twostepcodein)):

- `code` (string, required): A code from the app, or a backup code. Up to 40 characters.

Returns: [TwoStepState](#record-twostepstate).

```sh
curl -X POST https://app.solacia.ai/v1/me/two-step/off \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/team

Who can sign in to the account's console, and the invitations out.

Scope `team:admin`. Console role `member`.

Returns: [Team](#record-team).

```sh
curl https://app.solacia.ai/v1/team \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/team/hand-over

Give everyone a person's Handoff rules send them to someone else, with their share of the turns: before removing them, or when their alerts bounce.

Scope `integrations:admin`. Console role `owner`.

Body ([TeamHandOverIn](#record-teamhandoverin)):

- `email` (string, required): Whose place on the Handoff rules moves. Up to 254 characters.
- `to` (string, required): Who takes it: a teammate's or any work email. Up to 254 characters.

Returns: [Team](#record-team).

```sh
curl -X POST https://app.solacia.ai/v1/team/hand-over \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/team/invitations

Invite someone by email, as an owner or a member; their link is in the answer, once.

Scope `team:admin`. Console role `owner`.

Body ([TeamInviteIn](#record-teaminvitein)):

- `email` (string, required): The person's work email. Up to 254 characters.
- `role` ("owner" | "member" | "solacia"): `solacia` only for Solacia's own people. Default `"member"`.

Returns: [TeamInvited](#record-teaminvited).

```sh
curl -X POST https://app.solacia.ai/v1/team/invitations \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/team/invitations/{email}

Withdraw an invitation: its link stops working.

Scope `team:admin`. Console role `owner`.

Parameters:

- `email` (string, path, required): Up to 200 characters.

Returns: [Team](#record-team).

```sh
curl -X DELETE https://app.solacia.ai/v1/team/invitations/{email} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/team/members/{email}

Take someone off the team: they are signed out everywhere. Hand their buyers over first (POST /v1/team/hand-over) so their Handoff rules keep reaching a person.

Scope `team:admin`. Console role `owner`.

Parameters:

- `email` (string, path, required): Up to 200 characters.

Returns: [Team](#record-team).

```sh
curl -X DELETE https://app.solacia.ai/v1/team/members/{email} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PUT /v1/team/members/{email}

Change someone's role. The last owner stays an owner.

Scope `team:admin`. Console role `owner`.

Parameters:

- `email` (string, path, required): Up to 200 characters.

Body ([TeamRoleIn](#record-teamrolein)):

- `role` ("owner" | "member" | "solacia", required)

Returns: [Team](#record-team).

```sh
curl -X PUT https://app.solacia.ai/v1/team/members/{email} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/team/members/{email}/two-step

Turn off someone's two-step sign-in when they lost their phone; they sign in with their password. In preview.

Scope `team:admin`. Console role `owner`.

Parameters:

- `email` (string, path, required): Up to 200 characters.

Returns: [Team](#record-team).

```sh
curl -X DELETE https://app.solacia.ai/v1/team/members/{email}/two-step \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## API keys

Make, roll, edit and revoke the keys that call this API.

### GET /v1/api-keys

Every key that can call this account's API, the ones that stopped working, and the scopes and lifetimes a new one can have.

Scope `keys:admin`. Console role `owner`.

Returns: [ApiKeys](#record-apikeys).

```sh
curl https://app.solacia.ai/v1/api-keys \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### POST /v1/api-keys

A new key with the scopes asked for, shown once; it works at once and stops after 7, 30 or 90 days (90 when left out) or never. A key makes keys only within its own scopes.

Scope `keys:admin`. Console role `owner`.

Body ([ApiKeyIn](#record-apikeyin)):

- `expires_in_days` (7 | 30 | 90 | null): Days until it stops working: 7, 30 or 90; null for never. 90 when left out. Default `90`.
- `name` (string, required): What it is for: "Zapier", "Data warehouse". Up to 40 characters.
- `scopes` (string[], required): What it may do; see `scopes` in the list.

Returns: [ApiKeyMade](#record-apikeymade).

```sh
curl -X POST https://app.solacia.ai/v1/api-keys \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data warehouse",
    "scopes": [
      "leads:read",
      "demos:read"
    ],
    "expires_in_days": 90
  }'
```

### GET /v1/api-keys/self

The key making this call: its name, scopes and when it stops working.

Console role `member`.

Returns: [ApiKey](#record-apikey).

```sh
curl https://app.solacia.ai/v1/api-keys/self \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/api-keys/{id}

Stop a key working at once; it stays listed under `ended`.

Scope `keys:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [ApiKeys](#record-apikeys).

```sh
curl -X DELETE https://app.solacia.ai/v1/api-keys/3f9c1a7e5b2d8c40 \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### PATCH /v1/api-keys/{id}

Rename a key, narrow its scopes, or give it a new end (7, 30 or 90 days from now, or never). A key is narrowed, never widened.

Scope `keys:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([ApiKeyChange](#record-apikeychange)):

- `expires_in_days` (7 | 30 | 90 | null): A new end, this many days from now: 7, 30 or 90; null for never. Leave out to keep it.
- `name` (string | null): A new name.
- `scopes` (string[] | null): Fewer scopes: a key is narrowed, never widened.

Returns: [ApiKeys](#record-apikeys).

```sh
curl -X PATCH https://app.solacia.ai/v1/api-keys/3f9c1a7e5b2d8c40 \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      "leads:read"
    ]
  }'
```

### POST /v1/api-keys/{id}/roll

A new key in place of this one, with its name, scopes and lifetime, shown once. The old key keeps working for the overlap asked for (now, 1h, 24h, 7d), so whatever uses it can switch without downtime.

Scope `keys:admin`. Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Body ([ApiKeyRoll](#record-apikeyroll)):

- `overlap` ("now" | "1h" | "24h" | "7d", required): How long the old key keeps working beside the new one; `now` stops it at once.

Returns: [ApiKeyMade](#record-apikeymade).

```sh
curl -X POST https://app.solacia.ai/v1/api-keys/3f9c1a7e5b2d8c40/roll \
  -H "Authorization: Bearer $SOLACIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overlap": "24h"
  }'
```

### GET /v1/api-keys/{id}/usage

What a key did in the last 30 days: calls by day and by operation, its latest 50 calls, the demo links it made and the demos they brought, and its budget now. A key reads its own as `self`; another key's takes `keys:admin`.

Console role `owner`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [ApiKeyUsage](#record-apikeyusage).

```sh
curl https://app.solacia.ai/v1/api-keys/{id}/usage \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### GET /v1/chatbots

The chatbots people connected to this account by OAuth (Claude, ChatGPT), newest first, with what each may do and its calls; an owner sees everyone's, anyone else their own.

Scope `keys:admin`. Console role `member`.

Returns: [ChatbotConnections](#record-chatbotconnections).

```sh
curl https://app.solacia.ai/v1/chatbots \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

### DELETE /v1/chatbots/{id}

Stop a connected chatbot at once; it stays listed under `ended`. An owner ends anyone's, anyone else their own.

Scope `keys:admin`. Console role `member`.

Parameters:

- `id` (string, path, required): Up to 200 characters.

Returns: [ChatbotConnections](#record-chatbotconnections).

```sh
curl -X DELETE https://app.solacia.ai/v1/chatbots/{id} \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Billing

### GET /v1/billing

What the account is billed for: its plan and counter, and each buyer's day with the reason it counts as a demo or not. In preview.

Scope `demos:read`. Console role `member`.

Parameters:

- `start` (string (date) | null, query): The first day to read (Eastern Time). With none: the plan's current month so far, or the last 30 days for an account with no month running.
- `end` (string (date) | null, query): The last day, included (Eastern Time); with `start` only. Today when left out.
- `tests` (boolean, query): List the test lines too. They never count either way. Default `false`.
- `limit` (integer, query): 1 to 200. Default `50`.
- `cursor` (string, query): The previous page's next_cursor; empty for the first page. Up to 2000 characters.

Returns: [Billing](#record-billing).

```sh
curl https://app.solacia.ai/v1/billing \
  -H "Authorization: Bearer $SOLACIA_API_KEY"
```

## Records

<a id="record-activity"></a>

### Activity

- `first_at` (string, required)
- `last_at` (string, required)
- `minutes` (number, required)

<a id="record-agentasked"></a>

### AgentAsked

- `buyers` (integer, required)
- `text` (string, required)

<a id="record-agentbutton"></a>

### AgentButton

- `agenda` (string | null, required)
- `label` (string, required)

<a id="record-agentchange"></a>

### AgentChange

A change some notes ask for: what it replaces, with what, and why.

- `after` (string, required)
- `before` (string, required)
- `faults` (string[]): Why its words miss the demo-lines standard
- `field` ("opening" | "part" | "order" | "instructions" | "fact", required): opening and part: words said as written; order: the parts it shows first; instructions: its rules, whole; fact: something it knows
- `id` (string, required)
- `lang` (string | null)
- `name` (string | null): A fact's name
- `notes` (string[], required): The notes it answers
- `part` (string | null)
- `why` (string, required)

<a id="record-agentchangein"></a>

### AgentChangeIn

What changes; anything left out stays as it is.

- `facts` ([AgentFact](#record-agentfact)[] | null): Replaces all its facts
- `instructions` (string | null)
- `list_price` (boolean): Back to the list price for its renderer; Solacia only Default `false`.
- `name` (string | null)
- `price` (integer | null): US cents a demo; Solacia only
- `renderer` ("voice" | "face" | null)
- `retired` (boolean | null): true pauses it everywhere: its website rules and links send buyers to the next rule or the default until false resumes it. Refused while it holds a default or is in a test
- `tone` ("brief" | "warm" | "expert" | "pack" | null): pack: as the brief says
- `voices` (object<string, string> | null): Voice id per language; Solacia only. Empty: the product's

<a id="record-agentchangekept"></a>

### AgentChangeKept

- `after` (string, required): Up to 4000 characters.
- `field` ("opening" | "part" | "order" | "instructions" | "fact", required)
- `id` (string): Up to 40 characters.
- `lang` (string | null)
- `name` (string | null)
- `notes` (string[])
- `part` (string | null)

<a id="record-agentchanges"></a>

### AgentChanges

- `schema` (string): Default `"solacia.agents.v0"`.
- `changes` ([AgentChange](#record-agentchange)[], required)

<a id="record-agentchangesapplyin"></a>

### AgentChangesApplyIn

- `dropped` (string[]): Notes closed with no change
- `kept` ([AgentChangeKept](#record-agentchangekept)[]): Into the draft

<a id="record-agentchangesin"></a>

### AgentChangesIn

- `notes` (string[] | null): The notes to read; all the open ones when left out

<a id="record-agentchoicein"></a>

### AgentChoiceIn

- `agenda` (string | null): The part it picks
- `label` (object<string, string>): Its words per language

<a id="record-agentchoiceout"></a>

### AgentChoiceOut

- `agenda` (string | null, required): The part it picks; null: its words are said for the buyer
- `label` (object<string, string>, required): Its words per language; empty: the part's title

<a id="record-agentdefaultin"></a>

### AgentDefaultIn

The agent the caller sends personal links with unless they pick another.

- `agent` (string | null): Null: the outbound channel's

<a id="record-agentdetail"></a>

### AgentDetail

One agent: its live version, its draft, every version, and its script. In preview.

- `schema` (string): Default `"solacia.agents.v0"`.
- `base` (boolean, required)
- `draft` ([AgentDraftOut](#record-agentdraftout) | null, required)
- `id` (string, required)
- `in_test` (boolean, required): One side of a running test: nothing can be published until it stops
- `languages` (string[], required)
- `live` ([AgentVersionContent](#record-agentversioncontent), required)
- `name` (string, required)
- `notes` ([AgentNote](#record-agentnote)[]): Notes left on its rehearsals that no version took yet, oldest first
- `places` ([AgentPlace](#record-agentplace)[]): Where it runs, with the last 30 days
- `rehearsals` ([AgentRehearsalMark](#record-agentrehearsalmark)[]): Its newest rehearsals
- `renderer` ("voice" | "face"): What buyers get: the voice, or voice and face Default `"voice"`.
- `replaces` ([AgentFactReplaces](#record-agentfactreplaces)[] | null): What the facts it shows (the draft's, else the live version's) replace in the public docs; null while they are being checked
- `retired` (boolean, required): Paused: it meets no buyer anywhere until resumed
- `runs` (("embed" | "outbound" | "link")[]): The defaults it holds; it can't pause until they move
- `script` ([AgentScriptOut](#record-agentscriptout), required)
- `script_of` ("draft" | "live", required): Which version `script` shows
- `test` ([AgentTest](#record-agenttest) | null, required): Its running test between its versions
- `tests_started` ([AgentTestMark](#record-agenttestmark)[]): Its tests between versions
- `unanswered` ([AgentAsked](#record-agentasked)[]): What its buyers asked in the last 30 days that the docs held no answer to
- `version` (integer, required)
- `versions` ([AgentVersionOut](#record-agentversionout)[], required): Oldest first
- `weeks` ([AgentWeek](#record-agentweek)[]): Its last 12 weeks, oldest first

<a id="record-agentdraftin"></a>

### AgentDraftIn

What changes in the agent's draft; anything left out stays as the draft (or, with no draft, the live version) has it.

- `audience` (string | null)
- `counts` ("qualified" | "meeting" | null): What reaching the goal is: the buyer qualifies, or asks to meet the team
- `facts` ([AgentFact](#record-agentfact)[] | null): Replaces all its facts
- `goal` (string | null)
- `instructions` (string | null)
- `script` ([AgentScriptIn](#record-agentscriptin) | null)
- `tone` ("brief" | "warm" | "expert" | "pack" | null): pack: as the brief says
- `voices` (object<string, string> | null): Voice id per language; Solacia only

<a id="record-agentdraftout"></a>

### AgentDraftOut

- `at` (string, required)
- `behind` (boolean, required): Another version went live after it was started: publishing is refused
- `by` (string | null, required)
- `content` ([AgentVersionContent](#record-agentversioncontent), required)
- `faults` (string[], required): Why its own lines can't go live yet; empty: it can be published
- `since` (integer, required): The version it was started from

<a id="record-agentfact"></a>

### AgentFact

- `name` (string, required): What it is about; one named like the docs' replaces it Up to 80 characters.
- `text` (string, required): What the agent says about it Up to 600 characters.

<a id="record-agentfactreplaces"></a>

### AgentFactReplaces

A public passage one of the agent's facts contradicts, left out of its calls' docs.

- `fact` (string, required): The fact's name
- `page` (string, required): The page's title
- `says` (string, required): The page's sentence the fact replaces
- `url` (string, required)
- `what` (string, required): What the two state differently, in a few words

<a id="record-agentin"></a>

### AgentIn

A new agent: the pack run another way. It runs nothing until a channel is given to it.

- `copy_of` (string | null): Start from this agent's tone, instructions, facts and voices
- `name` (string, required): Up to 200 characters.
- `price` (integer | null): US cents a demo; Solacia only. Left out: the list price
- `renderer` ("voice" | "face"): Default `"voice"`.

<a id="record-agentlevers"></a>

### AgentLevers

What a test on the agent can learn, a lever at a time, from its last 30 days. In preview.

- `schema` (string): Default `"solacia.agents.v0"`.
- `agent` (string, required)
- `buyers` (integer, required): Its real buyers of the last 30 days
- `levers` ([Lever](#record-lever)[], required)

<a id="record-agentline"></a>

### AgentLine

- `own` (boolean, required): The agent's own words; false: the product's
- `pack` (string | null): The product's words it replaces, when it is the agent's own
- `text` (string, required)

<a id="record-agentnote"></a>

### AgentNote

- `at` (string, required)
- `by` (string, required)
- `done` (string | null): The version it went into, or dropped; null while open
- `id` (string, required)
- `quote` (string, required): The turn's words when it was left
- `session` (string, required): The rehearsal it was left on
- `tag` ("script" | "answer" | "screen" | "buyer", required)
- `text` (string, required)
- `turn` (integer, required): The turn it is about (AgentTurn.n)

<a id="record-agentnotein"></a>

### AgentNoteIn

- `session` (string, required): Up to 80 characters.
- `text` (string, required): Up to 1000 characters.
- `turn` (integer, required)

<a id="record-agentnotes"></a>

### AgentNotes

- `schema` (string): Default `"solacia.agents.v0"`.
- `notes` ([AgentNote](#record-agentnote)[], required)

<a id="record-agentnumbers"></a>

### AgentNumbers

- `demos` (number, required)
- `engaged` (number, required)
- `meetings` (number, required): Demos where the buyer asked for a meeting
- `minutes` (number, required)
- `spend` (number | null, required): US cents: each demo at the price of the agent that ran it, when it ran. Solacia's people only; null for everyone else

<a id="record-agentout"></a>

### AgentOut

- `audience` (string): Who its demos are for, in the team's words
- `base` (boolean, required): The first agent, the product's pack: every other one is built on it
- `changed_at` (string | null, required)
- `changed_by` (string | null, required)
- `cost` (integer | null, required): US cents a demo. Solacia's people only; null for everyone else
- `counts` ("qualified" | "meeting"): What reaching its goal is Default `"qualified"`.
- `facts` ([AgentFact](#record-agentfact)[], required): What only it knows, said at once like the docs
- `goal` (string): What a demo with it is for, in the team's words
- `id` (string, required)
- `instructions` (string, required): What it does differently on a call, in the team's words
- `last_30_days` ([AgentNumbers](#record-agentnumbers), required)
- `list_price` (integer | null, required): US cents a demo at the list price for its renderer. Solacia's people only; null otherwise
- `name` (string, required): The team's name for it; buyers meet the guide by its own name
- `placed` ([AgentPlaced](#record-agentplaced)): How many places of each kind it meets buyers in
- `renderer` ("voice" | "face", required): What buyers get: the guide's voice, or voice and face
- `retired` (boolean, required): Paused: it meets no buyer anywhere until resumed
- `runs` (("embed" | "outbound" | "link")[], required): The channels whose demos it runs
- `state` ("testing" | "draft" | "live" | "idle" | "paused"): testing: in a running test; draft: a draft waits to go live; live: meets buyers; idle: meets nobody; paused: retired, its places sending buyers on until it resumes Default `"live"`.
- `tone` ("brief" | "warm" | "expert" | null, required): How it talks; null: as the product's brief says
- `version` (integer): Its live version; GET /v1/agents/{id} has every one Default `1`.
- `voices` (object<string, string>, required): Its voice id per language, where not the product's

<a id="record-agentpart"></a>

### AgentPart

- `id` (string, required)
- `intro` (object<string, [AgentLine](#record-agentline)>, required): Language -> the agent's own introduction, said after the name; the product has none
- `name` (object<string, string>): Language -> the sentence the part opens on, said by the call
- `shows` (boolean, required): In the agent's focus; the ones it shows come first, in its order
- `title` (object<string, string>, required)

<a id="record-agentplace"></a>

### AgentPlace

One place the agent meets buyers, with its last 30 days: `rule`, a website rule on where buyers came from (`when` source) or the page (`when` page); `website`, the website's buyers no rule picks; `campaign`, the personal links of one campaign made with it; `links`, personal links with no campaign (with the account's default, also links that name no agent); `address`, the product's own demo address.

- `campaign` (string | null)
- `demos` (integer): Default `0`.
- `kind` ("rule" | "website" | "campaign" | "links" | "address", required)
- `links` (integer | null): Links made, for a campaign or single links
- `match` (string | null)
- `reached` (integer): Demos that reached the agent's goal Default `0`.
- `when` ("source" | "page" | null)

<a id="record-agentplaced"></a>

### AgentPlaced

How many places of each kind an agent meets buyers in; GET /v1/agents/{id} lists each.

- `address` (boolean): It meets buyers on the product's own demo address Default `false`.
- `campaigns` (integer): Campaigns whose personal links were made with it Default `0`.
- `links` (integer): Personal links made with it outside any campaign Default `0`.
- `outreach` (boolean): Personal links made with no agent named meet it Default `false`.
- `pages` (integer): Website rules on a page Default `0`.
- `sources` (integer): Website rules on where buyers came from Default `0`.
- `website` (boolean): It meets the website's buyers no rule picks Default `false`.

<a id="record-agentrehearsal"></a>

### AgentRehearsal

A rehearsal read back, turn by turn, with the notes on it. In preview.

- `schema` (string): Default `"solacia.agents.v0"`.
- `at` (string, required)
- `by` (string, required)
- `notes` ([AgentNote](#record-agentnote)[], required)
- `of` (integer | "draft", required)
- `parts` ([AgentScriptPart](#record-agentscriptpart)[], required)
- `session` (string, required)
- `turns` ([AgentTurn](#record-agentturn)[], required)
- `url` (string, required): The demo, to go on with it

<a id="record-agentrehearsalmark"></a>

### AgentRehearsalMark

- `at` (string, required)
- `by` (string, required)
- `notes` (integer, required): Open notes on it
- `of` (integer | "draft", required): What it ran: a version, or the draft as it was then
- `session` (string, required)
- `url` (string, required): The demo, to go on with it

<a id="record-agentrehearsein"></a>

### AgentRehearseIn

- `of` (integer | "draft"): A version's number, or the draft as it is now Default `"draft"`.

<a id="record-agentroutein"></a>

### AgentRouteIn

- `agent` (string, required): The id of the agent to run the channel's demos Up to 80 characters.

<a id="record-agentrule"></a>

### AgentRule

One website rule: buyers who came from `match` (when `source`: one of your own tags by its name such as utm_campaign=spring-launch, a tag's value in any tag such as spring-launch, a referring site such as linkedin, or a channel such as paid or social), or who opened the demo on a page under `match` (when `page`: a path such as /card), meet `agent`.

- `agent` (string, required): Up to 80 characters.
- `match` (string, required): Up to 120 characters.
- `when` ("source" | "page", required)

<a id="record-agentrulesin"></a>

### AgentRulesIn

The website's rules, in order: the whole list, replacing the one before. Empty: every website buyer meets the embed channel's agent.

- `rules` ([AgentRule](#record-agentrule)[], required)

<a id="record-agentscriptin"></a>

### AgentScriptIn

What changes of the agent's script; each field sent replaces that field whole.

- `choices` ([AgentChoiceIn](#record-agentchoicein)[] | null): Its own buttons under the opening; []: the product's
- `intro` (object<string, string> | null): Its own opening per language; {}: the product's
- `lines` (object<string, object<string, string>> | null): Its own introduction to a part, per language; {}: the product's
- `order` (string[] | null): The parts it shows, in order; []: all of the product's

<a id="record-agentscriptout"></a>

### AgentScriptOut

The script as a buyer meets it, each line marked when it is the agent's own.

- `buttons` (object<string, [AgentButton](#record-agentbutton)[]>, required)
- `first_deck` (string | null, required): A deck that starts the demo by itself, so the opening asks nothing
- `opening` (object<string, [AgentLine](#record-agentline)>, required)
- `own_buttons` (boolean, required)
- `parts` ([AgentPart](#record-agentpart)[], required)

<a id="record-agentscriptpart"></a>

### AgentScriptPart

- `id` (string, required)
- `title` (string, required)

<a id="record-agentsuggestion"></a>

### AgentSuggestion

A test worth running, read from what the agent's buyers did in the last 30 days.

- `buyers` (integer, required): The buyers the pattern is about
- `id` (string, required): opening, or part:<part id>: what a test would change
- `kind` ("left_on_part" | "left_early", required): left_on_part: buyers who stayed past the first minute and left without the goal left while this part was on; left_early: buyers left in the first minute, in the opening
- `of` (integer, required): Out of: every demo for left_early, the ones that left without the goal otherwise
- `part` (string | null)
- `title` (object<string, string> | null): The part's title per language

<a id="record-agentsuggestions"></a>

### AgentSuggestions

- `schema` (string): Default `"solacia.agents.v0"`.
- `suggestions` ([AgentSuggestion](#record-agentsuggestion)[], required)

<a id="record-agenttest"></a>

### AgentTest

- `agent` (string | null): The agent whose versions are the sides, wherever it is placed
- `arms` ([TestArm](#record-testarm)[], required)
- `by` (string | null, required)
- `chances` (number[]): The best challenger against A: worse, about the same, better
- `channel` ("embed" | "outbound" | "link" | null, required): Null: a test between one agent's versions
- `ended` (boolean, required): Past its end and not stopped: new buyers meet side A, one side waits to be kept
- `ends` (string | null, required): When it stops taking buyers; null: when the team stops it
- `guardrails` ([TestGuardrail](#record-testguardrail)[]): Between an agent's versions: what the test must not make worse, side A against B
- `high` (number, required)
- `id` (string, required)
- `kept` (string | null, required): The agent kept for the channel when it stopped
- `leader` (string | null, required)
- `lever` ("message" | "features" | "pricing" | "offer" | "qualification" | null): What it is to learn, when it was started from a lever
- `lift` (number, required): The best challenger's meeting rate minus A's
- `looks` ([TestLook](#record-testlook)[]): Week by week, oldest first
- `low` (number, required): 95% interval of that difference, valid however often it is read
- `meetings_from` ("demo" | "form" | "crm" | "qualified"): What counts as a meeting. demo: asking in the demo; form: that, or sending the vendor's own demo form (the website against no demo); crm: a meeting the account's CRM shows booked after the prospect's link was made (outreach against no demo); qualified: the buyer qualified, hot or warm, which asking for a meeting also is (a test between versions) Default `"demo"`.
- `min_buyers` (integer, required): Buyers each side needs before any verdict
- `more` (integer, required): Buyers each side still needs: before any verdict when early, to decide when ahead
- `per_side_week` (number | null): Buyers a week on its smallest side, from its whole weeks so far
- `question` (string, required)
- `rule` ("unless_worse" | "proven"): How it decides. proven: a side goes live once it beats the others past chance; unless_worse (between an agent's versions): a challenger may go live once keeping it would cost under 0.2 points on average if it were worse, read at the end of each week Default `"proven"`.
- `says` (string, required): The readout in one sentence
- `sides` ([TestSide](#record-testside)[]): Between an agent's versions: how far each side's buyers got
- `srm` (number, required): p-value of the sample-ratio check
- `started` (string, required)
- `stopped` (string | null, required)
- `verdict` ("early" | "ahead" | "winner" | "even" | "safe" | "broken", required): winner: one side beats every other past chance, on an interval that holds however often the test is read; safe (unless_worse): at the end of one of its weeks a challenger risked under 0.2 points if worse, so it may go live (`leader`); even: the gap is proven under 2 points; broken: the buyers did not fall on the sides as the shares say
- `weeks_left` (integer | null): Weeks until `more` buyers a side arrive at that pace; null when not counting

<a id="record-agenttestcrmcheck"></a>

### AgentTestCrmCheck

- `checked` (integer, required): Prospects whose meetings this check read
- `detail` (string, required): Why nothing could be read; empty when the CRM answered
- `marked` (integer): Contacts newly marked with their side in the CRM's Solacia test group field Default `0`.
- `meetings` (integer, required): Of them, the ones with a meeting booked since their link was made

<a id="record-agenttestin"></a>

### AgentTestIn

A test on one channel: side A is the agent that runs it now; two or three sides, each a different agent with at least 10% of buyers, adding to 100.

- `arms` ([TestArmIn](#record-testarmin)[], required)
- `channel` ("embed" | "outbound" | "link", required)
- `min_buyers` (integer): Buyers each side needs before any verdict 20 to 100000. Default `20`.
- `question` (string): Up to 200 characters.
- `weeks` (integer | null): How long it takes buyers; left out: until stopped

<a id="record-agenttestmark"></a>

### AgentTestMark

- `id` (string, required)
- `kept` (string | null, required)
- `started` (string, required)
- `stopped` (string | null, required)

<a id="record-agenttestplan"></a>

### AgentTestPlan

What a test of the agent's versions would catch at its pace, before it starts. Simulated.

- `agent` (string, required)
- `counts` ("qualified" | "meeting", required): What its goal counts, the test's primary metric
- `gaps` ([TestPlanGap](#record-testplangap)[], required)
- `guardrails` (("meetings" | "minutes" | "left_early")[], required): What the test watches beside its goal
- `per_week` (integer, required): Buyers a week it meets, from its last four weeks
- `rate` (number, required): Its rate on what its goal counts: qualified, or asked to meet
- `rate_known` (boolean, required): False: it has too few buyers yet, so 20% is assumed
- `share` (integer, required): Percent of buyers on the challenger
- `weeks` (integer, required): How long each simulated test may run

<a id="record-agentteststopin"></a>

### AgentTestStopIn

- `keep` (string | null): The agent to run the channel from now on; in a test between an agent's versions, the side (A, B or C) whose version goes live

<a id="record-agentturn"></a>

### AgentTurn

- `at` (string, required)
- `check` ("backed" | "drifted" | "wrong" | "unchecked" | null): An answer: what the docs made of it
- `n` (integer, required): Its place in the rehearsal, from 1
- `own` (string | null): In a script turn, the words in it that were the agent's own
- `part` (string | null): The part of the script it belongs to, when known
- `sources` (string[]): An answer's pages, or the details nothing backed
- `tag` ("script" | "answer" | "screen" | "buyer", required): Where its words came from: script (said as written), answer (the agent's own), screen (what it showed), buyer
- `text` (string, required)

<a id="record-agentversioncontent"></a>

### AgentVersionContent

A version: what a buyer gets from the agent. Script fields left empty are the pack's.

- `audience` (string, required): Who its demos are for, in the team's words
- `choices` ([AgentChoiceOut](#record-agentchoiceout)[], required): Its own buttons under the opening
- `counts` ("qualified" | "meeting"): What reaching the goal is, as a test of its versions reads it Default `"qualified"`.
- `facts` ([AgentFact](#record-agentfact)[], required)
- `goal` (string, required): What a demo with it is for, in the team's words
- `instructions` (string, required)
- `intro` (object<string, string>, required): Its own opening per language
- `lines` (object<string, object<string, string>>, required): Its own introduction to a part, per language
- `order` (string[], required): The parts it shows, in order; empty: all of the product's
- `tone` ("brief" | "warm" | "expert" | null, required)
- `voices` (object<string, string>, required)

<a id="record-agentversionout"></a>

### AgentVersionOut

- `at` (string | null, required): When it went live; null for the pack's own first version
- `by` (string | null, required)
- `changed` (string[]): What it changed from the version before, in the team's words, such as Opening or Order of parts; or that it put an older version back. Empty for the first.
- `live` (boolean, required)
- `number` (integer, required)

<a id="record-agentversiontestin"></a>

### AgentVersionTestIn

A test between one agent's versions, wherever it is placed: side A is its live version; two or three sides, each a different version or its draft, with at least 10% of buyers, adding to 100. Read on the share of buyers who qualified.

- `lever` ("message" | "features" | "pricing" | "offer" | "qualification" | null): What it is to learn (GET /agents/{id}/levers): it is read on that lever's goal
- `min_buyers` (integer): Buyers each side needs before any verdict 20 to 100000. Default `20`.
- `question` (string): Up to 200 characters.
- `rule` ("unless_worse" | "proven"): unless_worse: a challenger may go live unless it is worse; proven: only once it is proven better Default `"unless_worse"`.
- `sides` ([VersionSideIn](#record-versionsidein)[], required)
- `weeks` (integer | null): How long it takes buyers; left out: until stopped

<a id="record-agentweek"></a>

### AgentWeek

- `demos` (integer, required)
- `meetings` (integer, required)
- `reached` (integer, required): Buyers who did what its goal counts
- `start` (string, required): Its Monday

<a id="record-agents"></a>

### Agents

The account's agents, and the agent each channel runs: `embed` (the vendor's website), `outbound` (personal links from outreach) and `link` (the demo's own address). Then each channel's pace, and the tests between agents, newest first.

- `schema` (string): Default `"solacia.agents.v0"`.
- `agents` ([AgentOut](#record-agentout)[], required)
- `defaults` (object<string, string>): The agent each teammate sends links with unless they pick another, by their email
- `languages` (string[], required): The languages the demo's calls speak
- `list_prices` (object<string, integer> | null, required): US cents a demo for each renderer. Solacia's people only; null for everyone else
- `pace` (object<string, [ChannelPace](#record-channelpace)>, required)
- `routes` (object<string, string>, required)
- `rules` ([AgentRule](#record-agentrule)[]): The website's rules, in order: which agent a buyer meets by where they came from (the first that matches), then by the page the demo opened on (the most specific)
- `tests` ([AgentTest](#record-agenttest)[], required)
- `tones` (object<string, [ToneOut](#record-toneout)>, required)
- `voice_pool` (object<string, [VoicePool](#record-voicepool)>): The voices an agent can have, per language the demo speaks; empty when the product speaks with voices outside the pool

<a id="record-analytics"></a>

### Analytics

The team's analytics for the last `days` days against the days before: KPIs, activity by day, the funnel, what buyers told us, what they saw and asked, every session, companies. Shape v0: fields beyond these may still change; the Analytics screen owns them.

- `schema` (string): Default `"solacia.analytics.v0"`.
- `end` (string, required)
- `period_days` (integer, required)
- `start` (string, required)

<a id="record-anchor"></a>

### Anchor

- `at` (string, required): When that second was heard, ISO 8601.
- `s` (number, required): Seconds into the sound.

<a id="record-apibudgetuse"></a>

### ApiBudgetUse

One window of a key's budget, as it stands now.

- `limit` (integer, required): Units the key may spend in the window.
- `used` (integer, required): Units spent in the window so far.
- `window` ("minute" | "day", required)

<a id="record-apicall"></a>

### ApiCall

One call a key made. No network address is kept.

- `at` (string, required): When it arrived, ISO 8601.
- `client` (string, required): The caller's User-Agent, cut short.
- `country` (string, required): Where it came from, as the host reads it: two letters, or empty.
- `ms` (integer | null, required): How long it took to answer, in milliseconds.
- `operation` (string, required)
- `request_id` (string, required): Its X-Request-Id, to match the caller's own logs.
- `status` (integer | null, required): The HTTP status it answered with; null while it runs.

<a id="record-apicallday"></a>

### ApiCallDay

One day (UTC) of a key's calls, by how they answered.

- `day` (string, required): YYYY-MM-DD.
- `failed` (integer, required): Failed on our side (5xx), or never answered.
- `limited` (integer, required): Over the key's budget (429).
- `ok` (integer, required): Answered.
- `refused` (integer, required): Refused: the key, its scopes or the input; the caller's to fix.

<a id="record-apikey"></a>

### ApiKey

A key that can call this account's API, or one that could. Solacia keeps its hash, never the key.

- `at` (string): When it was made, ISO 8601.
- `by` (string): Who made it.
- `calls_30d` (integer): The calls it made in the last 30 days, refused ones included. Default `0`.
- `daily_calls` (integer[]): Its calls on each of the last 30 days (UTC), oldest first; the last is today.
- `ended_at` (string): When it stopped working, ISO 8601; empty while it works.
- `ended_by` (string): Who revoked it.
- `ended_why` ("" | "revoked" | "rolled" | "leaked" | "expired"): Why it stopped: `revoked` by a person, `rolled` into a new key, `leaked` (found in public and revoked by Solacia), or `expired`; empty while it works.
- `expires_at` (string | null): When it stops working, ISO 8601; null: never.
- `hint` (string): The key's prefix and last four characters, `sol_live_clara_…z1x9`; empty for older keys.
- `id` (string, required): The key's id: a prefix of its hash. Revoke, edit and roll it by this.
- `last_used_at` (string | null): When it last made a call, ISO 8601; null: never.
- `leaks` ([ApiKeyLeak](#record-apikeyleak)[]): Each place it was found in public, oldest first.
- `made_by_solacia` (boolean): Made by Solacia for a script or a partner. Default `false`.
- `name` (string, required): What it is for.
- `rolled_from` (string): The id of the key this one replaced in a roll.
- `scopes` (string[], required)
- `state` ("active" | "expired" | "revoked"): Whether it works: `expired` is past its end, `revoked` was stopped. Default `"active"`.
- `yours` (boolean): The key making this call. Default `false`.

<a id="record-apikeychange"></a>

### ApiKeyChange

What to change on a key; a field left out stays as it is.

- `expires_in_days` (7 | 30 | 90 | null): A new end, this many days from now: 7, 30 or 90; null for never. Leave out to keep it.
- `name` (string | null): A new name.
- `scopes` (string[] | null): Fewer scopes: a key is narrowed, never widened.

<a id="record-apikeyin"></a>

### ApiKeyIn

- `expires_in_days` (7 | 30 | 90 | null): Days until it stops working: 7, 30 or 90; null for never. 90 when left out. Default `90`.
- `name` (string, required): What it is for: "Zapier", "Data warehouse". Up to 40 characters.
- `scopes` (string[], required): What it may do; see `scopes` in the list.

<a id="record-apikeyleak"></a>

### ApiKeyLeak

One place a key was found in public, as GitHub's secret scanning reported it.

- `at` (string, required): When GitHub reported it, ISO 8601.
- `place` (string, required): The same in words: `a commit`, `an npm package`, `public code`.
- `revoked` (boolean, required): This report revoked the key; false when it had already stopped.
- `source` (string, required): What it was found in, in GitHub's words: `commit`, `content`, `npm`, ...
- `url` (string, required): Where it was found; empty when GitHub gave no public address.

<a id="record-apikeymade"></a>

### ApiKeyMade

- `ended` ([ApiKey](#record-apikey)[]): Revoked keys and keys past their end, the latest 50, newest first.
- `id` (string, required): The new key's id.
- `keys` ([ApiKey](#record-apikey)[], required)
- `lifetimes` ((integer | null)[]): How many days a new key can work; null is never.
- `scopes` ([ApiScope](#record-apiscope)[], required)
- `secret` (string, required): The key, shown this once: Solacia keeps only its hash.

<a id="record-apikeyroll"></a>

### ApiKeyRoll

- `overlap` ("now" | "1h" | "24h" | "7d", required): How long the old key keeps working beside the new one; `now` stops it at once.

<a id="record-apikeyusage"></a>

### ApiKeyUsage

What one key did in the last 30 days: its calls by day and by operation, its latest calls, the demo links it made and the demos they brought, and its budget now.

- `budget` ([ApiBudgetUse](#record-apibudgetuse)[], required): Its budget per minute and per day; empty when the API counts none.
- `calls` (integer, required): Calls in the last 30 days, refused ones included.
- `days` ([ApiCallDay](#record-apicallday)[], required): The last 30 days (UTC), oldest first; the last is today.
- `demos_caused` (integer, required): Demos in the last 30 days that came in by a link it made, whenever it made it.
- `key` ([ApiKey](#record-apikey), required)
- `links_made` (integer, required): Personal demo links it made in the last 30 days.
- `operations` ([ApiOperationUse](#record-apioperationuse)[], required): What it called, the most called first.
- `recent` ([ApiCall](#record-apicall)[], required): Its latest 50 calls, newest first.

<a id="record-apikeys"></a>

### ApiKeys

Every key that can call this account's API, newest first, the keys that stopped working, and what a new one can be.

- `ended` ([ApiKey](#record-apikey)[]): Revoked keys and keys past their end, the latest 50, newest first.
- `keys` ([ApiKey](#record-apikey)[], required)
- `lifetimes` ((integer | null)[]): How many days a new key can work; null is never.
- `scopes` ([ApiScope](#record-apiscope)[], required)

<a id="record-apioperationuse"></a>

### ApiOperationUse

One operation a key called in the last 30 days.

- `calls` (integer, required)
- `failed` (integer, required)
- `limited` (integer, required)
- `operation` (string, required): The operation's name, as in the contract: `leads.list`.
- `refused` (integer, required)

<a id="record-apiscope"></a>

### ApiScope

- `can` (string, required): What a key with it can do, in words.
- `name` (string, required): The scope, as a key carries it: `leads:read`.

<a id="record-appcheckresult"></a>

### AppCheckResult

The explorer's last check of the vendor's app, signed in as the sandbox user: when, how many screens it reached, what changed since the check before, or why it could not check.

- `changes` (string[])
- `checked` (string, required)
- `compared` (boolean): False on the first check: nothing before it to compare with. Default `true`.
- `error` (string)
- `screens` (integer, required)

<a id="record-appconnection"></a>

### AppConnection

The vendor's own app, connected so the explorer can check the demo against it (in preview): its address and the sandbox user it signs in as. The password is never sent back. `connected` is false when none is.

- `at` (string)
- `by` (string)
- `check` ([AppCheckResult](#record-appcheckresult) | null)
- `connected` (boolean, required)
- `email` (string)
- `url` (string)

<a id="record-appconnectionin"></a>

### AppConnectionIn

- `email` (string, required): A sandbox user made for Solacia. Up to 200 characters.
- `password` (string, required): That user's password: kept sealed. Up to 200 characters.
- `url` (string, required): The app's sign-in page, https://. Up to 500 characters.

<a id="record-audiencepicksin"></a>

### AudiencePicksIn

- `picked` (string[], required): The refs of the audiences picked.

<a id="record-billing"></a>

### Billing

What the account is billed for: its plan and counter, and one line per buyer per day with the reason it counts or not. A demo is a conversation of two minutes or more between one buyer and the agent, or a shorter one in which the buyer booked a meeting, once per buyer per Eastern day; tests never count, and neither does a call that ended on Solacia's side unless a meeting was booked. In preview.

- `count` ([BillingCount](#record-billingcount), required): Over every line of the days, whatever the page.
- `end` (string (date), required)
- `final_through` (string (date) | null, required): The last day closed; null: no day is final yet.
- `items` ([BillingLine](#record-billingline)[], required): The lines, newest first.
- `next_cursor` (string | null, required)
- `plan` ([BillingPlan](#record-billingplan) | null, required): Null: the account has no plan yet.
- `rules` (string, required): The version of the counting rules.
- `start` (string (date), required)
- `total` (integer): Lines of the days, over every page. Default `0`.

<a id="record-billingcorrection"></a>

### BillingCorrection

A correction Solacia made to a final line: the line counts as it says from then on.

- `at` (string, required): When, ISO 8601.
- `reason` (string, required)

<a id="record-billingcount"></a>

### BillingCount

The days read, in the five words every report uses, and why the other lines did not count. Tests are left out of all of them and counted apart.

- `booked` (integer): Of `demos`, the ones under two minutes that count by a booked meeting. Default `0`.
- `corrected` (integer, required): Demos a correction took out.
- `demos` (integer, required): The billed unit: buyers on a day with two minutes of conversation or more, or with a meeting booked in a shorter one.
- `meetings` (integer, required): Buyers on a day who asked for the account's team. Reported, never billed.
- `none` (integer, required): Lines with no conversation.
- `opened` (integer, required): Times the demo was opened.
- `our_side` (integer, required): Lines whose calls ended on Solacia's side.
- `qualified` (integer, required): Demos whose buyer fits the account's rules. Reported, never billed.
- `short` (integer, required): Lines under two minutes.
- `talked` (integer, required): Buyers on a day with any conversation.
- `tests` (integer, required): Lines left out as tests.
- `timed_out` (integer, required): Lines whose calls timed out with nothing heard.

<a id="record-billingline"></a>

### BillingLine

One buyer on one Eastern day, and whether it counts as a demo.

- `at` (string, required): The first word, ISO 8601; the first opening when nobody talked.
- `audience` ("buyer" | "vendor" | "made_up" | "test" | "staff" | "try" | "rehearsal", required): Who the demo is for. buyer: someone the vendor could sell to. vendor: a prospect's own people on a link Solacia made. made_up: a made-up buyer on dev. test: an address at the vendor's or Solacia's domain. staff: opened by Solacia's team. try: opened by a try link. rehearsal: the team rehearsing an agent. `test` is true for test, staff, try and rehearsal.
- `booked` (boolean): The buyer booked a meeting with the account's team that day, in the demo. Default `false`.
- `buyer` (string, required): Their work email; "" for an anonymous buyer.
- `calls` (integer, required)
- `correction` ([BillingCorrection](#record-billingcorrection) | null): The correction that stands, if any.
- `counted` (boolean, required): It is a demo: the billed unit.
- `cut` (integer, required): Seconds of calls that ended on Solacia's side: never counted.
- `day` (string (date), required): The Eastern day.
- `demos` (string[], required): That day's demos of this buyer, oldest first: ids for GET /v1/demos/{id}.
- `door` (string | null, required): How they arrived, as on a demo.
- `final` (boolean, required): Its day is closed: the line no longer changes, except by a correction.
- `link` (string, required): The link they used; "" with none.
- `meeting` (boolean, required): The buyer asked for the account's team.
- `qualified` (boolean, required)
- `reason` (string, required): `why` in words, in English.
- `seconds` (integer, required): The conversation that counts: calls that held, and typing.
- `silent` (integer, required): Seconds of calls that timed out with nothing heard: never counted.
- `talked` (boolean, required)
- `typed` (integer, required): Of `seconds`, typed.
- `unended` (integer, required): Calls with no ending on record, counted by their length.
- `why` ("demo" | "booked" | "test" | "our_side" | "timed_out" | "short" | "none" | "corrected", required): The one reason it counts or not. `demo`: two minutes or more. `booked`: under two minutes, and the buyer booked a meeting.

<a id="record-billingmonth"></a>

### BillingMonth

One month of the plan, and how it stands.

- `carried` (integer, required): Demos left by the month before; in month 1, brought in with the plan.
- `current` (boolean, required): Today (Eastern Time) is one of its days.
- `first` (string (date), required)
- `included` (integer, required): The plan's demos a month.
- `last` (string (date), required)
- `left` (integer, required): included + carried - used. Below zero: demos over the plan.
- `n` (integer, required): 1 is the plan's first month.
- `used` (integer, required): Demos counted in its days so far.

<a id="record-billingplan"></a>

### BillingPlan

The account's plan: demos a month from a first day, and its counter. A month runs from the plan's day of the month to the day before it in the next, in Eastern Time. What a month leaves is added to the next; a month that ends over its plan takes nothing from it.

- `carried` (integer, required): Demos brought in from an earlier plan, added to month 1.
- `counter` ([BillingMonth](#record-billingmonth)[], required): Every month that has begun, oldest first.
- `demos` (integer, required): Demos a month.
- `first` (string (date), required): The day month 1 begins.
- `last` (string (date) | null, required): Its last day; null with no end.
- `months` (integer | null, required): How many months it runs; null: no end.
- `standing` ("not_started" | "running" | "ended", required)
- `uncounted_before` (string (date) | null): Days before this one that are not final are not in the counter yet. Null: none.

<a id="record-brieflink"></a>

### BriefLink

The link to the buyer's brief that opens without a console account, to a work email at the account proven by a code, when a hand-off sent one.

- `ended_at` (string | null)
- `ended_by` (string | null)
- `made` (integer, required): Links made for this demo's brief.
- `open` (boolean, required): One still opens: none ended since.
- `opens` ([BriefOpen](#record-briefopen)[], required)

<a id="record-brieflinkendin"></a>

### BriefLinkEndIn

End every link a demo's brief went out with. The next hand-off makes a new one.

- `demo` (string, required): Up to 120 characters.

<a id="record-brieflinkmade"></a>

### BriefLinkMade

A new link to a demo's brief that opens without a console account, for the team to send a rep by hand. It opens to whoever proves a work email at the account (or at Solacia) with a code sent there, until it ends or the team ends it on Handoff.

- `ends_at` (string, required): When it stops opening, ISO 8601.
- `url` (string, required)

<a id="record-briefopen"></a>

### BriefOpen

One read of a brief link: when, by whom, and roughly where, as the host saw it.

- `at` (string, required)
- `city` (string | null)
- `country` (string | null)
- `played` (boolean): The call's recording started playing, rather than the brief being read. Default `false`.
- `reader` (string | null): The work email the reader proved with a code sent to it.
- `region` (string | null)
- `visitor` (string | null): The reader's address and browser, hashed: the same reader reads the same.

<a id="record-buyer"></a>

### Buyer

One row of the console's Buyers list, one per buyer (their demos joined by work email): who they are, three facts, their main question and where it stands. In preview.

- `action` ("book" | "prep" | "follow_up" | null): What a seller does next: book the call they asked for, prep the call they booked, or send the follow-up; empty when there is no way to reach them. In preview.
- `agent` (string | null, required)
- `asked` ([BuyerAsked](#record-buyerasked) | null, required)
- `audience` ("buyer" | "vendor" | "made_up" | "test" | "staff" | "try" | "rehearsal"): Who the demo is for. buyer: someone the vendor could sell to. vendor: a prospect's own people on a link Solacia made. made_up: a made-up buyer on dev. test: an address at the vendor's or Solacia's domain. staff: opened by Solacia's team. try: opened by a try link. rehearsal: the team rehearsing an agent. `test` is true for test, staff, try and rehearsal. Default `"buyer"`.
- `calls` (integer, required): Voice calls with the agent.
- `company` (string | null, required)
- `crm` (boolean, required)
- `demos` (integer, required): Their demos in all; 2 or more means they came back.
- `done` (boolean): The action is done: a teammate marked it, or the call they booked has begun. A new demo or a new action brings it back. In preview. Default `false`.
- `door` (string | null, required)
- `email` (string | null, required)
- `facts` (string[], required): Three things about their business.
- `first_at` (string, required)
- `fit` (string, required)
- `follow_up` (boolean, required)
- `found` ([BuyerFound](#record-buyerfound) | null): With `q`: what it met in what they said; empty when their name met it.
- `id` (string, required): Their newest demo with their email (their newest, when none has it).
- `label` (string, required): The outcome in words.
- `last_at` (string, required)
- `logo` (string | null): Their company's logo (Brandfetch's CDN), linked, never copied. In preview.
- `minutes` (number, required): Active minutes in the demo.
- `name` (string | null, required): The person, when their link's brief or their email names them.
- `number` (integer | null, required)
- `outcome` ("meeting" | "qualified" | "nurture" | "anonymous", required)
- `qualified` (boolean, required)
- `questions` (integer, required)
- `reach` (integer, required): How far the demo went: opened, saw, asked, talked, asked to meet. 1 to 5.
- `role` (string | null, required)
- `score` (integer, required): Orders buyers within an outcome: higher is more promising.
- `seen` (integer, required): The parts of the product they saw.
- `sessions` (string[], required): Their demos in the period: `id` first, then the rest newest first. Demos share a work email, or ran in the same browser before they gave one.
- `size` (string, required): Enterprise, Mid-market, SMB, or empty when unknown.
- `slot` (string | null, required): The meeting time the buyer picked.
- `test` (boolean, required)
- `unanswered` (integer, required)

<a id="record-buyerasked"></a>

### BuyerAsked

- `answered` ("yes" | "partly" | "no", required)
- `text` (string, required): Their main question, in their own words.

<a id="record-buyerdone"></a>

### BuyerDone

- `action` ("book" | "prep" | "follow_up", required)
- `done` (boolean, required)
- `id` (string, required)

<a id="record-buyerdonein"></a>

### BuyerDoneIn

A teammate marks the one thing to do for a buyer done, or takes the mark back.

- `action` ("book" | "prep" | "follow_up", required): The action they did, as the row gave it.
- `done` (boolean): False takes the mark back (Undo). Default `true`.

<a id="record-buyerfound"></a>

### BuyerFound

Where a search met the buyer: what they said (or a fact the demo learned), cut around the words, with where each word sits.

- `at` (string | null, required): When they said it; empty for a fact.
- `demo` (string, required): The demo they said it in.
- `marks` (integer[][], required): [start, end) of each matched word in `text`.
- `text` (string, required)
- `where` ("call" | "chat" | "tapped" | "fact", required): Said on a call, written in the chat, a suggested question they tapped, or a fact.

<a id="record-buyers"></a>

### Buyers

- `buyers` ([Buyer](#record-buyer)[], required)
- `days` (integer, required)
- `hidden_tests` (integer, required): Test demos left out; ask with tests=true to see them.
- `next_cursor` (string | null): Pass it as `cursor` for the buyers after these; empty on the last page.
- `total` (integer): Buyers that matched, over every page. Default `0`.

<a id="record-call"></a>

### Call

- `ended` (string | null, required): goodbye, left, idle, limit, timeout, error; null when unknown.
- `minutes` (number, required)
- `model` (string | null): Always null. Kept so v1 answers stay the same shape.
- `started_at` (string, required)
- `voice` (string | null): Always null. Kept so v1 answers stay the same shape.

<a id="record-callasked"></a>

### CallAsked

- `answer` (string, required): The rep's answer, true for every buyer.
- `question` (string, required)
- `said` (string, required): The rep's own sentence, from the transcript.

<a id="record-callmove"></a>

### CallMove

- `move` (string, required)
- `said` (string, required)

<a id="record-callobjection"></a>

### CallObjection

- `handling` (string, required)
- `objection` (string, required)
- `said` (string, required)

<a id="record-callpicksin"></a>

### CallPicksIn

- `picked` (string[], required): The refs of the folders or spaces picked.

<a id="record-callplace"></a>

### CallPlace

A Granola folder or space, or a Fathom team or meeting type, that may hold the vendor's sales calls.

- `kind` (string, required): folder or space (Granola); team, meeting_type or every (Fathom)
- `name` (string, required)
- `ref` (string, required): kind:id, as picked.

<a id="record-callplaces"></a>

### CallPlaces

The folders and spaces the key reaches, and those picked.

- `picked` (string[]): The refs picked.
- `places` ([CallPlace](#record-callplace)[], required)

<a id="record-campaignresult"></a>

### CampaignResult

What one campaign's links have brought so far.

- `campaign` (string, required): Empty for links made without one.
- `links` (integer, required)
- `opened` (integer, required): Links whose prospect ran at least one demo.
- `qualified` (integer, required): Prospects whose hottest demo is hot or warm.
- `team_requests` (integer, required): Prospects who asked to talk to your team.

<a id="record-channelpace"></a>

### ChannelPace

- `crm` ([CrmPace](#record-crmpace) | null): Outreach only: the same for a test against no demo, whose meetings come from the CRM
- `demos` (integer, required): Demos the channel labelled in the last 30 days, test demos left out
- `meetings` (integer, required)
- `per_side` (integer, required): Buyers each side of a test needs to see that rate rise by half
- `per_side_double` (integer, required): Buyers each side needs to see it double
- `per_week` (number, required)
- `rate` (number, required): The channel's meeting rate; 10% until it has 20 demos of its own

<a id="record-chapterout"></a>

### ChapterOut

- `at` (string, required): When the chapter's first line was said, ISO 8601, on the transcript's clock.
- `title` (string, required): Its name, a few words.

<a id="record-chapters"></a>

### Chapters

A recorded call's parts, in order, each named; empty when the call has none to show. Named once per recording and language. In preview.

- `chapters` ([ChapterOut](#record-chapterout)[], required)

<a id="record-chatbotconnection"></a>

### ChatbotConnection

A chatbot (Claude, ChatGPT, any MCP client) a person connected to this account by OAuth. It acts as that person, with no more than they allowed and their role allows.

- `at` (string, required): When it was connected, ISO 8601.
- `by` (string, required): The email of the person who connected it.
- `calls_30d` (integer): The calls it made in the last 30 days, refused ones included. Default `0`.
- `client` (string, required): The chatbot's name, as it gave it.
- `daily_calls` (integer[]): Its calls on each of the last 30 days (UTC), oldest first; the last is today.
- `ended_at` (string): When it stopped working, ISO 8601; empty while it works.
- `ended_by` (string): Who revoked it.
- `ended_why` ("" | "revoked" | "leaked" | "reused" | "signed_out" | "expired"): Why it stopped: `revoked` by a person, `leaked` (its token found in public), `reused` (a spent token came back, so it may be stolen), `signed_out` (its person signed out everywhere, changed their password or left), or `expired` (unused for 90 days).
- `id` (string, required): The connection's id. Revoke it by this.
- `last_used_at` (string | null): When it last made a call, ISO 8601; null: never.
- `scopes` (string[], required): What the person allowed it.
- `state` ("active" | "ended"): Whether it still works. Default `"active"`.
- `yours` (boolean): Connected by the person making this call. Default `false`.

<a id="record-chatbotconnections"></a>

### ChatbotConnections

The chatbots connected to this account, newest first, and the latest that stopped. An owner sees everyone's; anyone else sees their own.

- `connections` ([ChatbotConnection](#record-chatbotconnection)[], required)
- `ended` ([ChatbotConnection](#record-chatbotconnection)[]): Connections that stopped working, the latest 50, newest first.

<a id="record-chilipiperin"></a>

### ChiliPiperIn

Chili Piper, as its admin made it for Solacia: an Edge API token with Concierge permissions.

- `token` (string, required): Up to 2000 characters.

<a id="record-chilipiperrouter"></a>

### ChiliPiperRouter

A Concierge router: its id, the name the API routes by (`slug`), its name, and where each of its fields (Chili Piper's data fields) gets its value ("" for nothing; one of ChiliPiperRouters.sources). `listed_fields`: Chili Piper named its fields; false, they are its standard data fields (PersonEmail, ...).

- `defs` ([RouterField](#record-routerfield)[]): Each field's type and, for a dropdown, the values it takes.
- `fields` (object<string, string>, required)
- `id` (string, required)
- `labels` (object<string, string>): Each field's label in Chili Piper; a custom field's key is its UUID.
- `listed_fields` (boolean): Default `true`.
- `name` (string, required)
- `slug` (string, required)
- `trigger` ("" | "InAppButton" | "ThirdPartyForm" | "RouterLink"): How the router is told the buyer came, which its field keys fit; empty: an in-app button.

<a id="record-chilipiperrouterin"></a>

### ChiliPiperRouterIn

The router buyers go through (its slug, id or link) and where each of its fields gets its value (one of ChiliPiperRouters.sources, or "" for nothing); without `fields`, matched from their names and types.

- `fields` (object<string, string> | null)
- `router` (string, required): Up to 300 characters.

<a id="record-chilipiperrouters"></a>

### ChiliPiperRouters

The router buyers go through, and the token's routers to pick from. `listed` false: the token can't list routers, so the router is named by hand. `typed` false: the token can't read the data fields' types (Data fields: Read), so only the router's own form gives them.

- `chosen` ([ChiliPiperRouter](#record-chilipiperrouter) | null, required)
- `listed` (boolean, required)
- `routers` ([ChiliPiperRouter](#record-chilipiperrouter)[], required)
- `sources` ([FieldSource](#record-fieldsource)[])
- `typed` (boolean): Default `true`.

<a id="record-claykeymade"></a>

### ClayKeyMade

- `key` (boolean, required): Whether a Clay key is live.
- `key_at` (string): When it was made, ISO 8601.
- `key_by` (string): Who made the live key.
- `last_link_at` (string | null): When Clay last made one, ISO 8601; null before the first.
- `links` (integer, required): Prospects whose link Clay made.
- `path` (string, required): Where Clay's HTTP column sends each row, on this site: the account's own API, which passes a key straight to its engine.
- `secret` (string, required): The key, shown this once: Solacia keeps only its hash.

<a id="record-claystatus"></a>

### ClayStatus

Whether Clay can make links for this account, and what it has made: the console's proof that a Clay column is really connected.

- `key` (boolean, required): Whether a Clay key is live.
- `key_at` (string): When it was made, ISO 8601.
- `key_by` (string): Who made the live key.
- `last_link_at` (string | null): When Clay last made one, ISO 8601; null before the first.
- `links` (integer, required): Prospects whose link Clay made.
- `path` (string, required): Where Clay's HTTP column sends each row, on this site: the account's own API, which passes a key straight to its engine.

<a id="record-concern"></a>

### Concern

- `dealbreaker` (boolean, required)
- `text` (string, required)

<a id="record-contact"></a>

### Contact

- `company` (string | null, required): From the email's domain.
- `country` (string | null): Where their company is based (ISO 3166 code), when the buyer said it.
- `email` (string | null, required)
- `employees` (integer | null): How many people their company has: what the buyer said, else the company lookup's.
- `role` (string | null, required)

<a id="record-craftlinkin"></a>

### CraftLinkIn

A Craft API connection the vendor made for the documents the agent may answer from.

- `key` (string): The connection's API key, when it has one. Up to 500 characters.
- `url` (string, required): Up to 300 characters.

<a id="record-crmfield"></a>

### CrmField

One field of your CRM that Solacia may write (a Salesforce Lead field, a HubSpot contact property), as your CRM describes it.

- `choices` (string[], required): A closed list's active values, as your CRM spells them.
- `kind` ("list" | "text" | "boolean" | "date" | "datetime", required)
- `label` (string, required): What your team calls it.
- `length` (integer, required): The most characters it holds (text).
- `name` (string, required): Its API name (Salesforce) or internal name (HubSpot).

<a id="record-crmfields"></a>

### CrmFields

Your CRM's fields Solacia may write, by name, for a field map. In preview.

- `connected` (boolean, required): Your CRM is connected and answered; when not, the list is empty.
- `items` ([CrmField](#record-crmfield)[], required)
- `next_cursor` (string | null)
- `total` (integer, required)

<a id="record-crmlist"></a>

### CrmList

- `id` (string, required)
- `name` (string, required)
- `size` (integer, required): People on it (a campaign's contacts and leads), as the CRM last counted them.
- `updated` (string, required): When it last changed, ISO 8601, as the CRM says it.

<a id="record-crmlistlinks"></a>

### CrmListLinks

- `made` ([DemoLink](#record-demolink)[], required)
- `next` (string): Pass as `after` for the next page; empty after the last.
- `no_email` (integer): Contacts on this page without an email: no link. Default `0`.
- `no_field` (boolean): Salesforce: the org has no Solacia_Demo_Link__c URL field on Contact and Lead, so the links were made but not saved on the records. Default `false`.
- `refused` ([LinkRefused](#record-linkrefused)[])
- `refused_by_crm` (string): Why the CRM refused the write, in its words.
- `written` (boolean, required): Whether each link reached its record: HubSpot's Solacia demo link property, Salesforce's Solacia Demo Link field.

<a id="record-crmlistlinksin"></a>

### CrmListLinksIn

Personal links for one page of a CRM list's contacts, written back onto each contact.

- `after` (string): Where this page starts: the last answer's `next`. Up to 256 characters.
- `agent` (string | null): The agent they meet; left out: the sender's default.
- `campaign` (string): Up to 80 characters.
- `days` (integer): How long the links open the demo. 1 to 90. Default `30`.
- `list_id` (string, required): Up to 64 characters.

<a id="record-crmlists"></a>

### CrmLists

The lists in the account's CRM a send can start from: HubSpot's contact lists, Salesforce's campaigns.

- `connected` (boolean, required): Whether Solacia holds a connection to it.
- `crm` (string, required): The account's CRM (`hubspot`, `salesforce`), or empty when none is chosen.
- `lists` ([CrmList](#record-crmlist)[] | null, required): Its contact lists, most recently changed first; null when the CRM refused, such as a HubSpot connection made before Solacia asked to read lists.
- `refused` (string): Why the CRM refused, in its words.

<a id="record-crmpace"></a>

### CrmPace

- `per_side` (integer, required)
- `per_side_double` (integer, required)
- `rate` (number, required): The meeting rate assumed for cold outreach

<a id="record-deal"></a>

### Deal

A deal the buyer is on in the account's CRM, as the team keeps it there.

- `amount` (string, required): As the CRM holds it; empty when none.
- `closed_at` (string, required): When it was won or lost, ISO 8601; empty while open.
- `currency` (string, required)
- `id` (string, required)
- `name` (string, required)
- `stage` (string, required): Its stage, as the CRM names it.
- `state` ("open" | "won" | "lost", required)

<a id="record-deleted"></a>

### Deleted

- `deleted` (boolean, required)

<a id="record-demo"></a>

### Demo

One run of the demo, by one buyer, as the record shows it: when, how long, in what language, whether they left an email, what calls it had.

- `schema` (string): Default `"solacia.demo.v1"`.
- `audience` ("buyer" | "vendor" | "made_up" | "test" | "staff" | "try" | "rehearsal"): Who the demo is for. buyer: someone the vendor could sell to. vendor: a prospect's own people on a link Solacia made. made_up: a made-up buyer on dev. test: an address at the vendor's or Solacia's domain. staff: opened by Solacia's team. try: opened by a try link. rehearsal: the team rehearsing an agent. `test` is true for test, staff, try and rehearsal. Default `"buyer"`.
- `calls` ([Call](#record-call)[], required)
- `contact` (boolean, required): Whether the buyer left an email; the lead has it.
- `first_at` (string, required)
- `id` (string, required)
- `language` (string | null, required)
- `last_at` (string, required)
- `minutes` (number, required)
- `number` (integer | null, required)
- `priority` ("hot" | "warm" | "nurture" | "cold", required)
- `product` (string, required)
- `stages` (string[], required)
- `test` (boolean, required)
- `turns` (integer, required): What the buyer typed or said, as turns.

<a id="record-demolink"></a>

### DemoLink

A personal link: it opens the demo without the password and records the demo under the prospect's email. With what the prospect has done since it was made.

- `agent` (string | null): The agent the link was made with; null: the outbound channel's.
- `anonymous` (boolean): Default `false`.
- `campaign` (string)
- `company` (string, required)
- `demos` (integer): Demos the prospect ran since the link was made. Default `0`.
- `email` (string, required)
- `expires_at` (string, required): ISO 8601, UTC.
- `last_demo_at` (string | null): ISO 8601; null before a demo.
- `made_at` (string, required): ISO 8601.
- `made_by` (string, required)
- `name` (string, required)
- `notes` (string, required)
- `priority` ("hot" | "warm" | "nurture" | "cold" | null): The hottest of those demos; null before one.
- `role` (string, required)
- `sent_to` (string)
- `team_requested` (boolean): They asked to talk to your team in one of them. Default `false`.
- `test` (string | null): The outreach test that sorted them when the link was made.
- `try_out` (boolean): A try link, kept for your team to try the demo. Default `false`.
- `url` (string, required): The link to send; empty when the site cannot sign links.
- `with_demo` (boolean): False while an outreach test puts this prospect on its side with no demo: send them the same email without the demo link. `url` is then empty. Default `true`.

<a id="record-demolinkin"></a>

### DemoLinkIn

A personal demo link for one prospect, and who they are. Everything but the email is optional; what is given, the agent reads before the call. An anonymous link needs no email and names nobody.

- `agent` (string | null): The agent the prospect meets: its id. Left out: the sender's default agent, else the outbound channel's.
- `anonymous` (boolean): A link for someone unnamed: its demos are filed under an address made up for it, and a buyer who asks for your team gives their own email. Default `false`.
- `campaign` (string): The list, segment or sequence the link goes out in, such as CFOs Mexico Q4. Your team's label: the agent never sees it; the lead record carries it. Up to 80 characters.
- `company` (string): Up to 80 characters.
- `days` (integer): How long the link opens the demo. 1 to 90. Default `30`.
- `email` (string): The prospect's work email; none for an anonymous link. Up to 254 characters.
- `name` (string): Their name, to greet them by. Up to 80 characters.
- `notes` (string): What the rep knows that should shape the demo. The agent checks it with the buyer before relying on it and never quotes it. Up to 600 characters.
- `role` (string): Their job, such as CFO. Up to 80 characters.
- `sent_to` (string): Who you sent the link to: a company, a person or both. Your team's label: the agent never sees it. Up to 80 characters.
- `try_out` (boolean): A try link, Solacia's team only: one we keep to try the demo ourselves, never sent to a buyer. Its demos never post to Slack or reach the CRM. Anyone else is refused. Default `false`.

<a id="record-demolinks"></a>

### DemoLinks

The links made from the console or the API, newest first, one per prospect, and what each campaign has brought.

- `campaigns` ([CampaignResult](#record-campaignresult)[]): One row per campaign over every link, most links first.
- `links` ([DemoLink](#record-demolink)[], required)
- `next_cursor` (string | null): Pass it as `cursor` for the links after these; empty on the last page.
- `total` (integer): Links that matched, over every page. Default `0`.

<a id="record-demolinksin"></a>

### DemoLinksIn

Personal demo links for a list of prospects, made in one request: a file a rep dropped, or a sequence's export. Each row is one prospect, as for a single link.

- `rows` ([DemoLinkIn](#record-demolinkin)[], required): Up to 500 prospects.

<a id="record-demolinksmade"></a>

### DemoLinksMade

What a batch made: a link per prospect, in the order given, and the rows refused.

- `made` ([DemoLink](#record-demolink)[], required)
- `refused` ([LinkRefused](#record-linkrefused)[])

<a id="record-demopage"></a>

### DemoPage

- `items` ([Demo](#record-demo)[], required)
- `next_cursor` (string | null, required)
- `total` (integer): Demos that matched, over every page. Default `0`.

<a id="record-demotheme"></a>

### DemoTheme

The colours the demo wears now (`colours`), and the product's own (`default`), which a reset goes back to.

- `colours` ([ThemeColours](#record-themecolours), required)
- `custom` (boolean, required): Whether the team picked these, rather than the product's own
- `default` ([ThemeColours](#record-themecolours), required)

<a id="record-dictation"></a>

### Dictation

- `text` (string, required): What was said, punctuated; empty when nothing was heard

<a id="record-dictationin"></a>

### DictationIn

A recording of someone saying an answer, base64, as the browser recorded it.

- `audio` (string, required): The recording, base64, up to 3 MB Up to 4200000 characters.
- `type` (string): Up to 100 characters. Default `"audio/webm"`.

<a id="record-disputeside"></a>

### DisputeSide

Where one side of a dispute says it: the section of an internal document, or a public docs page.

- `document` (string): The internal document's title; empty for a public page.
- `says` (string, required): Its sentence that states it, as written there.
- `title` (string, required): The internal section's heading, or the public page's title.
- `url` (string): The public page's address; empty for an internal document.

<a id="record-docsdispute"></a>

### DocsDispute

A fact an internal document and the public docs state two ways.

- `internal` ([DisputeSide](#record-disputeside), required)
- `public` ([DisputeSide](#record-disputeside), required)
- `what` (string, required)

<a id="record-docsdisputes"></a>

### DocsDisputes

The side the agent follows, what is in dispute, and how many internal documents are still to be checked against the public docs (POST /internal-docs/check until 0).

- `disputes` ([DocsDispute](#record-docsdispute)[])
- `prefer` ("internal" | "public", required)
- `unchecked` (integer): Default `0`.

<a id="record-docslive"></a>

### DocsLive

- `at` (string, required): When it was made live, ISO 8601.
- `by` (string, required): Who made it live.
- `version` (string, required): The id of the version the agent answers from.
- `why` (string)

<a id="record-docslivein"></a>

### DocsLiveIn

- `version` (string, required): The id of a kept version. Up to 64 characters.
- `why` (string): Why: shown with the version. Up to 300 characters.

<a id="record-docsversion"></a>

### DocsVersion

The vendor's docs as fetched once and kept: the pages the agent can answer from.

- `at` (string): When it was published, ISO 8601.
- `by` (string): Who or what published it: the weekly docs check, or a person.
- `fetched` (string, required): The day its pages were fetched, YYYY-MM-DD.
- `id` (string, required): The version's id: the same pages with the same text are the same version.
- `pages` (integer, required)

<a id="record-docsversions"></a>

### DocsVersions

Which docs version the agent answers from, and the latest ones kept, newest first.

- `live` ([DocsLive](#record-docslive) | null, required): None until a version is published: the release's own copy answers.
- `versions` ([DocsVersion](#record-docsversion)[], required)

<a id="record-embed"></a>

### Embed

One key that puts the demo on the vendor's own site. The key is public: it sits in the page.

- `calls_per_day` (integer | null): Voice calls a day it allows; null: no own limit.
- `key` (string, required)
- `paused` (boolean, required): Paused: the site shows no demo until Solacia resumes it.
- `sites` (string[], required): The origins it answers on, such as https://www.acme.com; empty: any.
- `snippet` (string, required): The script tag to paste into the site's HTML, before </body>.

<a id="record-embeds"></a>

### Embeds

The account's website embeds. Solacia makes the keys and their sites; none until it has.

- `embeds` ([Embed](#record-embed)[], required)

<a id="record-eventtype"></a>

### EventType

One of the connected scheduler's event types (Calendly).

- `id` (string, required): The event type's id in the scheduler
- `kind` (string): round robin, group, or empty for one person
- `minutes` (integer): Default `0`.
- `name` (string, required)
- `url` (string, required): Its booking page

<a id="record-eventtypein"></a>

### EventTypeIn

The event buyers book: one the connected scheduler lists.

- `id` (string, required): Up to 500 characters.

<a id="record-eventtypes"></a>

### EventTypes

The event buyers book through a connected scheduler (`chosen`, none until one is picked) and the event types it offers.

- `chosen` ([EventType](#record-eventtype) | null, required)
- `events` ([EventType](#record-eventtype)[], required)

<a id="record-fathomkeyin"></a>

### FathomKeyIn

A Fathom user's API key: an admin's who can view all shared calls reaches the whole team.

- `key` (string, required): The key, as Fathom showed it. Up to 500 characters.

<a id="record-fieldmap"></a>

### FieldMap

Which of your own CRM fields get where each buyer came from, in the map's order. In preview.

- `at` (string | null)
- `by` (string | null)
- `checked` (boolean, required): The rows were checked against your CRM (it is connected and answered).
- `crm` ("salesforce" | "hubspot", required)
- `items` ([FieldMapItem](#record-fieldmapitem)[], required)
- `last` ([FieldMapLast](#record-fieldmaplast) | null): What the map wrote on the last lead, when one was sent: a real buyer's values, so only for a caller who may read leads (leads:read).
- `next_cursor` (string | null)
- `total` (integer, required)

<a id="record-fieldmapanswer"></a>

### FieldMapAnswer

- `answer` (string, required): Up to 2000 characters.
- `question` (string, required): Up to 1000 characters.

<a id="record-fieldmapdraft"></a>

### FieldMapDraft

A field map drafted from your document, not saved: each row checked against your CRM when it is connected, the rows left out and why, and what the document leaves open. Save it with PUT /integrations/{crm}/field-map once a person has read it. In preview.

- `checked` (boolean, required): The rows were checked against your CRM (it is connected and answered).
- `crm` ("salesforce" | "hubspot", required)
- `items` ([FieldMapDraftItem](#record-fieldmapdraftitem)[], required)
- `left_out` (string[], required): Rows the draft had that a map can't hold, each with why.
- `next_cursor` (string | null)
- `questions` (string[], required): What the document leaves open, for the person who saves the map.
- `total` (integer, required)

<a id="record-fieldmapdraftin"></a>

### FieldMapDraftIn

Your account of your CRM process, to draft your field map from: the file itself (`content`, base64) or its `text`.

- `answers` ([FieldMapAnswer](#record-fieldmapanswer)[]): Your answers to the draft's questions.
- `content` (string): The file, base64: .pdf, .docx, .html, .md or .txt, up to 3 MB Up to 4200000 characters.
- `language` ("en" | "es" | "pt"): The language the questions are written in. Default `"en"`.
- `name` (string, required): Up to 200 characters.
- `rows` ([FieldMapRow](#record-fieldmaprow)[]): The draft as you edited it, to change only where your answers do.
- `text` (string): Or its text, instead of the file Up to 200000 characters.

<a id="record-fieldmapdraftitem"></a>

### FieldMapDraftItem

One drafted row, with the document's words it rests on.

- `basis` (string): The document's words the row rests on.
- `booked` (string | null)
- `field` (string, required): The field's API name. Up to 80 characters.
- `fixed` (string | null)
- `follows` (string | null): Another row's field: this one is written only together with that row, on a new lead or when that row moves the lead on.
- `found` (boolean | null): Your CRM has the field and lets Solacia write it; null when it was not checked.
- `missing` (string[]): Labels the row sends that your closed list lacks.
- `moves_from` (string[]): On a lead your team already has: the values this row may replace. Any other value is never touched. Left out, a row with `fixed` and another value moves on from `fixed` only.
- `object` ("Lead"): Default `"Lead"`.
- `swap` (object<string, string>): Text in the value and what replaces it, such as underscores for spaces.
- `take` (string | null): utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, an ad click id (gclid, msclkid, fbclid, oppref, ...), fbc (Meta's click id as fb.1.<ms>.<fbclid>), arrival_url (the page that brought the buyer, with its tags), demo_page, referrer_url or meeting_at (when the meeting they booked starts); or how the demo went: priority (Hot, Warm, Nurture, Cold), fit, brief (its link), last_demo (the day), asked_meeting (true or false). Ad click ids are sent whole or not at all.
- `values` (object<string, string>): For a closed list: each tag value (any case) and the label it reads as. A value not here leaves the field empty.
- `when` (object<string, string>): A value for each outcome of the demo; of those that apply, the strongest wins (booked, asked_meeting, hot, warm, nurture, cold), else `any`. `fixed` is `any`'s value and `booked` is booked's.

<a id="record-fieldmapin"></a>

### FieldMapIn

The whole map, replacing the one before. Empty: Solacia fills none of your own fields.

- `rows` ([FieldMapRow](#record-fieldmaprow)[], required)

<a id="record-fieldmapitem"></a>

### FieldMapItem

One row of the map, with how it stands against your CRM now.

- `booked` (string | null)
- `field` (string, required): The field's API name. Up to 80 characters.
- `fixed` (string | null)
- `follows` (string | null): Another row's field: this one is written only together with that row, on a new lead or when that row moves the lead on.
- `found` (boolean | null): Your CRM has the field and lets Solacia write it; null when it was not checked.
- `missing` (string[]): Labels the row sends that your closed list lacks.
- `moves_from` (string[]): On a lead your team already has: the values this row may replace. Any other value is never touched. Left out, a row with `fixed` and another value moves on from `fixed` only.
- `object` ("Lead"): Default `"Lead"`.
- `swap` (object<string, string>): Text in the value and what replaces it, such as underscores for spaces.
- `take` (string | null): utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, an ad click id (gclid, msclkid, fbclid, oppref, ...), fbc (Meta's click id as fb.1.<ms>.<fbclid>), arrival_url (the page that brought the buyer, with its tags), demo_page, referrer_url or meeting_at (when the meeting they booked starts); or how the demo went: priority (Hot, Warm, Nurture, Cold), fit, brief (its link), last_demo (the day), asked_meeting (true or false). Ad click ids are sent whole or not at all.
- `values` (object<string, string>): For a closed list: each tag value (any case) and the label it reads as. A value not here leaves the field empty.
- `when` (object<string, string>): A value for each outcome of the demo; of those that apply, the strongest wins (booked, asked_meeting, hot, warm, nurture, cold), else `any`. `fixed` is `any`'s value and `booked` is booked's.

<a id="record-fieldmaplast"></a>

### FieldMapLast

What the map wrote on the last lead Solacia sent your CRM: the map's proof.

- `at` (string, required)
- `dropped` (string[]): The map's fields your CRM refused; the lead was written without them.
- `fields` (object<string, string | boolean>, required): Each field the map wrote, by API name, with its value.
- `new` (boolean, required): A lead Solacia made; false: one your team already had, which gets only its empty fields.
- `refused` (string): Your CRM refused some of the map's fields, in its words.

<a id="record-fieldmappreview"></a>

### FieldMapPreview

What a new lead from that buyer would get in each of your own fields. Nothing is written.

- `checked` (boolean, required): Checked against your CRM's own fields (it is connected and answered).
- `items` ([FieldMapPreviewLine](#record-fieldmappreviewline)[], required)
- `next_cursor` (string | null)
- `total` (integer, required)

<a id="record-fieldmappreviewin"></a>

### FieldMapPreviewIn

A link a buyer opens, to see what your saved map would send for them.

- `meeting` ("none" | "asked" | "booked"): Whether the buyer asked for a meeting in the demo, or booked one. Default `"none"`.
- `page` (string, required): The page the buyer opens, with its tags. Up to 2000 characters.
- `priority` ("hot" | "warm" | "nurture" | "cold" | null): How Solacia rated the buyer after the demo.
- `referrer` (string | null): The site that sent them.
- `rows` ([FieldMapRow](#record-fieldmaprow)[] | null): A map to preview instead of the saved one, such as a draft before it is saved.

<a id="record-fieldmappreviewline"></a>

### FieldMapPreviewLine

One row of the map for that buyer: what it would send, or why the field stays empty.

- `field` (string, required)
- `given` (string, required): The value before your CRM's field had its say; empty when there was none.
- `status` ("sent" | "no_value" | "not_in_table" | "not_in_list" | "no_field" | "too_long" | "unfit" | "on_booking" | "other_outcome" | "follows", required): sent; or why it stays empty: no_value (the visit had no such tag), not_in_table (the row's labels lack the value), not_in_list (your CRM's list lacks the label), no_field (your CRM has no such field we may write), too_long (an ad click id longer than the field, never cut), unfit (not a yes/no or a date), on_booking (only once the buyer books), other_outcome (a value only for other outcomes of the demo), follows (written only with the row it follows, which stays empty).
- `value` (string | boolean | null, required): What a new lead gets in the field; null when it stays empty.

<a id="record-fieldmaprow"></a>

### FieldMapRow

One of your CRM's fields and what Solacia puts in it: one of its values (`take`), or a fixed value (`fixed`, with `booked` in its place once the buyer books a meeting). A lead your team already has gets only its empty fields, except a step up from `fixed` to `booked`; a row that `follows` that row is written with the step up and only with it.

- `booked` (string | null)
- `field` (string, required): The field's API name. Up to 80 characters.
- `fixed` (string | null)
- `follows` (string | null): Another row's field: this one is written only together with that row, on a new lead or when that row moves the lead on.
- `moves_from` (string[]): On a lead your team already has: the values this row may replace. Any other value is never touched. Left out, a row with `fixed` and another value moves on from `fixed` only.
- `object` ("Lead"): Default `"Lead"`.
- `swap` (object<string, string>): Text in the value and what replaces it, such as underscores for spaces.
- `take` (string | null): utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, an ad click id (gclid, msclkid, fbclid, oppref, ...), fbc (Meta's click id as fb.1.<ms>.<fbclid>), arrival_url (the page that brought the buyer, with its tags), demo_page, referrer_url or meeting_at (when the meeting they booked starts); or how the demo went: priority (Hot, Warm, Nurture, Cold), fit, brief (its link), last_demo (the day), asked_meeting (true or false). Ad click ids are sent whole or not at all.
- `values` (object<string, string>): For a closed list: each tag value (any case) and the label it reads as. A value not here leaves the field empty.
- `when` (object<string, string>): A value for each outcome of the demo; of those that apply, the strongest wins (booked, asked_meeting, hot, warm, nurture, cold), else `any`. `fixed` is `any`'s value and `booked` is booked's.

<a id="record-fieldsource"></a>

### FieldSource

Where a router's field can get its value: the buyer's contact, a fact the call gathers, or the call read for that field ("call").

- `label` (string, required)
- `value` (string, required)

<a id="record-flow"></a>

### Flow

Where every buyer of the last `days` days went: each way a demo can go (every way is listed, with 0 when nobody went it), each demo with its way, newest first, the agents and doors of the period with their counts (before those filters narrow it), and the test demos. In preview.

- `agents` ([FlowAgent](#record-flowagent)[], required)
- `days` (integer, required)
- `demos` ([FlowDemo](#record-flowdemo)[], required)
- `doors` ([FlowDoor](#record-flowdoor)[], required)
- `end` (string (date), required)
- `paths` ([FlowWay](#record-flowway)[], required)
- `start` (string (date), required)
- `tests` ([FlowTests](#record-flowtests), required)
- `unopened` ([FlowClick](#record-flowclick)[]): Clicks on the website's demo button whose demo never appeared, counted in the way opened → left before seeing it; none when an agent filter is set, since no agent ran.

<a id="record-flowagent"></a>

### FlowAgent

- `demos` (integer, required)
- `name` (string, required)

<a id="record-flowclick"></a>

### FlowClick

A click on the website's demo button whose demo never appeared: the buyer left before seeing the product, most likely while it loaded (domain/metrics.py unopened).

- `at` (string, required): When they clicked, ISO 8601.
- `door` (string, required)

<a id="record-flowdemo"></a>

### FlowDemo

One demo in the flow: the way it went and who it was.

- `agent` (string | null, required)
- `calls` (integer, required)
- `company` (string | null, required)
- `door` (string | null, required)
- `email` (string | null, required)
- `id` (string, required)
- `last` (string, required)
- `minutes` (number, required)
- `outcome` (string, required)
- `priority` (string, required)
- `questions` (integer, required)
- `role` (string | null, required)
- `started` (string, required)
- `steps` (string[], required)
- `test` (boolean): One of our own test demos (counted only with `tests`). Default `false`.

<a id="record-flowdoor"></a>

### FlowDoor

A door demos were opened through in the period, and how many.

- `demos` (integer, required)
- `id` (string, required)

<a id="record-flowtests"></a>

### FlowTests

- `count` (integer, required): Test demos in the period, counted or not.
- `included` (boolean, required)

<a id="record-flowway"></a>

### FlowWay

One way a demo can go, from opening it to where the buyer is now, and how many went it.

- `n` (integer, required)
- `steps` (string[], required)

<a id="record-followup"></a>

### FollowUp

- `body` (string | null, required)
- `subject` (string | null, required)

<a id="record-followupdraft"></a>

### FollowUpDraft

The demo's follow-up email as it now stands. In preview.

- `at` (string, required)
- `body` (string, required)
- `edited_by` (string | null): Who edited it last; none when it is as drafted.
- `language` (string, required)
- `subject` (string, required)

<a id="record-followupin"></a>

### FollowUpIn

The follow-up email as a teammate edited it.

- `body` (string, required): Up to 10000 characters.
- `subject` (string, required): Up to 300 characters.

<a id="record-foundation"></a>

### Foundation

What the account's customers say, quote by quote, graded by who said it, and what nobody has said yet. The ground every demo script is written from.

- `claims` ([FoundationClaim](#record-foundationclaim)[], required): Strongest and widest first
- `codes` ([FoundationCodeOut](#record-foundationcodeout)[], required)
- `gaps` (string[], required): What no customer has told us yet
- `kinds` ([FoundationKindOut](#record-foundationkindout)[], required)
- `people` (integer, required): Customers and buyers heard, each once
- `sources` ([FoundationSourceOut](#record-foundationsourceout)[], required)
- `vendor` (string, required)
- `voices` ([FoundationVoices](#record-foundationvoices), required): Sources by whose words they carry

<a id="record-foundationadded"></a>

### FoundationAdded

- `foundation` ([Foundation](#record-foundation), required)
- `read` ([FoundationRead](#record-foundationread) | null, required): The first part's read; none when it was read before

<a id="record-foundationclaim"></a>

### FoundationClaim

- `by` (string, required)
- `code` ("alternative" | "pain" | "outcome" | "capability" | "proof" | "anxiety" | "habit" | "loss", required)
- `id` (string, required)
- `measured` (boolean, required): A quote behind it carries a number
- `quotes` ([FoundationQuote](#record-foundationquote)[], required)
- `reach` (integer, required): Customers and buyers behind it, each once
- `roles` (string[], required)
- `sayable` (boolean, required): A public source backs it, so buyers may hear it
- `strength` ("many" | "one" | "vendor" | "ours", required): Several customers or buyers; one; only the vendor's published material; only our reading
- `text` (string, required)

<a id="record-foundationclaimin"></a>

### FoundationClaimIn

- `gone` (boolean): Drop it Default `false`.
- `into` (string | null): Fold it into this claim: its quotes count there
- `text` (string | null): Its new wording

<a id="record-foundationcodeout"></a>

### FoundationCodeOut

- `id` ("alternative" | "pain" | "outcome" | "capability" | "proof" | "anxiety" | "habit" | "loss", required)
- `means` (string, required)
- `missing` (string, required): What the gap is called while no customer has said it
- `title` (string, required)

<a id="record-foundationkindout"></a>

### FoundationKindOut

- `id` ("won_call" | "lost_call" | "interview" | "crm_note" | "ticket" | "review" | "usage" | "case_study" | "vendor_page" | "our_note", required)
- `label` (string, required)
- `public` (boolean, required): Quotable to buyers unless the team says otherwise
- `voice` ("customer" | "buyer" | "vendor" | "ours", required): Whose words it carries

<a id="record-foundationquote"></a>

### FoundationQuote

- `customer` (string, required)
- `date` (string, required)
- `id` (string, required)
- `kind` ("won_call" | "lost_call" | "interview" | "crm_note" | "ticket" | "review" | "usage" | "case_study" | "vendor_page" | "our_note", required)
- `role` (string, required)
- `source` (string, required)
- `title` (string, required)
- `words` (string, required): The source's own words, cut from it exactly

<a id="record-foundationread"></a>

### FoundationRead

- `dropped` (string[], required): What the model cut that was not the source's own words, and why
- `kept` (integer, required): Quotes kept from this part
- `left` (integer[], required)
- `new_claims` (integer, required)
- `part` (integer, required)
- `parts` (integer, required)
- `source` (string, required)

<a id="record-foundationreadin"></a>

### FoundationReadIn

- `part` (integer, required): 0 to 100.

<a id="record-foundationsourcein"></a>

### FoundationSourceIn

Raw evidence: a call's transcript, an interview, a CRM note, a ticket, a review, usage data, or the vendor's own page. Kept whole; the first part is read at once.

- `customer` (string): Whose words: the company Up to 80 characters.
- `date` (string): YYYY-MM-DD Up to 10 characters.
- `kind` ("won_call" | "lost_call" | "interview" | "crm_note" | "ticket" | "review" | "usage" | "case_study" | "vendor_page" | "our_note", required)
- `public` (boolean | null): May be quoted to buyers; left out: by its kind
- `role` (string): Who spoke Up to 80 characters.
- `text` (string, required): Up to 200000 characters.
- `title` (string): Up to 120 characters.

<a id="record-foundationsourceout"></a>

### FoundationSourceOut

- `at` (string, required)
- `by` (string, required)
- `chars` (integer, required)
- `customer` (string, required): Whose words: a company; two sources from one count once
- `date` (string, required): When it happened, YYYY-MM-DD, or empty
- `id` (string, required)
- `kind` ("won_call" | "lost_call" | "interview" | "crm_note" | "ticket" | "review" | "usage" | "case_study" | "vendor_page" | "our_note", required)
- `kind_label` (string, required)
- `left` (integer[], required): Parts not read yet: read each with POST .../read
- `parts` (integer, required): The parts it is read in
- `public` (boolean, required)
- `quotes` (integer, required): Quotes kept from it
- `role` (string, required): Who spoke: finance lead, controller, the person who spends
- `title` (string, required)
- `voice` ("customer" | "buyer" | "vendor" | "ours", required)

<a id="record-foundationvoices"></a>

### FoundationVoices

- `buyer` (integer, required)
- `customer` (integer, required)
- `ours` (integer, required)
- `vendor` (integer, required)

<a id="record-gap"></a>

### Gap

A question the agent could not settle from the vendor's sources, counted across buyers; the team closes it once with an answer the agent then uses for everyone, or dismisses it.

- `schema` (string): Default `"solacia.gap.v1"`.
- `answer` (string, required)
- `answered_at` (string, required)
- `area` (string | null): The product area buyers' askings were routed to.
- `asked` (integer, required)
- `buyers` ([GapBuyer](#record-gapbuyer)[]): Who asked, newest first.
- `dismissed_at` (string): When the team dismissed it; empty unless status is dismissed.
- `dismissed_by` (string): Who dismissed it.
- `key` (string, required)
- `kind` ("question" | "coverage", required)
- `listed_by` (string[], required)
- `name` (string, required)
- `not_listed_by` (string[], required)
- `question` (string, required)
- `reason` (string, required)
- `said` (string, required)
- `sessions` (string[], required)
- `status` ("open" | "closed" | "dismissed", required)
- `variants` (string[], required)
- `where` (string, required)

<a id="record-gapanswerin"></a>

### GapAnswerIn

The team's answer to a question the agent couldn't answer. From then on the agent gives it, in its own words, to every buyer who asks it in any wording.

- `answer` (string, required): What buyers should be told, as the team would say it: facts only, no quotes. Up to 2000 characters.
- `key` (string, required): The gap's key Up to 2000 characters.

<a id="record-gapbuyer"></a>

### GapBuyer

A buyer who asked a gap's question: who, how their demo ended, and whether they left right after asking.

- `asked_at` (string, required)
- `company` (string | null, required)
- `demo` (string, required)
- `email` (string | null, required)
- `left_after_s` (number | null): Seconds from asking to their last activity.
- `left_soon` (boolean): They stopped within 90 seconds of asking. Default `false`.
- `outcome` ("meeting" | "qualified" | "nurture" | "anonymous", required)
- `role` (string | null, required)
- `test` (boolean, required)

<a id="record-gapcallsin"></a>

### GapCallsIn

- `key` (string, required): The gap's key Up to 2000 characters.
- `question` (string): The question as asked; left out: the gap's Up to 2000 characters.

<a id="record-gapdismissin"></a>

### GapDismissIn

Set a gap aside (a wrong flag, a test, something buyers are never told), or restore it. It leaves the open list and count; the guide's answers don't change.

- `dismissed` (boolean): false restores it to the open list Default `true`.
- `key` (string, required): The gap's key Up to 2000 characters.
- `reason` ("unpublished" | null): unpublished: the vendor deliberately doesn't publish this (a margin, a custom price), so the agent keeps handing it to the team (ADR 0009)

<a id="record-gapdocument"></a>

### GapDocument

What the document says about the gap's question: whether it answers it (the judge), the passages nearest it, and the answer drafted from them alone when it does. Nothing is said to buyers until the team saves an answer.

- `answers` (boolean, required)
- `draft` (string | null, required): The answer drafted from the passages, checked against them
- `passages` ([GapDocumentPassage](#record-gapdocumentpassage)[], required)
- `title` (string, required)

<a id="record-gapdocumentin"></a>

### GapDocumentIn

A document the team attaches to a gap: the file itself (`content`, base64) or, for a program or an agent that has it as text, its `text`. Kept in the product's docs store.

- `content` (string): The file, base64: .pdf, .docx, .html, .md or .txt, up to 3 MB Up to 4200000 characters.
- `key` (string, required): The gap's key Up to 2000 characters.
- `name` (string, required): Up to 200 characters.
- `question` (string): The question as asked; left out: the gap's Up to 2000 characters.
- `text` (string): Or its text, instead of the file Up to 1000000 characters.

<a id="record-gapdocumentpassage"></a>

### GapDocumentPassage

- `text` (string, required)
- `title` (string, required): The document's name and the heading the passage sits under

<a id="record-gaplist"></a>

### GapList

- `built_at` (number, required)
- `items` ([Gap](#record-gap)[], required)
- `next_cursor` (string | null): Pass it as `cursor` for the questions after these; empty on the last page.
- `open` (integer, required)
- `topics` (object<string, string>): The product's areas (a gap's or a question's `area`) named as topics, in `language`.
- `total` (integer): Questions that matched, over every page. Default `0`.

<a id="record-granolakeyin"></a>

### GranolaKeyIn

A Granola API key the vendor made: a workspace key, or a member's.

- `key` (string, required): The key, as Granola showed it. Up to 500 characters.

<a id="record-handoff"></a>

### Handoff

- `crm` ([HandoffCrm](#record-handoffcrm) | null)
- `days` (integer, required)
- `funnel` ([HandoffFunnel](#record-handofffunnel), required)
- `hidden_tests` (integer): Test demos' requests left out; ask with tests=true to see them. Default `0`.
- `next_cursor` (string | null): Pass it as `cursor` for the requests after these; empty on the last page.
- `requests` ([HandoffRequest](#record-handoffrequest)[], required)
- `total` (integer): Requests in the window, over every page; the funnel counts them all. Default `0`.

<a id="record-handoffcrm"></a>

### HandoffCrm

Whether the leads could be read in the CRM; when not, why (`why`, in words).

- `crm` (string | null, required)
- `median` (number | null): Seconds from asking to the first dated sign, median.
- `moved` (integer): Default `0`.
- `read` (boolean, required)
- `stalled` (integer): Default `0`.
- `waiting` (integer): Default `0`.
- `why` (string)

<a id="record-handofffunnel"></a>

### HandoffFunnel

The requests by state, and the seconds from asking to the first person told.

- `asked` (integer, required)
- `crm_only` (integer, required)
- `failed` (integer, required)
- `median` (number | null, required)
- `not_recorded` (integer, required)
- `open_median` (number | null)
- `open_p90` (number | null)
- `opened` (integer): Default `0`.
- `p90` (number | null, required)
- `reached` (integer, required)

<a id="record-handoffmoved"></a>

### HandoffMoved

Whether the lead moved in the CRM after asking. `state`: moved (any sign), waiting (none yet, asked less than 7 days ago), stalled (none in 7 days). `found`: the CRM has the contact. `first`: seconds from asking to the first dated sign.

- `first` (number | null)
- `found` (boolean, required)
- `signs` ([HandoffSign](#record-handoffsign)[], required)
- `state` ("moved" | "waiting" | "stalled", required)

<a id="record-handoffrequest"></a>

### HandoffRequest

A buyer who asked for the team. `state`: reached (a person was told: the routed email, the channel, or a booking), crm_only (the CRM took it, nobody was told), failed (every step stopped; each says why), not_recorded (asked before steps were kept, 2026-10-20). `seconds`: from asking to the first person told. `went`: the rule that took them then; `now`: where today's rules send them.

- `asked_at` (string, required)
- `brief_link` ([BriefLink](#record-brieflink) | null)
- `company` (string | null, required)
- `email` (string | null, required)
- `moved` ([HandoffMoved](#record-handoffmoved) | null)
- `now` ([HandoffRoute](#record-handoffroute), required)
- `opened` (number | null)
- `priority` (string, required)
- `seconds` (number | null, required)
- `session` (string, required)
- `slot` (string | null, required)
- `state` ("reached" | "crm_only" | "failed" | "not_recorded", required)
- `steps` ([HandoffStep](#record-handoffstep)[], required)
- `went` ([HandoffRoute](#record-handoffroute), required)

<a id="record-handoffroute"></a>

### HandoffRoute

A routing rule's verdict: the rule (`number` from 1; 0: none), who it named, the CRM owner when a rule asked, and, for today's rules, why (`because`, condition by condition).

- `because` (string[])
- `host` (string | null)
- `number` (integer, required)
- `owner` (string | null)
- `route` (string | null, required)
- `to` (string[], required)

<a id="record-handoffsign"></a>

### HandoffSign

One sign the team took the lead on after they asked: a meeting or a logged call or email (`at`), a lifecycle stage past a lead (`value`, in words), or deals (`value`, how many).

- `at` (string | null)
- `kind` ("meeting" | "contacted" | "stage" | "deals", required)
- `value` (string)

<a id="record-handoffstep"></a>

### HandoffStep

One way a request went out. `kind`: slack, webhook, channel (none set), email (the routed one), crm, booking; or SES's word on that email: delivered, opened, clicked, bounced, complained, rejected, delayed. `why`: in words, when it didn't go. `to`: who the email named, or who it bounced from.

- `at` (string, required)
- `kind` (string, required)
- `ok` (boolean, required)
- `to` (string[], required)
- `why` (string, required)

<a id="record-integrationchoice"></a>

### IntegrationChoice

Which provider the account uses for a kind of integration, and where that came from: picked here or in the console ("console"), or the account's setup ("setup").

- `kind` ("crm" | "scheduling", required)
- `provider` (string | null, required)
- `providers` (string[], required)
- `source` ("console" | "setup" | "none", required)

<a id="record-integrationchoicein"></a>

### IntegrationChoiceIn

The provider to use: an id the kind offers, or "off".

- `provider` (string, required): Up to 40 characters.

<a id="record-integrationconnect"></a>

### IntegrationConnect

Where to send the account's owner to approve the connection in the provider's own app. They come back to the console, which finishes it (PUT /integrations/{id}/connection).

- `provider` (string, required)
- `url` (string, required)

<a id="record-integrationconnection"></a>

### IntegrationConnection

A connection the account's owner made by signing in to the provider: which of the vendor's accounts it reaches (`label`), who made it and when. `connected` is false once it is removed.

- `at` (string)
- `by` (string)
- `connected` (boolean, required)
- `label` (string)
- `provider` (string, required)

<a id="record-integrationconnectionin"></a>

### IntegrationConnectionIn

What the provider sent the owner back with.

- `code` (string, required): Up to 2000 characters.
- `picked` (string): Google Drive: the ids of the files picked in Google's picker, comma-separated (picked_file_ids), as Google sent them back. Up to 20000 characters.
- `state` (string, required): Up to 500 characters.

<a id="record-integrationevent"></a>

### IntegrationEvent

- `id` (string, required): The event type's id in the scheduler
- `name` (string, required)
- `url` (string, required): Its booking page

<a id="record-integrationfile"></a>

### IntegrationFile

- `modified` (string, required)
- `title` (string, required)

<a id="record-integrationgroup"></a>

### IntegrationGroup

- `id` (string, required)
- `items` ([IntegrationOut](#record-integrationout)[], required)
- `title` (string, required)

<a id="record-integrationmadeby"></a>

### IntegrationMadeBy

- `at` (string, required): When, ISO 8601.
- `by` (string, required): Who connected it.
- `label` (string, required): What it is connected to, such as the HubSpot portal.

<a id="record-integrationout"></a>

### IntegrationOut

One integration as the console's Integrations page shows it.

- `calls` (integer | null): Sales calls: how many were read, once something is picked.
- `connect` (boolean, required): An owner connects it by signing in there.
- `connection` ([IntegrationMadeBy](#record-integrationmadeby) | null, required)
- `crm` (string | null, required): The CRM it is, when it is one.
- `detail` (string, required): One line on what it holds once connected, or why it was lost.
- `docs` (string | null, required)
- `event` ([IntegrationEvent](#record-integrationevent) | null, required): Calendly or Cal.com: the event buyers book.
- `events` (boolean, required): Calendly or Cal.com: its event types can be picked.
- `files` ([IntegrationFile](#record-integrationfile)[] | null, required): Internal docs: the files last read.
- `how` (string, required): How it is set up.
- `id` (string, required)
- `line` (string, required): What it does, in one line.
- `link` (string | null, required): HubSpot Meetings: the meeting link buyers book.
- `links` (boolean, required): HubSpot Meetings: its meeting links can be picked.
- `name` (string, required)
- `paste` (boolean, required): Connected by pasting a link (internal docs).
- `router` (string | null): Chili Piper: the router buyers go through.
- `routers` (boolean): Chili Piper, its token pasted: its routers can be picked. Default `false`.
- `routing` (boolean, required): Email alerts: set up on the Routing page.
- `scheduler` (string | null, required): The scheduler it is, when it is one.
- `sign_in_again` (boolean): Zendesk, connected by an API token where it now connects by signing in: an owner signs in (POST /integrations/zendesk/sign-in) to keep it, and the audiences picked carry over. Default `false`.
- `skipped` (string[], required)
- `snippet` (string | null, required): The website embed's script tag, once it has a key.
- `status` ("connected" | "not_connected" | "planned", required)
- `what` (string, required)

<a id="record-integrationpicked"></a>

### IntegrationPicked

- `chosen` (string | null, required): The provider picked, or off; null before a pick.
- `source` (string, required): Picked in the console, or the setup's.

<a id="record-integrations"></a>

### Integrations

Every integration with its state, grouped as the console's Integrations page shows them, and the scheduler and CRM the account picked.

- `calendar` ([IntegrationPicked](#record-integrationpicked), required)
- `crm` ([IntegrationPicked](#record-integrationpicked), required)
- `groups` ([IntegrationGroup](#record-integrationgroup)[], required)

<a id="record-internaldoc"></a>

### InternalDoc

A document the agent answers from: its title and when its source last changed it.

- `modified` (string)
- `title` (string, required)

<a id="record-internaldocs"></a>

### InternalDocs

What a source of internal docs holds at its last read, and what that read left out.

- `at` (string)
- `connected` (boolean, required)
- `docs` ([InternalDoc](#record-internaldoc)[])
- `label` (string)
- `provider` (string, required)
- `skipped` (string[]): Each "Title: why" it was not read.

<a id="record-internaldocschoice"></a>

### InternalDocsChoice

Which side the agent follows where the vendor's internal docs and its public docs state one thing two ways: the other side's passage is left out of what it answers from.

- `prefer` ("internal" | "public", required)

<a id="record-lead"></a>

### Lead

One buyer, as of `at`: who they are, why the lead matters, what they saw and asked, whether they want the team, and the follow-up drafted for them. The same record a CRM receives.

- `schema` (string): Default `"solacia.lead.v1"`.
- `activity` ([Activity](#record-activity), required)
- `at` (string, required)
- `calls` ([Call](#record-call)[] | null): With include=calls.
- `campaign` (string | null): The campaign of the personal demo link the buyer came in by, if it named one.
- `concerns` ([Concern](#record-concern)[], required)
- `contact` ([Contact](#record-contact), required)
- `deals` ([Deal](#record-deal)[] | null): With include=deals: the buyer's deals in the account's CRM, read now.
- `event` (string, required): lead.snapshot when read here; lead.contact, lead.team_request or lead.call_ended when pushed.
- `facts` ([LeadFact](#record-leadfact)[], required)
- `fit` (string | null, required)
- `follow_up` ([FollowUp](#record-followup) | null, required)
- `link` (string, required): The team's page for this buyer.
- `network` ([Network](#record-network) | null): The company the buyer's network address was looked up as when they gave their email, if it was. An office network can name the company; home, mobile and VPN addresses mostly name none.
- `next_meeting` (string[], required)
- `number` (integer | null): Which try of the demo this is; #1 is the first.
- `priority` ("hot" | "warm" | "nurture" | "cold", required)
- `product` (string, required)
- `questions` ([LeadQuestion](#record-leadquestion)[], required)
- `reasons` ([Reason](#record-reason)[], required)
- `seen` (string[], required)
- `session` (string, required): The demo's id; the same as a demo's `id`.
- `source` ([LeadSource](#record-leadsource) | null): Where the buyer came from; null when nobody knows.
- `stages` (string[], required): How far the demo went: email, call, saw, asked, team.
- `team_request` ([TeamRequest](#record-teamrequest), required)
- `test` (boolean, required): One of the vendor's or our own test demos.
- `transcript` ([Line](#record-line)[] | null): With include=transcript.
- `vendor` (string, required)

<a id="record-leadfact"></a>

### LeadFact

- `group` (string, required)
- `label` (string, required)
- `source` (string, required): said, confirmed or inferred
- `value` (string, required)

<a id="record-leadpage"></a>

### LeadPage

- `counts` (object<string, integer>, required): Leads per priority, over the whole filter.
- `items` ([Lead](#record-lead)[], required)
- `next_cursor` (string | null, required)
- `total` (integer): Leads that matched, over every page. Default `0`.

<a id="record-leadquestion"></a>

### LeadQuestion

- `answer` (string | null, required): Only an answer that held; null when the team owes it.
- `answered` (boolean, required)
- `at` (string, required)
- `channel` (string, required)
- `question` (string, required)

<a id="record-leadsource"></a>

### LeadSource

Where the buyer came from: your own campaign tags as you wrote them, the campaign, the page that brought them to the demo, and Solacia's reading of a channel.

- `arrival_url` (string | null): The page that brought the buyer, with the tags Solacia kept from its address.
- `arrived_at` (string | null): When that visit was, ISO 8601, when the site kept it.
- `campaign` (string | null): The demo link's campaign, else the page's utm_campaign.
- `channel` (string, required): Solacia's reading of where the buyer came from, beside your own tags, never in their place: outbound (a personal demo link), paid, email, social, ai_assistant, organic, referral, campaign or direct; by the visit that first brought the buyer to the site when known, else the page the demo opened on.
- `click_id` (string | null): Which ad click id the visit carried (gclid, msclkid, fbclid, li_fat_id, ...), if any.
- `click_ids` (object<string, string>): The ad click ids of that visit, by name (gclid, msclkid, fbclid, oppref, ...).
- `embedded` (boolean): The demo was opened from the embed on the vendor's own site. Default `false`.
- `first_touch` ([SourceTouch](#record-sourcetouch) | null)
- `landing_page` (string | null): The page the demo was opened on.
- `last_touch` ([SourceTouch](#record-sourcetouch) | null)
- `referrer` (string | null)
- `utm` (object<string, string>): Your utm_source, utm_medium, utm_campaign, utm_term and utm_content, exactly as you wrote them, of the visit that first brought the buyer to the site when known, else of the page the demo opened on. Each touch below has its own.

<a id="record-lever"></a>

### Lever

- `changes` (string[], required): The parts of a version it changes
- `counts` ("qualified" | "meeting", required): The goal its test is read on
- `id` ("message" | "features" | "pricing" | "offer" | "qualification", required): message: what it says and how; features: what it shows first; pricing: what it charges (its facts); offer: what it asks the buyer to do (its goal); qualification: who it is for and what it asks them (audience, rules)
- `readings` ([LeverReading](#record-leverreading)[], required)

<a id="record-leverreading"></a>

### LeverReading

What the agent's buyers did that a lever's test starts from: `n` of `of` buyers.

- `key` (string | null): The part or the product area it is about
- `kind` ("left_early" | "left_on_part" | "asked_about" | "met_after_prices" | "met_without_prices" | "qualified_not_met" | "qualified" | "met_unqualified", required): left_early: left in the first minute without the goal, of every buyer; left_on_part: left during part `key` without asking to meet, of those who stayed a minute; asked_about: asked about area `key`, of every buyer; met_after_prices / met_without_prices: asked to meet, of those shown the prices or not; qualified_not_met: did not ask to meet, of those who qualified; qualified: of every buyer; met_unqualified: did not qualify, of those who asked to meet
- `n` (integer, required)
- `of` (integer, required)
- `title` (object<string, string> | null): The part's title per language

<a id="record-line"></a>

### Line

- `at` (string, required)
- `kind` (string): An event's kind: opened, played, source, showed, presented, team, call_started or call_ended.
- `note` (string)
- `text` (string, required)
- `what` (string): The screen, place or deck the event names, or how the call ended.
- `who` ("buyer" | "guide" | "event", required)

<a id="record-linkrefused"></a>

### LinkRefused

A row no link was made for, and why: the same answer a single link would get.

- `code` (string, required): `invalid_email`, `personal_email` or `invalid_days`.
- `detail` (string, required)
- `email` (string, required)
- `row` (integer, required): The row's place in `rows`, from 0.

<a id="record-maileventtaken"></a>

### MailEventTaken

What came of it: confirmed (the subscription), kept (with its buyer), ignored (not an event we keep), unmatched (no product or buyer in its tags).

- `result` ("confirmed" | "kept" | "ignored" | "unmatched", required)

<a id="record-maileventsheard"></a>

### MailEventsHeard

- `at` (string, required): When, ISO 8601.
- `event` (string): The SES event it carried, as Handoff's steps name it.
- `product` (string): The account whose buyer it named.
- `result` (string, required): What came of SNS's last post: confirmed, kept, ignored or unmatched.

<a id="record-maileventskeymade"></a>

### MailEventsKeyMade

- `events_set` (string, required): The SES configuration set every routed email names (MAIL_EVENTS_SET); empty: no events.
- `key` (boolean, required): Whether the key SNS posts with is live.
- `key_at` (string): When, ISO 8601.
- `key_by` (string): Who made it.
- `last` ([MailEventsHeard](#record-maileventsheard) | null): SNS's last post; null before the first.
- `path` (string, required): Where SNS posts, on this site.
- `secret` (string, required): The key, shown this once: Solacia keeps only its hash.

<a id="record-maileventsstatus"></a>

### MailEventsStatus

Whether SES's events on the routed emails reach Solacia: the console's proof.

- `events_set` (string, required): The SES configuration set every routed email names (MAIL_EVENTS_SET); empty: no events.
- `key` (boolean, required): Whether the key SNS posts with is live.
- `key_at` (string): When, ISO 8601.
- `key_by` (string): Who made it.
- `last` ([MailEventsHeard](#record-maileventsheard) | null): SNS's last post; null before the first.
- `path` (string, required): Where SNS posts, on this site.

<a id="record-me"></a>

### Me

Who the key or session is, and what it may do: the first call to make with a new key.

- `account` (string, required)
- `account_name` (string, required)
- `actor` ("operator" | "api_key" | "user" | "connection", required)
- `name` (string, required)
- `products` (string[], required)
- `role` (string | null, required)
- `scopes` (string[], required)

<a id="record-melanguagein"></a>

### MeLanguageIn

- `language` ("en" | "es" | "pt", required): English, Spanish or Portuguese.

<a id="record-menamein"></a>

### MeNameIn

- `name` (string, required): How the team sees them on Team and in Handoff. Up to 80 characters.

<a id="record-mepasswordin"></a>

### MePasswordIn

- `current` (string, required): Up to 200 characters.
- `new` (string, required): At least 10 characters. Up to 200 characters.

<a id="record-mepicturein"></a>

### MePictureIn

- `image` (string, required): A JPEG, PNG or WebP as a base64 data: URL, at most 48 KB decoded (a square of about 160 px); empty takes the picture away. Up to 65536 characters.

<a id="record-meetinglink"></a>

### MeetingLink

One of the connected HubSpot's meeting links.

- `kind` (string): one rep, group or round robin
- `name` (string, required)
- `url` (string, required)

<a id="record-meetinglinkin"></a>

### MeetingLinkIn

The link buyers book: one the connected HubSpot lists.

- `url` (string, required): Up to 500 characters.

<a id="record-meetinglinks"></a>

### MeetingLinks

The meeting link buyers book through HubSpot Meetings (`url`, empty until one is picked) and the links the connected HubSpot offers.

- `links` ([MeetingLink](#record-meetinglink)[], required)
- `url` (string, required)

<a id="record-network"></a>

### Network

- `company` (string | null, required): Null when the lookup named no company.
- `confidence` (string | null, required): The provider's grade: very high, high, moderate, low or very low.
- `domain` (string | null, required)
- `industry` (string | null, required)
- `matches_email` (boolean | null, required): The company's domain is the email's; null when either is missing.
- `provider` (string, required)
- `size` (string | null, required): Employees, as a range such as 51-200.

<a id="record-nothing"></a>

### Nothing

The input of an operation that takes only its path.

None.

<a id="record-person"></a>

### Person

The caller, a person who signs in to the console. In preview.

- `added_at` (string): When they joined, ISO 8601.
- `email` (string, required)
- `language` ("en" | "es" | "pt"): What their console speaks: their own pick, else the account's language. In preview. Default `"en"`.
- `name` (string, required)
- `picture` (string): Their picture as a data: URL (a small square JPEG, PNG or WebP), or empty.
- `role` ("owner" | "member" | "solacia", required)

<a id="record-poolvoice"></a>

### PoolVoice

- `accent` (string, required): The locale it is native to, e.g. es-CO
- `gender` ("f" | "m" | "", required): f or m; empty for a product voice outside the pool
- `id` (string, required): The voice's id at the speech provider
- `name` (string, required): Its name; empty for a product voice outside the pool

<a id="record-problem"></a>

### Problem

Every error, as application/problem+json.

- `code` (string, required)
- `detail` (string, required)
- `request_id` (string | null): The X-Request-Id of this request; quote it when asking about the error.
- `status` (integer, required)
- `title` (string, required)
- `type` (string): Default `"about:blank"`.

<a id="record-question"></a>

### Question

- `schema` (string): Default `"solacia.question.v1"`.
- `answer` (string | null, required)
- `area` (string | null, required)
- `at` (string, required)
- `channel` (string, required)
- `demo` (string, required)
- `status` ("sourced" | "partial" | "unsourced" | "spoken" | "wrong" | "none", required)
- `text` (string, required)

<a id="record-questionpage"></a>

### QuestionPage

- `items` ([Question](#record-question)[], required)
- `next_cursor` (string | null, required)
- `total` (integer): Questions that matched, over every page. Default `0`.

<a id="record-reason"></a>

### Reason

- `text` (string, required)
- `tone` ("intent" | "fit" | "caution", required)

<a id="record-recordingout"></a>

### RecordingOut

One call of the demo as recorded: the buyer's voice and the agent's. In preview.

- `anchors` ([Anchor](#record-anchor)[]): Where the sound was against the clock, every half minute: a moment's place in the sound is read between the two around it (after `began` alone when there are none).
- `audio` (string, required): A link that plays it (Opus in WebM) for the next hour.
- `began` (string, required): When the sound starts, ISO 8601: the transcript's times fall on it.
- `n` (integer, required): Its number among the demo's recordings, oldest first; it never changes.
- `screen` (string | null): A link to the buyer's screen through the call for the next hour: rrweb's events, JSON compressed with gzip, their times on the same clock as `began`. None when none was kept.
- `seconds` (integer, required)

<a id="record-recordings"></a>

### Recordings

The demo's calls as recorded and still kept: 90 days, when the call ran 2 minutes or more, the buyer qualified or asked to meet. In preview.

- `recordings` ([RecordingOut](#record-recordingout)[], required)

<a id="record-routedbuyer"></a>

### RoutedBuyer

One of the latest buyers, and the rule that takes them (`number` from 1; 0: none).

- `asked` (boolean, required)
- `booked` (boolean, required)
- `company` (string | null, required)
- `email` (string, required)
- `host` (string | null)
- `number` (integer, required)
- `owner` (string | null)
- `priority` (string, required)
- `route` (string | null, required)
- `session` (string, required)
- `to` (string[], required)

<a id="record-routerfield"></a>

### RouterField

One field of a router's form, as Chili Piper defines it: the key the form sends it under, the data field it fills, its label, its type and the values a dropdown takes.

- `data_field` (string)
- `key` (string, required)
- `kind` ("text" | "number" | "email" | "phone" | "choice" | "many" | "yes_no" | "date"): Default `"text"`.
- `label` (string)
- `options` (string[])

<a id="record-routing"></a>

### Routing

The account's rules, the people to pick from, the product's rules a condition can name, whether this environment sends email, and where the latest buyers go.

- `editable` (boolean, required)
- `owners` ([RoutingOwners](#record-routingowners), required)
- `people` ([RoutingPerson](#record-routingperson)[], required)
- `preview` ([RoutedBuyer](#record-routedbuyer)[], required)
- `routes` ([RoutingRule](#record-routingrule)[], required)
- `rules` ([RoutingRuleOption](#record-routingruleoption)[], required)
- `sending` (boolean, required)
- `unreadable` (string[]): Default `[]`.

<a id="record-routingcondition"></a>

### RoutingCondition

One condition of a rule; any of its values holds. `kind`: priority (hot, warm, nurture), rule (the product's own fit and intent rules, by id), booked (booked, asked, or left: never asked for the team, flag lead_owner), crm_owner (no values).

- `kind` (string, required): Up to 20 characters.
- `values` (string[])

<a id="record-routingin"></a>

### RoutingIn

The account's rules, in order: the first that fits a buyer decides.

- `routes` ([RoutingRule](#record-routingrule)[], required)

<a id="record-routingowners"></a>

### RoutingOwners

Whether a rule can name the buyer's owner in the CRM here (`crm`: HubSpot or Salesforce), and if not, what to do (`why`).

- `crm` (string | null, required)
- `ready` (boolean, required)
- `why` (string, required)

<a id="record-routingperson"></a>

### RoutingPerson

- `email` (string, required)
- `name` (string, required)
- `role` (string, required)

<a id="record-routingpreview"></a>

### RoutingPreview

- `preview` ([RoutedBuyer](#record-routedbuyer)[], required)

<a id="record-routingrecipient"></a>

### RoutingRecipient

Who hears: an email address, `owner` for the buyer's owner in the CRM, or `booked_with` for the rep the scheduler booked the meeting with (a rule naming them needs the condition booked: [booked]). `weight`: their percentage share when the rule takes turns.

- `email` (string, required): Up to 320 characters.
- `weight` (number): Default `1`.

<a id="record-routingrule"></a>

### RoutingRule

A rule: when all its conditions hold (none: every buyer), who hears and how. `share`: `all` (everyone on it) or `turns` (one, by weight, the same one for the same buyer).

- `channels` (string[])
- `id` (string, required): Up to 64 characters.
- `owns` (boolean): The one person it picks for a buyer owns their new lead in the CRM: the rep they booked with, else its turn's pick (Salesforce; flag lead_owner). Default `false`.
- `share` (string): Up to 8 characters. Default `"all"`.
- `to` ([RoutingRecipient](#record-routingrecipient)[])
- `when` ([RoutingCondition](#record-routingcondition)[])

<a id="record-routingruleoption"></a>

### RoutingRuleOption

One of the product's own fit or intent rules a condition can name.

- `check` (string, required)
- `id` (string, required)
- `kind` ("fit" | "intent", required)
- `label` (string, required)

<a id="record-routingtest"></a>

### RoutingTest

Whether the test went, to whom, and why not.

- `detail` (string, required)
- `sent` (boolean, required)
- `to` (string[], required)

<a id="record-routingtestin"></a>

### RoutingTestIn

- `route` (string, required): Up to 64 characters.

<a id="record-salescall"></a>

### SalesCall

What one call holds for the agent. No names: the reading strips them.

- `asked` ([CallAsked](#record-callasked)[], required)
- `date` (string, required)
- `objections` ([CallObjection](#record-callobjection)[], required)
- `pitch` ([CallMove](#record-callmove)[], required)
- `sales` (boolean, required): A call with a buyer; false for an internal meeting.
- `title` (string, required)
- `url` (string): The call in Granola or Fathom, for the vendor's team.

<a id="record-salescalls"></a>

### SalesCalls

What a sales-call connection (Granola or Fathom) covers: the folders picked, the calls read, newest first, and how many are still to read (POST again while unread is above 0).

- `at` (string)
- `calls` ([SalesCall](#record-salescall)[])
- `connected` (boolean, required)
- `label` (string)
- `listed` (integer): Calls found in the picked folders. Default `0`.
- `picked` ([CallPlace](#record-callplace)[])
- `skipped` (string[])
- `unread` (integer): Default `0`.

<a id="record-salescallsreadin"></a>

### SalesCallsReadIn

- `listed_within` (integer): Once every call is read, list the picked folders again only when the last listing is older than this many seconds (0: always). Above 0, a connection with no folders picked is no error. 0 to 86400. Default `0`.

<a id="record-snspost"></a>

### SnsPost

What SNS posts: a subscription to confirm, or a notification carrying one SES event in `Message` (JSON). Field names are SNS's own.

- `Message` (string): Up to 200000 characters.
- `MessageId` (string): Up to 100 characters.
- `Signature` (string): Up to 1000 characters.
- `SignatureVersion` (string): Up to 4 characters.
- `SigningCertURL` (string): Up to 500 characters.
- `Subject` (string | null)
- `SubscribeURL` (string): Up to 2000 characters.
- `Timestamp` (string): Up to 40 characters.
- `Token` (string): Up to 1000 characters.
- `TopicArn` (string): Up to 300 characters.
- `Type` (string, required): Up to 40 characters.
- `UnsubscribeURL` (string): Up to 2000 characters.

<a id="record-sourcetouch"></a>

### SourceTouch

- `at` (string | null)
- `channel` (string, required): Solacia's reading of this visit, as the lead's `channel`.
- `click_id` (string | null): Which ad click id this visit carried, if any.
- `page` (string, required): The page's address, without its query.
- `referrer` (string | null, required): The host of the site that sent the buyer there, if another site did.
- `utm` (object<string, string>): The utm_ tags this visit carried, exactly as you wrote them.

<a id="record-standing"></a>

### Standing

Where one demo stands, as the console's demo page heads it: what it came to, the meeting time the buyer picked, the agent that ran it, where it was opened, and what followed. In preview.

- `agent` (string | null, required)
- `crm` (boolean, required): Sent to the account's CRM.
- `door` (string | null, required): Where it was opened: outbound, site:<host>, site (the embed, page unknown) or link.
- `fit` (string, required)
- `follow_up` (boolean, required): A follow-up email is drafted.
- `id` (string, required)
- `label` (string, required): The outcome in words.
- `outcome` ("meeting" | "qualified" | "nurture" | "anonymous", required)
- `qualified` (boolean, required): Hot or warm by the account's fit rules, whatever the outcome.
- `seen` (integer, required): The parts of the product they saw.
- `slot` (string | null, required): The meeting time the buyer picked.
- `source` ([LeadSource](#record-leadsource) | null): Where the buyer came from, your own tags first, as on the lead; null when nobody knows.

<a id="record-started"></a>

### Started

The caller's first steps in the console, each done or not; none once every one was done, for Solacia's own people, or for a key.

- `crm` (string): The CRM the account picked, by name; empty until one is.
- `site` (string): The vendor's own domain, where the demo goes.
- `snippet` (string): The script tag for the site, once the account has an embed key.
- `steps` ([StartedStep](#record-startedstep)[], required)

<a id="record-startedstep"></a>

### StartedStep

- `done` (boolean, required): Done, from what is true: never ticked by hand.
- `id` ("demo" | "crm" | "slack" | "team" | "site" | "two_step" | "question", required): `demo` try your own demo, `crm` connect the CRM, `slack` connect Slack, `team` invite the team, `site` put the demo on the site, `two_step` turn on two-step sign-in, `question` answer the first question the agent couldn't.

<a id="record-team"></a>

### Team

Who can sign in to the account's console, the invitations out, and whether the caller may change either. In preview: invitations and changes are off for most accounts.

- `invitations` ([TeamInvitation](#record-teaminvitation)[], required)
- `manage` (boolean, required): The caller may invite people, change roles and remove people.
- `members` ([TeamMember](#record-teammember)[], required)
- `reach` ([TeamReach](#record-teamreach) | null)
- `recipients` ([TeamRecipient](#record-teamrecipient)[]): Addresses on Handoff rules that don't sign in. Default `[]`.
- `sending` (boolean, required): Invitations go out by email here; otherwise share the link.

<a id="record-teamhandoverin"></a>

### TeamHandOverIn

- `email` (string, required): Whose place on the Handoff rules moves. Up to 254 characters.
- `to` (string, required): Who takes it: a teammate's or any work email. Up to 254 characters.

<a id="record-teamheard"></a>

### TeamHeard

What the routed emails sent this address over the last `reach.days` days.

- `buyers` (integer, required): Buyers who asked for the team that a routed email named them for.
- `last` ("sent" | "delivered" | "opened" | "bounced" | "failed" | null): How the latest went: SES's latest word on it, else whether it was sent.
- `last_at` (string | null): When the latest went out, ISO 8601.
- `why` (string): In words, when the latest didn't arrive.

<a id="record-teaminvitation"></a>

### TeamInvitation

An invitation not accepted yet. Its link was shown once, when it was made.

- `by` (string, required): Who sent it: their email.
- `by_name` (string, required)
- `email` (string, required)
- `expired` (boolean, required)
- `expires_at` (string, required)
- `heard` ([TeamHeard](#record-teamheard) | null): What reached them lately; none: no routed email named them.
- `places` ([TeamPlace](#record-teamplace)[]): The Handoff rules that name them, in order; none: they get no buyers. Default `[]`.
- `recent` ([TeamSent](#record-teamsent)[]): The last few buyers sent to them, newest first. Default `[]`.
- `role` ("owner" | "member" | "solacia", required)
- `sent_at` (string, required)

<a id="record-teaminvitein"></a>

### TeamInviteIn

- `email` (string, required): The person's work email. Up to 254 characters.
- `role` ("owner" | "member" | "solacia"): `solacia` only for Solacia's own people. Default `"member"`.

<a id="record-teaminvited"></a>

### TeamInvited

The invitation made, and its link: shown this once. `sent` says whether the email went; when it didn't, `detail` says why and the link is for the caller to send.

- `detail` (string, required)
- `email` (string, required)
- `link` (string, required)
- `sent` (boolean, required)
- `team` ([Team](#record-team), required)

<a id="record-teammember"></a>

### TeamMember

- `added_at` (string, required): When they first joined, ISO 8601.
- `email` (string, required)
- `heard` ([TeamHeard](#record-teamheard) | null): What reached them lately; none: no routed email named them.
- `name` (string, required)
- `picture` (string): Their picture as a data: URL, or empty.
- `places` ([TeamPlace](#record-teamplace)[]): The Handoff rules that name them, in order; none: they get no buyers. Default `[]`.
- `recent` ([TeamSent](#record-teamsent)[]): The last few buyers sent to them, newest first. Default `[]`.
- `role` ("owner" | "member" | "solacia", required)
- `two_step` (boolean): They sign in with a code from an authenticator app too. Default `false`.
- `you` (boolean, required): The caller is this person.

<a id="record-teamplace"></a>

### TeamPlace

One Handoff rule that names this address.

- `label` (string, required): The buyers the rule takes, in words: "Hot buyers", "Everyone else".
- `number` (integer, required): The rule's place in the list, from 1.
- `others` ([TeamShare](#record-teamshare)[]): Everyone else the rule names, in its order; `owner` is the buyer's owner in the CRM. Default `[]`.
- `route` (string, required): The rule's id, as GET /v1/routing names it.
- `share` ("all" | "turns", required): Everyone on the rule hears, or one of them by turns.
- `turns` (integer | null): Their percentage of the turns, when the rule takes turns.

<a id="record-teamreach"></a>

### TeamReach

Where a buyer who asks for the team goes, in one line.

- `channel` (string | null): The team's channel for every request: Slack's label, or a webhook.
- `crm` (string | null): The CRM whose owner of the buyer hears too, when a rule tells them.
- `days` (integer, required): The days `heard` counts over.
- `emails` (integer, required): Addresses the Handoff rules name, people or not.

<a id="record-teamrecipient"></a>

### TeamRecipient

An address a Handoff rule names that doesn't sign in to the console: an alias, or a teammate never invited. They get each buyer's brief by email.

- `email` (string, required)
- `heard` ([TeamHeard](#record-teamheard) | null): What reached them lately; none: no routed email named them.
- `places` ([TeamPlace](#record-teamplace)[]): The Handoff rules that name them, in order; none: they get no buyers. Default `[]`.
- `recent` ([TeamSent](#record-teamsent)[]): The last few buyers sent to them, newest first. Default `[]`.

<a id="record-teamrequest"></a>

### TeamRequest

- `booked` (object | null, required): The meeting made in the vendor's scheduler.
- `requested` (boolean, required)
- `slot` (string | null, required): The time they picked, ISO 8601 with offset.

<a id="record-teamrolein"></a>

### TeamRoleIn

- `role` ("owner" | "member" | "solacia", required)

<a id="record-teamsent"></a>

### TeamSent

One buyer a routed email named this address for.

- `asked_at` (string, required): When they asked for the team, ISO 8601.
- `booked` (boolean, required): They picked a time, rather than asking without one.
- `company` (string | null): The buyer's company, from their email's domain.
- `email` (string | null): The buyer's email.
- `last` ("sent" | "delivered" | "opened" | "bounced" | "failed", required): How this address's email about them went.
- `session` (string, required): The buyer's demo, as GET /v1/demos/{id} reads it.
- `why` (string): In words, when it didn't arrive.

<a id="record-teamshare"></a>

### TeamShare

- `email` (string, required)
- `turns` (integer | null)

<a id="record-testarm"></a>

### TestArm

- `agent` (string, required)
- `best` (number, required): The chance this side is the best of them (0 to 1)
- `buyers` (integer, required): Buyers put on this side who opened a demo; each counts once
- `cost` (integer | null, required): US cents a demo. Solacia's people only; null for everyone else
- `demos` (integer, required)
- `key` (string, required): A (what ran before), B, C
- `loss` (number, required): Meeting rate lost on average by keeping this side, if another is better (0.004 = 0.4 points)
- `meetings` (integer, required): Buyers who asked for a meeting
- `name` (string, required)
- `rate` (number, required): meetings / buyers
- `renderer` ("voice" | "face", required)
- `share` (integer, required): Percent of buyers sent to this side
- `version` (integer | null): In a test between an agent's versions: this side's; null for its draft

<a id="record-testarmin"></a>

### TestArmIn

- `agent` (string, required): An agent's id, or "none": on the website no demo button, the vendor's usual Get a demo; in outreach the same email without the demo link Up to 80 characters.
- `share` (integer, required): Percent of buyers 0 to 100.

<a id="record-testguardrail"></a>

### TestGuardrail

One guardrail across a test's two sides, as a scorecard row: side A, side B, B minus A and its interval, read as the goal's is (valid however often it is read).

- `a` (number, required)
- `a_count` (integer | null): Buyers who did it on side A; null for an average
- `b` (number, required)
- `b_count` (integer | null)
- `better` ("up" | "down", required): Which way is better
- `gap` (number, required): b minus a: points of share, or minutes
- `high` (number | null, required)
- `id` ("meetings" | "minutes" | "left_early", required): meetings: share who asked to meet the team; minutes: average minutes in the demo; left_early: share who left in the first minute
- `low` (number | null, required): Null until both sides have buyers

<a id="record-testguards"></a>

### TestGuards

- `buyers` (integer, required)
- `left_early` (number, required): Share who left in the first minute
- `meetings` (number, required): Share who asked to meet the team
- `minutes` (number, required): Average minutes in the demo

<a id="record-testlook"></a>

### TestLook

The test as it stood at the end of one of its weeks.

- `at` (string, required): When that week ended
- `better` (number, required): The chance it is better by over a point
- `buyers` (integer[], required): On each side, A first
- `gap` (number, required): The best challenger's rate minus A's
- `high` (number, required)
- `low` (number, required)
- `rates` (number[], required)
- `safe` (string | null): Under unless_worse: the side that could go live at this week's end
- `same` (number, required): The chance it is within a point either way
- `week` (integer, required): 1: its first seven days
- `worse` (number, required): The chance that challenger is worse than A, by over a point

<a id="record-testplangap"></a>

### TestPlanGap

- `gap` (number, required): The challenger's true rate minus the live version's (0.07 = 7 points)
- `proven` ([TestPlanRun](#record-testplanrun), required)
- `unless_worse` ([TestPlanRun](#record-testplanrun), required)

<a id="record-testplanrun"></a>

### TestPlanRun

- `by_week` (number[]): Share of simulated tests gone live by the end of each week, from week 1
- `live` (number, required): Share of simulated tests where the challenger went live in time
- `weeks` (integer | null, required): Median week it went live; null when under half did

<a id="record-testside"></a>

### TestSide

One side of a test between an agent's versions, as its buyers went through it.

- `guards` ([TestGuards](#record-testguards), required)
- `key` (string, required)
- `paths` ([FlowWay](#record-flowway)[], required): How many buyers went each way, as Home's flow reads demos; every way listed, zeros included

<a id="record-themecolours"></a>

### ThemeColours

The demo's colours, each #rrggbb: the call around the product and the popup's loading screen, never the product's own screens.

- `accent` (string, required): Links, the active item, focus rings
- `accent_deep` (string, required): The accent under the pointer, and on a tint
- `accent_soft` (string, required): Tints behind highlighted things
- `background` (string, required): Behind everything
- `button` (string, required): The main button, with white words on it
- `line` (string, required): Borders and dividers
- `muted` (string, required): Secondary words: hints, labels, times
- `surface` (string, required): Cards and panels
- `text` (string, required): The words

<a id="record-themein"></a>

### ThemeIn

New colours for the demo. One left out keeps the product's own. White words on the button and the accent, and the text on the background and panels, need 4.5:1 contrast.

- `accent` (string | null): Links, the active item, focus rings
- `accent_deep` (string | null): The accent under the pointer, and on a tint
- `accent_soft` (string | null): Tints behind highlighted things
- `background` (string | null): Behind everything
- `button` (string | null): The main button, with white words on it
- `line` (string | null): Borders and dividers
- `muted` (string | null): Secondary words: hints, labels, times
- `surface` (string | null): Cards and panels
- `text` (string | null): The words

<a id="record-themesitein"></a>

### ThemeSiteIn

A website to take the demo's colours from.

- `url` (string, required): Up to 300 characters.

<a id="record-themesuggestion"></a>

### ThemeSuggestion

Colours for the demo, read from a website: nothing is saved until they are chosen with PUT /demo/theme.

- `colours` ([ThemeColours](#record-themecolours), required)
- `found` (boolean, required): Whether the site showed a colour of its own
- `notes` (string[], required): What was found on the site, and what was changed to keep it readable
- `rendered` (boolean, required): Read as a visitor sees the page, rather than from its code

<a id="record-toneout"></a>

### ToneOut

- `name` (string, required)
- `says` (string, required): What the guide is told, word for word

<a id="record-transcript"></a>

### Transcript

- `schema` (string): Default `"solacia.transcript.v1"`.
- `id` (string, required)
- `lines` ([Line](#record-line)[], required)

<a id="record-trylinkin"></a>

### TryLinkIn

Marks a link already made as a try link, or as one sent to a buyer again (Solacia's team only). The link and its demos stay as they are; only what its demos tell from now on follows the mark.

- `email` (string, required): The email the link was made for, as the list of links gives it. Up to 254 characters.
- `try_out` (boolean): True: a try link, whose demos never post to Slack or reach your CRM. False: a link sent to a buyer. Default `true`.

<a id="record-trylinkmarked"></a>

### TryLinkMarked

- `email` (string, required)
- `try_out` (boolean, required)

<a id="record-twostepcodein"></a>

### TwoStepCodeIn

- `code` (string, required): A code from the app, or a backup code. Up to 40 characters.

<a id="record-twostepcodes"></a>

### TwoStepCodes

Backup codes, shown this once: each signs in once when the phone is lost.

- `backup_codes` (string[], required)
- `state` ([TwoStepState](#record-twostepstate), required)

<a id="record-twostepsetup"></a>

### TwoStepSetup

A new secret for the authenticator app: scan `qr` (an SVG data: URI) or type `secret`. Two-step sign-in turns on with the app's first code (POST /me/two-step/confirm).

- `qr` (string, required): The QR code, as an SVG data: URI an img can show.
- `secret` (string, required)
- `uri` (string, required): The otpauth:// link the QR code holds.

<a id="record-twostepstate"></a>

### TwoStepState

The caller's two-step sign-in. In preview.

- `available` (boolean, required): The caller can turn it on here.
- `backup_codes_left` (integer, required)
- `on` (boolean, required): Sign-in asks for a code from their authenticator app after the password.
- `since` (string, required): When it was turned on, ISO 8601; empty when off.

<a id="record-versionsidein"></a>

### VersionSideIn

- `share` (integer, required): Percent of the agent's buyers 10 to 90.
- `version` (integer | "draft", required): A version number (side A: the live one), or draft: the draft as it is now

<a id="record-voicepool"></a>

### VoicePool

- `product` (string, required): The voice calls speak this language with when the agent picks none
- `voices` ([PoolVoice](#record-poolvoice)[], required): The voices to pick from, the product's own first

<a id="record-voicesample"></a>

### VoiceSample

- `audio` (string, required): The line said, base64
- `line` (string, required): What the voice says: the start of the account's opening in that language
- `type` (string, required): The audio's media type

<a id="record-voicesamplein"></a>

### VoiceSampleIn

A voice to hear before it is picked.

- `agent` (string | null): Say this agent's own opening, when it has one
- `language` (string, required): Up to 8 characters.
- `voice` (string, required): An id from the agents' voice_pool Up to 100 characters.

<a id="record-zendeskaudience"></a>

### ZendeskAudience

Who some of the help center's articles are for: a user segment, or everyone.

- `articles` (integer, required)
- `name` (string, required): The segment's name in Zendesk; empty for everyone, or when Zendesk won't list segments.
- `ref` (string, required)

<a id="record-zendeskaudiences"></a>

### ZendeskAudiences

- `audiences` ([ZendeskAudience](#record-zendeskaudience)[], required)
- `picked` (string[]): The refs picked.

<a id="record-zendeskkeyin"></a>

### ZendeskKeyIn

A Zendesk account and an API token its admin made, with the email it signs in as.

- `address` (string, required): Up to 300 characters.
- `email` (string, required): Someone who can see the articles. Up to 320 characters.
- `token` (string, required): The API token, as Zendesk showed it. Up to 500 characters.

<a id="record-zendesksigninin"></a>

### ZendeskSignInIn

The Zendesk account to sign in to: its address, where the owner approves Solacia.

- `address` (string, required): Up to 300 characters.

Example lead record (`GET /v1/leads/{id}`):

```json
{
  "schema": "solacia.lead.v1",
  "event": "lead.snapshot",
  "at": "2026-10-14T15:02:55.000+00:00",
  "product": "halden",
  "vendor": "Halden",
  "session": "web-7f3a9c",
  "link": "https://app.solacia.ai/halden/console/outcomes?id=web-7f3a9c",
  "test": false,
  "contact": {
    "email": "maya.chen@arbor.example",
    "company": "Arbor",
    "role": "VP Finance"
  },
  "campaign": "Finance leaders Q4",
  "network": null,
  "source": {
    "utm": {},
    "campaign": "CFOs Mexico Q4",
    "channel": "outbound",
    "click_id": null,
    "click_ids": {},
    "arrival_url": "https://demo.solacia.ai/clara/",
    "arrived_at": null,
    "embedded": false,
    "landing_page": "https://demo.solacia.ai/clara/",
    "referrer": null,
    "first_touch": null,
    "last_touch": {
      "page": "https://demo.solacia.ai/clara/",
      "referrer": null,
      "utm": {},
      "click_id": null,
      "channel": "direct",
      "at": null
    }
  },
  "priority": "hot",
  "fit": null,
  "reasons": [
    {
      "text": "Asked to talk to the team",
      "tone": "intent"
    }
  ],
  "stages": [
    "email",
    "asked",
    "team"
  ],
  "facts": [],
  "seen": [],
  "questions": [
    {
      "question": "Can it forecast by region?",
      "answer": "Yes. Forecasts split by any region you define, and each region's plan updates daily.",
      "answered": true,
      "channel": "call",
      "at": "2026-10-14T15:02:10.000+00:00"
    },
    {
      "question": "Does it read our NetSuite subsidiaries?",
      "answer": null,
      "answered": false,
      "channel": "call",
      "at": "2026-10-14T15:02:30.000+00:00"
    }
  ],
  "concerns": [],
  "team_request": {
    "requested": true,
    "slot": "2026-10-16T15:00:00-04:00",
    "booked": null
  },
  "next_meeting": [
    "Show a forecast for each region: on their agenda, not reached",
    "Find out how many subsidiaries they consolidate, when they need it live and who else decides"
  ],
  "follow_up": {
    "subject": "Forecasts by region, and your next step with Halden",
    "body": "Hi Maya,\n\nThanks for touring Halden today. ..."
  },
  "activity": {
    "first_at": "2026-10-14T15:02:10.000+00:00",
    "last_at": "2026-10-14T15:02:50.000+00:00",
    "minutes": 0.7
  },
  "number": 7,
  "transcript": null,
  "calls": [
    {
      "voice": null,
      "model": null,
      "started_at": "2026-10-14T15:02:05.000+00:00",
      "minutes": 4.2,
      "ended": "goodbye"
    }
  ],
  "deals": null
}
```

## MCP tools

### get_buyer

One buyer's full record by the `id` find_buyers gives: who they are, priority and why, what they saw and asked with the answers, concerns, meeting request and the drafted follow-up. include=transcript adds the conversation; include=calls adds the voice calls; include=deals adds their deals in the CRM, won, lost or open. The caller's account only; test demos are left out unless asked for. Calls `GET /v1/leads/{id}`, scope `leads:read`.

- `id` (string, required)
- `include` (string): Comma-separated: transcript, calls, deals. Up to 40 characters.

### find_buyers

The buyers who took a demo in the last `days` days, one short row each: who they are, company, outcome (meeting, qualified, nurture, anonymous), fit, three facts, their main question, how far they went and when. `q` keeps the buyers whose name, company, role or anything they said holds every word. order=promising puts meetings and qualified buyers first. Pass a row's `id` to get_buyer for the full record. For the rows after these, pass the answer's `next_cursor` as `cursor`. The caller's account only; test demos are left out unless asked for. Calls `GET /v1/buyers`, scope `demos:read`.

- `cursor` (string): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `days` (integer): Demos that began in the last `days` days, today included. 1 to 365. Default `30`.
- `language` ("en" | "es" | "pt"): The language the rows' roles and facts are written in: English, Spanish or Portuguese. Default `"en"`.
- `limit` (integer): At most this many buyers; 0 for all of them. 0 to 500. Default `20`.
- `order` ("newest" | "promising"): newest: by their latest demo. promising: meetings first, then qualified, nurture and no email, each by score. Default `"promising"`.
- `q` (string): Only the buyers whose name, address, company, role, or anything they said or told the demo (calls included) holds every word of it; case and accents don't matter. Up to 120 characters.
- `tests` (boolean): Default `false`.

### edit_follow_up

Replace the follow-up email drafted for a buyer (the `id` find_buyers gives) with this subject and body, kept as the person's edit. Nothing is sent: the team sends it. Given only a change, read the draft with get_buyer first and keep the rest. Calls `PUT /v1/demos/{id}/follow-up`, scope `leads:write`.

- `body` (string, required): Up to 10000 characters.
- `id` (string, required)
- `subject` (string, required): Up to 300 characters.

### list_questions

Questions buyers asked in demos, newest first, each with the agent's answer and how well it was answered. `q` keeps questions holding those words; answered=false keeps the ones it could not answer. For those grouped, with how often each was asked, use list_unanswered_questions. The caller's account only; test demos are left out unless asked for. Calls `GET /v1/questions`, scope `demos:read`.

- `answered` (boolean): true: answered from a source or in the call; false: not.
- `cursor` (string): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `fresh` (boolean): Default `false`.
- `limit` (integer): 1 to 200. Default `20`.
- `q` (string): Up to 200 characters.
- `since` (string): Only demos active at or after this time, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Up to 40 characters.
- `tests` (boolean): Default `false`.

### list_unanswered_questions

Questions the agent could not answer from the vendor's own sources, grouped, most asked first, with how many times and what the agent said instead. status=closed lists the ones the team has answered since; dismissed, the ones it set aside. For the rows after these, pass the answer's `next_cursor` as `cursor`. Calls `GET /v1/gaps`, scope `demos:read`.

- `cursor` (string): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `fresh` (boolean): Default `false`.
- `language` ("en" | "es" | "pt"): The language who asked is described in: English, Spanish or Portuguese. Default `"en"`.
- `limit` (integer): At most this many questions; 0 for all of them. 0 to 500. Default `20`.
- `status` ("open" | "closed" | "dismissed" | "all"): Default `"open"`.

### answer_question

Give the agent the team's answer to a question it could not answer (a `key` list_unanswered_questions gives); from then on it tells every buyer who asks. Write only what the person said buyers should be told, never an answer you made up, and show it to them first. Calls `POST /v1/gaps/answer`, scope `gaps:write`.

- `answer` (string, required): What buyers should be told, as the team would say it: facts only, no quotes. Up to 2000 characters.
- `key` (string, required): The gap's key Up to 2000 characters.

### dismiss_question

Set aside a question the agent could not answer (a `key` list_unanswered_questions gives): a wrong flag, a test, or something the team never tells buyers. It leaves the open list and the agent's answers stay as they are; dismissed=false brings it back. Calls `POST /v1/gaps/dismiss`, scope `gaps:write`.

- `dismissed` (boolean): false restores it to the open list Default `true`.
- `key` (string, required): The gap's key Up to 2000 characters.
- `reason` ("unpublished"): unpublished: the vendor deliberately doesn't publish this (a margin, a custom price), so the agent keeps handing it to the team (ADR 0009)

### get_numbers

The demos' numbers for the last `days` days against the period before: sessions, calls, minutes, goals reached, conversion, the funnel, and the topics buyers asked about most. Calls `GET /v1/analytics`, scope `demos:read`.

- `days` (integer): 1 to 365. Default `30`.
- `demos` (boolean): false leaves out each demo's row and the demos behind each question: the numbers alone. Default `false`.
- `fresh` (boolean): Default `false`.
- `tests` (boolean): Default `false`.

### list_integrations

Which tools this account has connected and how: its CRM (HubSpot, Salesforce), scheduler, Slack, email alerts, internal docs, the website embed and API keys, each connected or not, with what and by whom, and the CRM and scheduler buyers go to. Connecting one is done in the console. Calls `GET /v1/integrations`, scope `integrations:read`.

- `language` ("en" | "es" | "pt"): The language its words are in. Default `"en"`.

### get_website_embed

The script tag that puts this account's live demo on its own website, ready to paste into the site's HTML before </body>, with the sites it answers on and whether it is paused. An empty list: Solacia has not made the account's embed yet. Calls `GET /v1/embed`, scope `None`.

None.

### list_agents

The account's demo agents: what each says and how (tone, instructions, facts, voices), which channel each runs (the website, outreach links, the demo's own address) and the rules that pick one, its last 30 days, and the A/B tests between them. Pass an agent's `id` to get_agent for its versions, draft and script. Calls `GET /v1/agents`, scope `agents:read`.

None.

### get_agent

One agent (an `id` list_agents gives): its live version and unpublished draft, every version with who changed what, the script a buyer meets (opening, parts, buttons), the questions it couldn't answer, where it runs, and the team's notes on its calls. Calls `GET /v1/agents/{id}`, scope `agents:read`.

- `id` (string, required)

### change_agent

Change an agent's draft (an `id` list_agents gives): how it talks, its instructions, facts, who it's for, its goal and its script. Only the fields given change; buyers keep meeting the live version until publish_agent. Change only what the person asked for in their own words, never what a buyer said in a demo. Calls `PUT /v1/agents/{id}/draft`, scope `agents:admin`.

- `audience` (string): Up to 200 characters.
- `counts` ("qualified" | "meeting"): What reaching the goal is: the buyer qualifies, or asks to meet the team
- `facts` ([AgentFact](#record-agentfact)[]): Replaces all its facts
- `goal` (string): Up to 200 characters.
- `id` (string, required)
- `instructions` (string): Up to 1000 characters.
- `script` ([AgentScriptIn](#record-agentscriptin))
- `tone` ("brief" | "warm" | "expert" | "pack"): pack: as the brief says
- `voices` (object<string, string>): Voice id per language; Solacia only

### publish_agent

Make an agent's draft its live version: every demo that starts from now on meets it. Show the person what changed (get_agent) and publish only when they say so. Calls `POST /v1/agents/{id}/draft/publish`, scope `agents:admin`.

- `id` (string, required)

### test_agent

Split real buyers between an agent's live version (side A) and its draft or other versions, each buyer always on the same side, and read which qualifies more of them. Shares add to 100, at least 10 each. Calls `POST /v1/agents/{id}/tests`, scope `agents:admin`.

- `id` (string, required)
- `lever` ("message" | "features" | "pricing" | "offer" | "qualification"): What it is to learn (GET /agents/{id}/levers): it is read on that lever's goal
- `min_buyers` (integer): Buyers each side needs before any verdict 20 to 100000. Default `20`.
- `question` (string): Up to 200 characters.
- `rule` ("unless_worse" | "proven"): unless_worse: a challenger may go live unless it is worse; proven: only once it is proven better Default `"unless_worse"`.
- `sides` ([VersionSideIn](#record-versionsidein)[], required)
- `weeks` (integer): How long it takes buyers; left out: until stopped 1 to 26.

### rehearse_agent

A link to a demo of an agent's draft (or one of its versions) for the person to run as a buyer would, before publishing. Never counted in results; nothing in it reaches the team or the CRM. Calls `POST /v1/agents/{id}/rehearsals`, scope `agents:admin`.

- `id` (string, required)
- `of` (integer | "draft"): A version's number, or the draft as it is now Default `"draft"`.

### stop_agent_test

Stop an A/B test (an `id` list_agents gives under tests). With `keep`, that agent, or that side's version, runs the channel from the next demo. Calls `POST /v1/agent-tests/{id}/stop`, scope `agents:admin`.

- `id` (string, required)
- `keep` (string): The agent to run the channel from now on; in a test between an agent's versions, the side (A, B or C) whose version goes live Up to 80 characters.

### make_demo_links

Make a personal demo link for each prospect: a work email, and their name, company, role and what the rep knows, which the agent reads before the demo. Each link opens the demo without a password and records it under that prospect. Nothing is sent: give the links back to the person. Rows that are not a work email come back refused. Calls `POST /v1/demo-links/batch`, scope `links:write`.

- `rows` ([DemoLinkIn](#record-demolinkin)[], required): Up to 500 prospects.

### list_crm_lists

The lists in the account's CRM that demo links can be made for (HubSpot contact lists, Salesforce campaigns), with how many people each holds. Pass a list's `id` to make_crm_list_links. Calls `GET /v1/crm/lists`, scope `links:write`.

- `q` (string): Words in the list's name. Up to 80 characters.

### make_crm_list_links

Make a personal demo link for each person on a CRM list (a `list_id` list_crm_lists gives) and write it onto their CRM record, where the team's own sequence picks it up. Nothing is sent to anyone. One page per call: call again with `after` set to the answer's `next` until it is empty. Calls `POST /v1/demo-links/from-crm-list`, scope `links:write`.

- `after` (string): Where this page starts: the last answer's `next`. Up to 256 characters.
- `agent` (string): The agent they meet; left out: the sender's default. Up to 80 characters.
- `campaign` (string): Up to 80 characters.
- `days` (integer): How long the links open the demo. 1 to 90. Default `30`.
- `list_id` (string, required): Up to 64 characters.

### list_demo_links

The personal demo links made so far, newest first: who each is for, the link, and what that prospect has done since (demos, how hot, whether they asked for your team), with what each campaign has brought over all its links. For the rows after these, pass the answer's `next_cursor` as `cursor`. Calls `GET /v1/demo-links`, scope `links:write`.

- `campaign` (string): Only this campaign's links; an empty value, those without one. Up to 80 characters.
- `cursor` (string): The previous page's next_cursor; empty for the first page. Up to 2000 characters.
- `limit` (integer): At most this many links, newest first; 0 for all of them. 0 to 500. Default `20`.

## Files

- [openapi.v1.json](/docs/openapi.v1.json)
- [mcp.v1.json](/docs/mcp.v1.json)
- [examples/lead.v1.json](/docs/examples/lead.v1.json)
