# Quickstart

Create an API key, check it, and read the action items from your latest call. Three requests.

Source: https://docs.itsconvo.com/

API Base URL: https://www.itsconvo.com/api/v1

You need the [Convo desktop app](https://www.itsconvo.com) on a Starter plan or above. The API is at `https://www.itsconvo.com/api/v1`.

<span id="get-your-api-key" className="block scroll-mt-24" aria-hidden="true" />

## 1. Create an API key

1. Open the desktop app and go to **Settings → Convo API**.
2. Click **Create key**, give the key a name and accept the API Terms of Use.
3. Copy the key. It is shown only once.

The examples read the key from `CONVO_API_KEY`. Keep it on your server. More in [Authentication](/authentication).

```bash
export CONVO_API_KEY="convo_..."
```

<span id="make-your-first-request" className="block scroll-mt-24" aria-hidden="true" />

## 2. Check your key

Call `GET /user/profile` to check your key and see your profile, plan and AI credit usage.

<Tabs items={["curl", "JavaScript", "Python"]}>
<Tab value="curl">
```bash
curl https://www.itsconvo.com/api/v1/user/profile \
  -H "Authorization: Bearer $CONVO_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```javascript
const API = "https://www.itsconvo.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CONVO_API_KEY}` };

const { data: profile } = await (await fetch(`${API}/user/profile`, { headers })).json();
console.log(profile.subscription.tier);
```
</Tab>
<Tab value="Python">
```python
import os
import requests

API = "https://www.itsconvo.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CONVO_API_KEY']}"}

profile = requests.get(f"{API}/user/profile", headers=headers).json()["data"]
print(profile["subscription"]["tier"])
```
</Tab>
</Tabs>

<span id="see-the-response" className="block scroll-mt-24" aria-hidden="true" />

```json
{
  "data": {
    "profile": { "name": "Alice Chen", "email": "alice@example.com" },
    "subscription": { "tier": "professional", "status": "active" },
    "apiUsage": { "aiGenerations": { "used": 1240, "limit": 15000, "remaining": 13760, "resetsAt": "2026-04-01T00:00:00.000Z" } }
  }
}
```

This response is shortened. Rate limit headers, including `X-RateLimit-Remaining`, are included in the response. A `401` means the key is wrong or the `Bearer ` prefix is missing. See [Error Codes](/errors).

## 3. Find your latest call

Calls come newest first.

<Tabs items={["curl", "JavaScript", "Python"]}>
<Tab value="curl">
```bash
curl "https://www.itsconvo.com/api/v1/conversations?limit=1" \
  -H "Authorization: Bearer $CONVO_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```javascript
const { data: calls } = await (await fetch(`${API}/conversations?limit=1`, { headers })).json();
const callId = calls[0].id;
```
</Tab>
<Tab value="Python">
```python
calls = requests.get(f"{API}/conversations", params={"limit": 1}, headers=headers).json()["data"]
call_id = calls[0]["id"]
```
</Tab>
</Tabs>

```json
{
  "data": [
    {
      "id": "session_1773842400000",
      "title": "Acme pilot pricing call",
      "startTime": "2026-03-18T14:00:00.000Z",
      "endTime": "2026-03-18T14:45:00.000Z",
      "duration": 45,
      "segmentCount": 187
    }
  ],
  "pagination": { "total": 42, "limit": 1, "offset": 0 }
}
```

## 4. Read its action items

<Tabs items={["curl", "JavaScript", "Python"]}>
<Tab value="curl">
```bash
curl https://www.itsconvo.com/api/v1/conversations/session_1773842400000/keypoints \
  -H "Authorization: Bearer $CONVO_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```javascript
const { data: keyPoints } = await (await fetch(`${API}/conversations/${callId}/keypoints`, { headers })).json();
console.log(keyPoints.keypoints.actionItems);
```
</Tab>
<Tab value="Python">
```python
key_points = requests.get(f"{API}/conversations/{call_id}/keypoints", headers=headers).json()["data"]
print(key_points["keypoints"]["actionItems"])
```
</Tab>
</Tabs>

```json
{
  "data": {
    "id": "session_1773842400000",
    "title": "Acme pilot pricing call",
    "keypoints": {
      "decisions": ["Start a two-team pilot in April"],
      "actionItems": [
        { "item": "Send the pilot pricing to Sarah", "owner": "Alice", "confidence": 0.95, "priority": "high" }
      ]
    },
    "createdAt": "2026-03-18T14:47:10.000Z"
  }
}
```

This response is shortened. The app generates key points after each call. If a call has none yet, you get a `404`. `POST` to the same path generates them, for free.

## What's Next?

<Cards>
  <Card icon={<MessagesSquare aria-hidden="true" />} title="List Conversations" description="Fetch your recent meetings and their metadata." href="/api-reference/conversations/list-conversations" />
  <Card icon={<FileText aria-hidden="true" />} title="Get a Transcript" description="Retrieve the full speaker-attributed transcript for any meeting." href="/api-reference/conversations/get-transcript" />
  <Card icon={<DocsSparkles aria-hidden="true" />} title="Generate Key Points" description="Get an AI-generated summary with decisions and action items." href="/api-reference/a-i--generation/generate-keypoints" />
  <Card icon={<Blocks aria-hidden="true" />} title="Core Concepts" description="Understand the data model before building your integration." href="/core-concepts" />
  <Card icon={<Webhook aria-hidden="true" />} title="Webhooks" description="Get a signed request when a call's key points are ready." href="/webhooks" />
  <Card icon={<MCPIcon aria-hidden="true" />} title="MCP Server" description="Ask Claude, ChatGPT or Cursor about your calls." href="/mcp" />
</Cards>

---

# Introduction

What Convo does on a sales call, what the API gives you, and how requests and responses look.

Source: https://docs.itsconvo.com/introduction

API Base URL: https://www.itsconvo.com/api/v1

## What is Convo?

Convo is a real-time AI sales assistant. It helps sales reps recognise buying signals, handle objections and ask the right questions while the conversation is happening.

The API gives your code what Convo keeps from each call: the transcript, key points, coaching feedback, a follow-up email and briefings on the people you meet. Use it to put that into your CRM, your reports or your own agents.

<Cards>
  <Card icon={<DocsSparkles aria-hidden="true" />} title="Live help on calls" description="Spots buying signals and objections, and shows the rep what to ask or say next." />
  <Card icon={<Blocks aria-hidden="true" />} title="Memory" description="Remembers each contact across calls and briefs you before the next one." />
  <Card icon={<ChartNoAxesCombined aria-hidden="true" />} title="Coaching" description="Scores each call on the moments that mattered, with a line to try next time." />
  <Card icon={<Plug aria-hidden="true" />} title="Follow-up" description="Drafts the follow-up email and sends call data to Zapier, Make, IFTTT or your own code." />
</Cards>

[Features](/features) describes the app. [Core Concepts](/core-concepts) describes the API's objects.

## From call to API

1. **Record.** The desktop app transcribes the call as it happens. No bot joins the meeting.
2. **Save.** When the call ends, the app saves it and sends `conversation.created`.
3. **Summarise.** The app generates key points: topics, decisions and action items with owners. `conversation.keypoints.ready` follows.
4. **Use.** Read the call with the API, react to [webhooks](/webhooks), or ask your AI assistant about it through the [MCP server](/mcp).

## Get started

<Cards>
  <Card icon={<Rocket aria-hidden="true" />} title="Quickstart" description="Create an API key and make your first request." href="/" />
  <Card icon={<BookOpen aria-hidden="true" />} title="API Reference" description="Every endpoint with its parameters and examples." href="/api-reference" />
  <Card icon={<FileText aria-hidden="true" />} title="Core Concepts" description="Calls, transcripts, key points, feedback and contacts." href="/core-concepts" />
  <Card icon={<MCPIcon aria-hidden="true" />} title="MCP Server" description="Ask Claude, ChatGPT or Cursor about your calls." href="/mcp" />
</Cards>

<span id="convo-api-v1" className="block scroll-mt-24" aria-hidden="true" />

## Base URL

```
https://www.itsconvo.com/api/v1
```

For example, to list your calls: `GET https://www.itsconvo.com/api/v1/conversations`. Every request needs an [API key](/authentication).

## Response format

A successful response puts its result in `data`. Paged lists also return `pagination`. An error response has an `error` object with `code` and `message` ([Error Codes](/errors)).

<Tabs items={["Success", "Error"]}>
<Tab value="Success">
```json
{ "data": { ... } }
```
</Tab>
<Tab value="Error">
```json
{ "error": { "code": "not_found", "message": "Conversation not found" } }
```
</Tab>
</Tabs>

<Callout>
The API is versioned at `v1`. New fields can appear without a new version, so ignore keys you don't know. Breaking changes come only in a new version, with 90 days' notice.
</Callout>

## Support

Write to [ivan@itsconvo.com](mailto:ivan@itsconvo.com). By using the API you agree to the [API Terms of Use](https://www.itsconvo.com/terms/api).

---

# Features

What Convo does before, during and after a sales call, and which parts the API gives you.

Source: https://docs.itsconvo.com/features

API Base URL: https://www.itsconvo.com/api/v1

## During the call

Convo listens to both sides of the call on the rep's computer and shows what matters in a small window that only the rep sees.

- When the buyer mentions budget, timing or another buying signal, Convo suggests the question to ask next.
- When an objection lands, or the buyer asks about pricing or a feature, it shows an answer from your uploaded documents and past calls.
- About five minutes before a calendar-linked meeting ends, it reminds the rep of the must-ask questions still open.
- When the rep has done most of the talking for a couple of minutes, it suggests listening more.

It works with Zoom, Google Meet, Microsoft Teams, Webex, Slack and any other app that plays audio on the computer. No bot joins the meeting, and the window is hidden from screen sharing on macOS and Windows. It transcribes English, Spanish, French, German, Portuguese, Italian and Polish, and can detect the language.

In the API: the call's [transcript](/api-reference/conversations/get-transcript).

## After the call

The app saves the call and generates key points: the topics discussed, decisions, important dates and action items with an owner and a priority. Transcripts are available right after the call ends and are fully searchable from the Convo dashboard.

Coaching feedback scores the rep from 0 to 10 in five categories:

| Category | What it measures |
|----------|-----------------|
| Clarity | How clearly the rep communicated their points |
| Listening | Engagement and responsiveness |
| Time Management | How well the call stayed on track |
| Collaboration | Interaction and inclusivity |
| Decision Making | Progress toward clear outcomes |

Feedback needs at least 10 transcript segments. Each strength and growth area quotes what the rep said, and each growth area adds a line they could have said instead. On Professional and Enterprise, a growth area can be saved as a cue, so it comes back as live help on the next call.

A follow-up email can be drafted from the call in a professional, casual or concise tone, with a subject line, the key points and the action items.

In the API: [key points](/api-reference/conversations/get-keypoints), [feedback](/api-reference/conversations/get-feedback), [questions about a call](/api-reference/a-i--generation/query-conversation) and [follow-up emails](/api-reference/a-i--generation/generate-email).

## Before the next call

With Convo Memory (Professional and Enterprise), Convo links calls to the people in your calendar meetings. Before the next call with someone, it briefs the rep on what was discussed, what is still open and what was decided.

In the API: the [contacts endpoints](/api-reference/contacts/list-contacts).

## Integrations

- **Calendars:** Google Calendar and Outlook, for meeting detection and briefings.
- **CRMs:** HubSpot, Salesforce, Pipedrive and Attio.
- **Notes and chat:** Notion and Slack.
- **Automation:** Zapier (triggers for new meetings, summaries and feedback; actions that generate summaries and emails, share a meeting or rename it), IFTTT (a trigger when a summary is ready, queries for meetings, summaries and feedback, and actions that generate summaries and emails or share a meeting) and Make.
- **Your own code:** the [REST API](/api-reference), [webhooks](/webhooks) (Professional and Enterprise) and the [MCP server](/mcp).

## Privacy

- Audio is captured on the rep's computer, with no bot in the call. It is sent only to Convo's transcription providers, which delete it after processing and don't train on it.
- Data is encrypted in transit and at rest, with AES-256 at rest.
- Your conversations are never used to train AI models.
- The desktop app runs on macOS, Windows and Linux.

---

# Core Concepts

The objects in the Convo API, how they fit together, and which endpoints return them.

Source: https://docs.itsconvo.com/core-concepts

API Base URL: https://www.itsconvo.com/api/v1

Most objects belong to a call, which the API calls a conversation.

| Object | What it is | Endpoints |
|--------|------------|-----------|
| Conversation | One recorded call | [List](/api-reference/conversations/list-conversations), [rename](/api-reference/conversations/update-conversation), [share](/api-reference/conversations/share-conversation), [delete](/api-reference/conversations/delete-conversation) |
| Transcript | The call's text, in segments | [Get transcript](/api-reference/conversations/get-transcript) |
| Key points | Topics, decisions, action items, participants and dates | [Get](/api-reference/conversations/get-keypoints), [generate](/api-reference/a-i--generation/generate-keypoints) |
| Feedback | Coaching on the rep's side of the call | [Get](/api-reference/conversations/get-feedback), [generate](/api-reference/a-i--generation/generate-feedback) |
| Answers and emails | Generated from one call on request | [Ask a question](/api-reference/a-i--generation/query-conversation), [draft an email](/api-reference/a-i--generation/generate-email) |
| Contact | A person from your calendar meetings, with Convo Memory | [List](/api-reference/contacts/list-contacts), [briefing](/api-reference/contacts/get-contact-briefing), [open action items](/api-reference/contacts/list-unresolved-threads) |
| Calendar event | An upcoming Google or Outlook event | [List](/api-reference/calendar/list-calendar-events) |
| Webhook | A URL that receives signed events | [Webhooks](/webhooks) |

## Conversations

A conversation is one recorded call. Its `id` is the key for everything about the call.

```json
{
  "id": "session_1773842400000",
  "title": "Acme pilot pricing call",
  "startTime": "2026-03-18T14:00:00.000Z",
  "endTime": "2026-03-18T14:45:00.000Z",
  "duration": 45,
  "segmentCount": 187
}
```

- `title` comes from the key points, so it is `null` until they exist.
- `duration` is the minutes between the first and the last segment.
- `segmentCount` tells you how many transcript segments are available.

## Transcripts

The transcript is recorded during the call, in segments. `speaker` is `local` for the rep, from their microphone. Other people are usually `remote`.

```json
{
  "segments": [
    { "text": "What would a pilot cost for two teams?", "speaker": "remote", "timestamp": "2026-03-18T14:01:12.000Z" },
    { "text": "For two teams we'd start at the Professional plan.", "speaker": "local", "timestamp": "2026-03-18T14:01:18.000Z" }
  ]
}
```

## Key points

The desktop app generates key points after each call.

| Field | Contents |
|-------|----------|
| `sections` | Topics, each with a `heading` and `points` |
| `decisions` | What was decided |
| `actionItems` | `item`, `owner`, `priority` (`high`, `medium` or `low`) and `confidence` (0 to 1) |
| `participants` | Names mentioned in the call |
| `importantDates` | `date` and `context` |

`GET` returns them. `POST` generates them when they are missing, or again with `forceRefresh: true`. Both are free.

## Feedback

Feedback coaches the rep on their side of the call.

| Field | Contents |
|-------|----------|
| `overallScore` | 0 to 10 |
| `categoryScores` | `clarity`, `listening`, `timeManagement`, `collaboration` and `decisionMaking`, each 0 to 10 |
| `topPriority` | The one change to make before the next call, with the moment it comes from and a line to say instead. Missing on short or routine calls. |
| `strengths`, `growthAreas` | Moments with the rep's own words, a timestamp and why they mattered. Growth areas add a `suggestion` and an `alternative` line. |
| `talkListenRatio` | Talk-to-listen ratio as a percentage |
| `actionPlan` | Three to five concrete steps |

Generating feedback needs at least 10 transcript segments and uses one [AI credit](/tiers#ai-credits). So do questions and emails. Key points and every `GET` are free.

## Contacts

With [Convo Memory](/tiers#convo-memory), Convo links calls to the people in your calendar meetings. A briefing on a contact holds the relationship summary, recent meetings, open action items and recent decisions. Open action items across all contacts come from `GET /contacts/unresolved-threads`, oldest first.

## Calendar events

Upcoming events from the Google or Outlook calendar connected in the desktop app, with attendees, times and time zones, in the provider's own format.

## Webhooks

A webhook sends a signed `POST` to your URL when a call is saved, its key points or feedback are ready, or it is shared, renamed or deleted. See [Webhooks](/webhooks).

---

# MCP Server

Connect Claude, ChatGPT and Cursor to your Convo calls. Sign in with OAuth, or run the local server with an API key.

Source: https://docs.itsconvo.com/mcp

API Base URL: https://www.itsconvo.com/api/v1

Ask your AI assistant what a contact raised last time, which follow-ups are still open, or what to send after today's demo. Convo's [Model Context Protocol](https://modelcontextprotocol.io) server gives it your calls, key points, feedback and contacts.

```
https://www.itsconvo.com/api/mcp
```

- **Hosted.** Claude, ChatGPT and Cursor sign in through the browser with OAuth. There is nothing to install. Other clients can send an API key as a Bearer header.
- **Local.** The npm package `@itsconvo/mcp-server` runs on your computer with an API key. It adds tools that answer questions, draft emails and share calls.
- **Plans.** Both need Starter or above. The two Convo Memory tools need Professional or Enterprise with [Memory](/tiers#convo-memory) turned on.

## What you can do

- Search and browse your meeting history
- Read full transcripts with speakers and timestamps
- Get summaries with key points, decisions and action items
- Ask any question about a specific meeting
- Draft follow-up emails that reference actual discussion points
- Prepare for upcoming meetings by reviewing all past interactions with a person or company
- Get a weekly digest of all meetings, decisions and action items
- Find all open action items across your meetings, filtered by owner

## Connect

For Claude Web, ChatGPT or Cursor's hosted connection, you don't need an API key or the npm package. Sign in through OAuth in the matching tab. The API key and npm steps are only for the [local server](#local-server).

<Tabs items={["Claude Web", "Claude Desktop", "Claude Code", "Cursor", "ChatGPT", "Other clients"]}>
<Tab value="Claude Web">

Claude on the web (claude.ai) connects through OAuth. No API key or npm install needed.

1. In Claude, open **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Name it **Convo** and enter `https://www.itsconvo.com/api/mcp`. Leave the advanced OAuth fields empty and click **Add**.
4. Click **Connect** and sign in to Convo with your email and password, or with Google.

To try it, start a new chat and ask "What meetings did I have this week?" Enable Convo from the chat's **+ → Connectors** menu if needed.

The connector is available across your Claude account, including Claude Desktop. Claude Free supports one custom connector; paid plans also support custom connectors. Convo needs Starter or above.

On Claude Team or Enterprise, an Owner or Primary Owner first adds the connector under **Organization settings → Connectors → Add → Custom → Web**. Members then find Convo in **Customize → Connectors** and connect their own account. See Claude's [custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
</Tab>
<Tab value="Claude Desktop">

Use the custom connector from the **Claude Web** tab. It syncs to Claude Desktop automatically.

To use the local server with your own API key instead, follow [Local server](#local-server) and add the configuration to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Restart Claude Desktop after saving.
</Tab>
<Tab value="Claude Code">

Connect the hosted server with an API key:

```bash
claude mcp add --transport http convo https://www.itsconvo.com/api/mcp \
  --header "Authorization: Bearer $CONVO_API_KEY"
```

Or run the [local server](#local-server):

```bash
claude mcp add convo -e CONVO_API_KEY=$CONVO_API_KEY -- convo-mcp
```
</Tab>
<Tab value="Cursor">

For a hosted connection, add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` inside one project:

```json
{
  "mcpServers": {
    "convo": {
      "url": "https://www.itsconvo.com/api/mcp"
    }
  }
}
```

Open Cursor's **Customize** page, find Convo and complete the browser sign-in. Enable Convo and start a new chat or agent session. No npm install or manually copied key is needed. You need Convo Starter or above.

If you prefer a static key for the hosted server, add `"headers": { "Authorization": "Bearer convo_..." }` beside `url`.

For the additional local tools listed below, complete the [local server](#local-server) steps and use its `convo-mcp` configuration instead. Restart Cursor after saving the local configuration. See [Cursor's MCP guide](https://cursor.com/docs/mcp).
</Tab>
<Tab value="ChatGPT">

Convo is not currently listed in ChatGPT's public plugin directory. Add it manually through Developer mode.

You need **Convo Starter or above** and access to **Developer mode in ChatGPT on the web**. OpenAI currently lists Plus, Pro, Business, Enterprise and Education as eligible. Workspace permissions may require an administrator.

1. In ChatGPT, open **Settings**, select **Security and login**, and enable **Developer mode**.
2. Open [ChatGPT Plugins](https://chatgpt.com/plugins) and select the **plus button** to add your own connection.
3. Name it **Convo** and enter `https://www.itsconvo.com/api/mcp` as the MCP server URL. Choose **OAuth**. If asked for a registration method, use **Dynamic Client Registration (DCR)**; no manually supplied client ID or secret is needed.
4. Complete the connection flow, sign in to Convo when prompted, and review the requested access and discovered tools.
5. Open Convo in your [personal plugins](https://chatgpt.com/plugins?view=personal) and install it. Start a new **Work** chat, type **@**, and select **Convo**.

If your interface uses developer-mode apps, select Convo from the chat's plus menu under **Developer mode** instead. If Developer mode or the add button is missing, check your ChatGPT plan and workspace permissions.

No local server installation or manually copied Convo API key is needed.

To check the connection, ask: "Summarize my most recent Convo meeting and its action items."

See OpenAI's [Developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode) for access requirements and its [plugin quickstart](https://developers.openai.com/plugins/quickstart) for the personal-plugin installation steps.
</Tab>
<Tab value="Other clients">

Point the client at `https://www.itsconvo.com/api/mcp` (streamable HTTP). If it supports MCP authorization, it signs you in through the browser. Otherwise, send `Authorization: Bearer convo_...` with a key from **Settings → Convo API** in the desktop app.
</Tab>
</Tabs>

## Local server

The local server calls the [REST API](/api-reference) with your API key, so its requests count against your [rate limit](/rate-limits).

1. Create a key in the [Convo desktop app](https://www.itsconvo.com) under **Settings → Convo API**. It starts with `convo_` and is shown only once.
2. Install the server. It needs Node.js 18 or later.

   ```bash
   npm install -g @itsconvo/mcp-server
   ```

3. Add it to your client. For Claude Desktop, edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows, then restart Claude Desktop. Cursor takes the same block in `mcp.json`; restart Cursor after saving.

   ```json
   {
     "mcpServers": {
       "convo": {
         "command": "convo-mcp",
         "env": { "CONVO_API_KEY": "convo_..." }
       }
     }
   }
   ```

If the client can't find `convo-mcp`, which happens when Node is installed with a version manager such as nvm, use `"command": "npx"` with `"args": ["-y", "@itsconvo/mcp-server"]` instead.

## Tools

The hosted server has 9 read-only tools. The local server has all 14.

| Tool | What it does | Parameters | Server |
|------|--------------|------------|--------|
| `meetings_list` | Lists calls, newest first | `limit` (1–100, default 20), `search` (title or transcript), `since` (ISO 8601) | Both |
| `meetings_get_transcript` | Returns a call's transcript | `meeting_id` | Both |
| `meetings_get_summary` | Returns key points: topics, decisions, action items. Local generates missing ones, for free. Hosted returns saved ones only. | `meeting_id` | Both |
| `meetings_get_feedback` | Returns coaching feedback. Local generates missing feedback for one AI credit. Hosted returns saved feedback only. | `meeting_id` | Both |
| `meetings_ask` | Answers a question about one call, for one AI credit | `meeting_id`, `question` (up to 500 characters) | Local |
| `meetings_draft_email` | Drafts a follow-up email, for one AI credit | `meeting_id`, `recipient_name`, `tone` (`professional`, `casual` or `concise`) | Local |
| `meetings_share` | Creates a public link to a call | `meeting_id` | Local |
| `calendar_upcoming` | Lists upcoming Google or Outlook events | `max_results` (1–50, default 10) | Local |
| `account_info` | Shows your plan and AI credit usage | none | Local |
| `intelligence_prepare` | Briefs you from past calls that match a person, company or topic, with open action items and decisions | `search`. Local also takes `max_past_meetings` (1–20, default 10). | Both |
| `intelligence_weekly_digest` | Sums up calls over a period: total meeting time, all decisions and all action items | `days` (1–90, default 7) | Both |
| `intelligence_find_action_items` | Finds action items across recent calls | `days` (1–90, default 14), `owner` | Both |
| `intelligence_prepare_for_contact` | Returns the Convo Memory briefing on one contact | `email`, plus `history_limit` locally (default 25) or `historyLimit` hosted (default 10), 1–50 | Both, Memory |
| `intelligence_unresolved_threads` | Lists open action items across your contacts | `limit` (1–100, default 25) | Both, Memory |

Hosted summaries and feedback must already exist in Convo. Your AI assistant can use the retrieved transcript or summary to answer questions and draft emails itself; this does not call Convo's local generation tools.

### Built-in prompts

These pre-built workflows appear as prompt templates in your AI assistant. Both servers have them.

| Prompt | Description |
|--------|-------------|
| `meeting-prep` | Prepare for an upcoming meeting by reviewing past interactions with a person, company or topic |
| `weekly-review` | Get a consolidated review of your week |
| `follow-up-blitz` | Draft follow-up emails for all recent meetings at once (looks back 3 days by default) |

The local server also offers two resources, `convo://meetings/recent` and `convo://meetings/{id}/summary`.

## Example conversations

**Preparing for a meeting:**
> "I have a call with Sarah from Acme Corp tomorrow. What should I know?"

The AI uses `intelligence_prepare` to search your past meetings, pull their summaries and action items, and give you a briefing with suggested talking points.

**Catching up on action items:**
> "What action items am I behind on from the last two weeks?"

The AI uses `intelligence_find_action_items` to scan recent meetings and return the open items with owners, priorities and the meetings they came from.

**Drafting follow-ups:**
> "Draft follow-up emails for all my calls from the last 3 days"

The AI can list recent meetings and draft emails from their summaries. With the local server, it can also use Convo's `meetings_draft_email` tool.

**Asking about a specific meeting:**
> "What did we decide about pricing in the Q1 review?"

The AI can search for the meeting and read its transcript to answer. With the local server, it can also use Convo's `meetings_ask` tool.

## Troubleshooting

**The Claude connector shows as disconnected after sign-in.** Check your Convo subscription first: the hosted server requires Starter or above. If your subscription is active, reconnect Convo and check the error shown; a disconnected status alone does not identify the cause.

**Claude's sign-in page never appeared.** The browser may have blocked the pop-up. Allow pop-ups for claude.ai and click **Connect** again. Also confirm that Convo was added as a custom connector and that your workspace permits it.

**An older ChatGPT or Codex chat asks to reconnect.** Start a new chat and pick Convo with **@**. In Codex, restart the app first if Convo is missing. The [Plugins page](https://chatgpt.com/plugins) opens the directory, not a direct Convo sign-in page. Open your existing Convo connection there if it needs authentication.

**The local server stops with "CONVO_API_KEY environment variable is required".** Add the key to the `env` block of your configuration.

**A tool returns "API access requires a Starter plan or above".** The local server needs Convo Starter or above. Upgrade at [itsconvo.com/pricing](https://www.itsconvo.com/pricing).

**A tool returns "Invalid API key".** The key is wrong or revoked. Create a new one in **Settings → Convo API**.

**A tool returns "Rate limit exceeded" or "Monthly AI generation limit reached".** The first clears at the next full hour. For the second, see [AI credits](/tiers#ai-credits). `account_info` shows your usage.

**The REST API returns "This credential only permits read-only MCP access".** Keys from an MCP sign-in work only with the hosted server. Create an API key in the app for the REST API.

## Links

- [Convo](https://www.itsconvo.com)
- [npm package](https://www.npmjs.com/package/@itsconvo/mcp-server)
- [GitHub](https://github.com/itsconvo/mcp-server)
- [OpenAPI specification](https://docs.itsconvo.com/api/openapi)
- [Model Context Protocol](https://modelcontextprotocol.io)

---

# Resources

Authentication, usage limits, and practical guidance for building with the Convo API.

Source: https://docs.itsconvo.com/resources

API Base URL: https://www.itsconvo.com/api/v1

## Before you build

<Cards>
  <Card icon={<KeyRound aria-hidden="true" />} title="Authentication" description="Create an API key and authenticate your requests." href="/authentication" />
  <Card icon={<CreditCard aria-hidden="true" />} title="Tier Access" description="Check which operations your subscription supports." href="/tiers" />
  <Card icon={<Gauge aria-hidden="true" />} title="Rate Limits" description="Understand request limits and handle throttled requests." href="/rate-limits" />
  <Card icon={<TriangleAlert aria-hidden="true" />} title="Error Codes" description="Find the cause of an unsuccessful request and what to do next." href="/errors" />
</Cards>

## Build your workflow

<Cards>
  <Card icon={<Webhook aria-hidden="true" />} title="Webhooks" description="Trigger a workflow when a call is saved or its key points are ready." href="/webhooks" />
  <Card icon={<CircleCheck aria-hidden="true" />} title="Best Practices" description="Webhooks, retries, key storage and pagination." href="/best-practices" />
  <Card icon={<MCPIcon aria-hidden="true" />} title="MCP Server" description="Ask Claude, ChatGPT or Cursor about your calls and contacts." href="/mcp" />
  <Card icon={<FileText aria-hidden="true" />} title="Full documentation" description="Every page in one text file, for your AI tools." href="/llms-full.txt" />
</Cards>

---

# Authentication

How to create an API key, send it with each request, and what happens when it is missing, wrong or revoked.

Source: https://docs.itsconvo.com/authentication

API Base URL: https://www.itsconvo.com/api/v1

Every request needs an API key in the `Authorization` header. Keys work on the Starter, Professional and Enterprise plans.

```
Authorization: Bearer convo_...
```

<Tabs items={["curl", "JavaScript", "Python"]}>
<Tab value="curl">
```bash
curl https://www.itsconvo.com/api/v1/conversations \
  -H "Authorization: Bearer $CONVO_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```javascript
const res = await fetch("https://www.itsconvo.com/api/v1/conversations", {
  headers: { Authorization: `Bearer ${process.env.CONVO_API_KEY}` },
});
const { data } = await res.json();
```
</Tab>
<Tab value="Python">
```python
import os
import requests

resp = requests.get(
    "https://www.itsconvo.com/api/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['CONVO_API_KEY']}"},
)
data = resp.json()["data"]
```
</Tab>
</Tabs>

## Create a key

1. Open the Convo desktop app and go to **Settings → Convo API**.
2. Click **Create key**, give the key a name and accept the API Terms of Use.
3. Copy the key. It is shown only once.

- A key is `convo_` followed by 32 hex characters. Convo stores only a SHA-256 hash of it, so a lost key can't be shown again. Create a new one.
- Starter allows 1 active key, Professional 3 and Enterprise 10. Each sign-in to the hosted [MCP server](/mcp) from Claude, ChatGPT or Cursor also takes a slot.
- All your keys share one [rate limit](/rate-limits) and one budget of [AI credits](/tiers).

## Revoke a key

In **Settings → Convo API**, click **Revoke** next to the key and confirm. The key stops working at once.

## Keep keys on your server

Send requests from your server, not from a browser. The API doesn't allow requests from other websites' pages (CORS), and a key in front-end code is visible to anyone. Read the key from an environment variable and keep it out of your repository.

## When authentication fails

Errors use the [error format](/errors).

| Status | Message | What to do |
|--------|---------|------------|
| `401 unauthorized` | `Missing or invalid Authorization header. Use: Bearer <api_key>` | Send the header, starting with `Bearer ` |
| `401 unauthorized` | `Invalid API key` | The key is wrong or revoked. Create a new one. |
| `403 forbidden` | `API access requires a Starter plan or above. …` | The account is on Free, or its subscription has ended. Upgrade at [itsconvo.com/pricing](https://www.itsconvo.com/pricing). |
| `403 forbidden` | `This credential only permits read-only MCP access. …` | The key came from an MCP sign-in and only works with the hosted MCP server. Create an API key in the app. |

Active and trialing subscriptions work. If a renewal is late, access continues for 48 hours after the billing period ends.

---

# Tier Access

What each plan includes in the API: keys, requests per hour, AI credits, webhooks and Convo Memory.

Source: https://docs.itsconvo.com/tiers

API Base URL: https://www.itsconvo.com/api/v1

The API works on the Starter, Professional and Enterprise plans. The Free plan has no API access. Prices are on [itsconvo.com/pricing](https://www.itsconvo.com/pricing).

| | Starter | Professional | Enterprise |
|---|:---:|:---:|:---:|
| [API keys](/authentication#create-a-key) | 1 | 3 | 10 |
| [Requests per hour](/rate-limits) | 100 | 500 | 2,000 |
| [AI credits](#ai-credits) per month | 1,500 | 15,000 | 30,000 |
| [Webhooks](/webhooks) | No | 3 | 999 |
| [Contacts](#convo-memory) (Convo Memory) | No | Yes | Yes |
| [MCP server](/mcp) | Yes | Yes | Yes |

## AI credits

- `POST /feedback` when it generates, `POST /query` and `POST /email` use one credit each. Key points and every `GET` are free.
- The desktop app's AI features, including live help during calls, use the same credits.
- One day can use at most a third of the monthly credits: 500, 5,000 or 10,000. A monthly spending cap can also stop generation before the credits run out.
- Credits reset on the 1st of each month at 00:00 UTC. `GET /user/profile` shows `used`, `limit` and `remaining`.
- When a limit is reached, the endpoint returns `429 ai_limit_exceeded`.

## Convo Memory

The [contacts endpoints](/api-reference/contacts/list-contacts) need a Professional or Enterprise plan with Convo Memory turned on in the desktop app under **Settings → Memory**. Without Memory, `GET /contacts` and `GET /contacts/unresolved-threads` return an empty list with `reason: "no-brain"`, and a briefing returns `403`.

---

# Rate Limits

Each plan allows a number of requests per hour. How they are counted, which headers show the count, and how to handle a 429.

Source: https://docs.itsconvo.com/rate-limits

API Base URL: https://www.itsconvo.com/api/v1

Each account can make a set number of requests per clock hour (UTC). All its API keys share the count, and it resets on the hour.

| Plan | Requests per hour |
|------|:-----------------:|
| Starter | 100 |
| Professional | 500 |
| Enterprise | 2,000 |

Every request with a valid key counts, including requests that end in an error. Requests from the local [MCP server](/mcp) count too. The hosted MCP server and webhook deliveries don't.

Successful responses carry three headers.

| Header | Type | Meaning |
|--------|------|---------|
| `X-RateLimit-Limit` | integer | Requests allowed per hour on your plan |
| `X-RateLimit-Remaining` | integer | Requests left this hour |
| `X-RateLimit-Reset` | Unix timestamp | When the count resets: the next full hour, in seconds |

Over the limit you get `429 rate_limited` with the same headers and `Retry-After`, the seconds until the next hour.

```json
{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (100 requests per hour for starter plan)" } }
```

## Other 429 responses

| Response | Cause | What to do |
|----------|-------|------------|
| `429 rate_limited`, message `OpenAI rate limit exceeded. Please try again later.` | The AI model is busy. Only on the AI generation endpoints, without headers. | Wait a few seconds and retry |
| `429 ai_limit_exceeded` | Your AI credits are used up for the month or the day, or the spending cap is reached. See [Tier Access](/tiers). | Don't retry. Check `GET /user/profile`. |
| `429` with `{ "error": "Rate limit exceeded", "message": "…" }` | A request without an `Authorization` header. These are limited to 100 per 15 minutes per IP address. | Send your key |

## Handling a 429

Read `error.code` before you retry. Only `rate_limited` clears by waiting.

```javascript
const res = await fetch(url, { headers });
if (res.status === 429) {
  const { error } = await res.json();
  if (error?.code === "ai_limit_exceeded") throw new Error(error.message);
  const wait = Number(res.headers.get("Retry-After") ?? 5);
  await new Promise((r) => setTimeout(r, wait * 1000));
  // send the same request again
}
```

To use fewer requests, let [webhooks](/webhooks) tell you when a call is ready instead of polling `GET /conversations`.

---

# Webhooks

Get a signed POST at your URL when a call is saved, summarised, scored, shared, renamed or deleted. Professional and Enterprise.

Source: https://docs.itsconvo.com/webhooks

API Base URL: https://www.itsconvo.com/api/v1

A webhook sends a signed JSON `POST` to your URL for each event you subscribe to.

- Professional plans can have 3 webhooks and Enterprise 999.
- A delivery tells you that something happened. Read the data itself from the API, such as `GET /conversations/{id}/keypoints`.
- Reply with a 2xx within 10 seconds and do the work afterwards. Convo ignores the response.

## Setup

1. Register your URL and events with `POST /webhooks`. The response contains the signing secret, which you see only once.
2. Send a test event with `POST /webhooks/test`.
3. [Verify the signature](#verify-the-signature) of every request.

### Register a URL

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">
```bash
curl -X POST https://www.itsconvo.com/api/v1/webhooks \
  -H "Authorization: Bearer $CONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/convo", "events": ["conversation.keypoints.ready", "conversation.deleted"] }'
```
</Tab>
<Tab value="JavaScript">
```javascript
const res = await fetch("https://www.itsconvo.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONVO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/convo",
    events: ["conversation.keypoints.ready", "conversation.deleted"],
  }),
});
const { data } = await res.json();
// data.secret is shown only in this response
```
</Tab>
</Tabs>

```json
{
  "data": {
    "id": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34",
    "url": "https://example.com/webhooks/convo",
    "events": ["conversation.keypoints.ready", "conversation.deleted"],
    "secret": "whsec_3c9f0e1a7b2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c",
    "createdAt": "2026-03-18T15:00:00.000Z"
  }
}
```

- The URL must use HTTPS. Localhost and private network addresses are refused with `400`.
- List, test and delete webhooks with the [webhook endpoints](/api-reference/webhooks/list-webhooks).
- Webhooks can't be changed. To change the URL or events, delete the webhook (`DELETE /webhooks` with `{ "id": "..." }` as the body) and register a new one.

### Send a test event

```bash
curl -X POST https://www.itsconvo.com/api/v1/webhooks/test \
  -H "Authorization: Bearer $CONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhookId": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34" }'
```

```json
{ "data": { "webhookId": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34", "delivered": true, "statusCode": 200 } }
```

`delivered` is true whenever your server answered, so check `statusCode`. If your server doesn't answer within 10 seconds, you get `delivered: false`. The test is sent even when the webhook isn't subscribed to `webhook.test`.

## Events

| Event | When it fires | `data` |
|-------|---------------|--------|
| `conversation.created` | The desktop app saves a new call after it ends | `conversationId` |
| `transcript.ready` | The desktop app saves a call's transcript. `segmentCount` is the number of segments in that save. | `conversationId`, `segmentCount` |
| `transcript.failed` | Saving the transcript failed | `conversationId`, `error` |
| `conversation.keypoints.ready` | Key points are generated, by the app after a call or by `POST /keypoints`. Returning saved key points doesn't fire it. | `conversationId`, `title` |
| `conversation.summary.ready` | With `keypoints.ready`, when the key points have sections | `conversationId`, `title`, `sectionCount` |
| `conversation.action_items.ready` | With `keypoints.ready`, when there are action items | `conversationId`, `actionItemCount` |
| `conversation.feedback.ready` | Feedback is generated, in the app or by `POST /feedback` | `conversationId`, `overallScore` |
| `conversation.shared` | A call is shared, in the app or by `POST /share` | `conversationId`, `shareUrl` |
| `conversation.updated` | A call is renamed with `PATCH /conversations/{id}` | `conversationId`, `title` |
| `conversation.deleted` | A call is deleted, in the app or through the API | `conversationId` |
| `webhook.test` | `POST /webhooks/test` | `message` |

Each request looks like this:

```json
{
  "event": "conversation.keypoints.ready",
  "data": { "conversationId": "session_1773842400000", "title": "Acme pilot pricing call" },
  "timestamp": "2026-03-18T15:00:12.000Z"
}
```

| Header | Value |
|--------|-------|
| `Content-Type` | `application/json` |
| `X-Convo-Event` | The event name |
| `X-Convo-Signature` | The hex HMAC-SHA256 of the raw body, keyed with your secret |

## Verify the signature

Use the whole secret as the key, including `whsec_`. Compute the HMAC over the raw body before you parse it, and compare in constant time. The signature covers the body's `timestamp`, so you can reject old requests by checking it.

<Tabs items={["Node.js", "Python"]}>
<Tab value="Node.js">
```javascript
import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/webhooks/convo", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.CONVO_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  const received = req.get("X-Convo-Signature") ?? "";
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  res.sendStatus(200);
  const { event, data } = JSON.parse(req.body);
  // handle the event
});

app.listen(3000);
```
</Tab>
<Tab value="Python">
```python
import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/webhooks/convo")
def convo_webhook():
    secret = os.environ["CONVO_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Convo-Signature", "")):
        abort(401)
    payload = request.get_json()
    # handle payload["event"] and payload["data"]
    return "", 200
```
</Tab>
</Tabs>

## Delivery

- Convo sends each event once. It doesn't retry and keeps no delivery log, so a delivery that fails or times out is lost. To catch up, list recent calls with `GET /conversations`.
- Deliveries don't count against your [rate limit](/rate-limits).
- Webhooks keep sending after a downgrade below Professional. `DELETE /webhooks` works on any paid plan, so you can still remove them.

---

# Error Codes

The error format and every error code, with what each one means and what to do.

Source: https://docs.itsconvo.com/errors

API Base URL: https://www.itsconvo.com/api/v1

All errors look the same.

```json
{ "error": { "code": "not_found", "message": "Conversation not found" } }
```

- Handle errors by `code`. The codes below don't change.
- `message` is for people and can change. For `validation_error` it names the field.
- A request without an `Authorization` header can get a `429` with a different body. See [Rate Limits](/rate-limits#other-429-responses).

## Codes

| Code | Status | Meaning | What to do |
|------|:------:|---------|------------|
| `validation_error` | 400 | A field or parameter is missing or wrong, or the body isn't valid JSON. Feedback also returns it for a call with fewer than 10 transcript segments. | Fix the request |
| `unauthorized` | 401 | The `Authorization` header is missing, or the key is wrong or revoked | See [Authentication](/authentication#when-authentication-fails) |
| `forbidden` | 403 | The plan doesn't allow the request. This covers a Free plan or ended subscription, webhooks below Professional, the webhook limit, a contact briefing without Convo Memory, revoked calendar access, and a key from an MCP sign-in. | Read the message |
| `not_found` | 404 | No such call, webhook or contact in your account, or the call was deleted. Also returned when key points or feedback don't exist yet, when renaming a call without key points, and when no calendar is connected. | Check the ID. Generate key points or feedback with `POST`. |
| `rate_limited` | 429 | Over the hourly request limit, or the AI model is busy | Wait `Retry-After` seconds, or a few seconds when there is no header |
| `ai_limit_exceeded` | 429 | Your AI credits are used up for the month or the day, or the spending cap is reached | Don't retry. See [Tier Access](/tiers#ai-credits). |
| `internal_error` | 500 | Something failed on Convo's side | Retry once after a pause |

## Retrying

- Retry `rate_limited` and `internal_error`. Every other code means the request or the account has to change first.
- On `POST /feedback`, `/query` and `/email`, a `500` can come after the AI credit was used, so a retry uses another one.
- If an error persists, write to [ivan@itsconvo.com](mailto:ivan@itsconvo.com) with the endpoint, the time and the message.

---

# Best Practices

Habits that keep an integration fast, inside its limits and safe.

Source: https://docs.itsconvo.com/best-practices

API Base URL: https://www.itsconvo.com/api/v1

## React to webhooks instead of polling

Register a webhook for `conversation.keypoints.ready` and read the call when it arrives. Deliveries don't count against your [rate limit](/rate-limits). Webhooks need Professional or Enterprise. On Starter, poll `GET /conversations?since=...` on a schedule.

## Call POST directly for key points and feedback

`POST /conversations/{id}/keypoints` and `POST /conversations/{id}/feedback` return the saved result when there is one, so you don't need a `GET` first. Only `forceRefresh: true` generates again. Key points are free. Generating feedback uses one [AI credit](/tiers#ai-credits).

## Check the error code before you retry

`rate_limited` clears by waiting. `ai_limit_exceeded` doesn't. See [Handling a 429](/rate-limits#handling-a-429).

## Keep your key on the server

Read it from an environment variable and keep it out of front-end code and your repository. If a key leaks, revoke it in the desktop app under **Settings → Convo API** and create a new one.

## Page through long lists

`GET /conversations` returns up to 100 calls per page. Use `offset` until you have `pagination.total` calls.

```javascript
const headers = { Authorization: `Bearer ${process.env.CONVO_API_KEY}` };
const limit = 100;
const calls = [];

for (let offset = 0; ; offset += limit) {
  const res = await fetch(
    `https://www.itsconvo.com/api/v1/conversations?limit=${limit}&offset=${offset}`,
    { headers },
  );
  if (!res.ok) throw new Error(`Convo API ${res.status}`);
  const { data, pagination } = await res.json();
  calls.push(...data);
  if (data.length === 0 || calls.length >= pagination.total) break;
}
```

---

# Overview

Every Convo API endpoint, generated from the OpenAPI document.

Source: https://docs.itsconvo.com/api-reference

API Base URL: https://www.itsconvo.com/api/v1

## Meeting data

<Cards>
  <Card title="Conversations" description="List calls, read transcripts, key points and feedback, and rename, share or delete a call." href="/api-reference/conversations/list-conversations" />
  <Card title="AI Generation" description="Generate key points, coaching feedback, answers, and follow-up emails from a conversation." href="/api-reference/a-i--generation/generate-keypoints" />
  <Card title="Contacts" description="Brief yourself before the next call and see which follow-ups are still open. Professional and Enterprise, with Convo Memory." href="/api-reference/contacts/list-contacts" />
</Cards>

## Account and automation

<Cards>
  <Card title="Calendar" description="Upcoming events from your Google or Outlook calendar." href="/api-reference/calendar/list-calendar-events" />
  <Card title="User" description="Your profile, plan and AI credit usage." href="/api-reference/user/get-user-profile" />
  <Card title="Webhooks" description="Create, list, test, and delete webhook subscriptions." href="/api-reference/webhooks/list-webhooks" />
  <Card title="OpenAPI specification" description="Download the specification for use in your API tools." href="/api/openapi" />
</Cards>

New to the API? Start with the [Quickstart](/), then review [Authentication](/authentication) and [Rate Limits](/rate-limits).

---

# List conversations

Returns your recorded calls, newest first. `search` matches the title or any words in the transcript, case-insensitive. `since` keeps only transcript from that time on, so for a call that started earlier, `startTime`, `duration` and `segmentCount` cover only the later part. `pagination.total` counts every matching call.

Source: https://docs.itsconvo.com/api-reference/conversations/list-conversations

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/conversations

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "summary": "List conversations",
        "description": "Returns your recorded calls, newest first. `search` matches the title or any words in the transcript, case-insensitive. `since` keeps only transcript from that time on, so for a call that started earlier, `startTime`, `duration` and `segmentCount` cover only the later part. `pagination.total` counts every matching call.",
        "operationId": "listConversations",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100,
              "minimum": 1
            },
            "description": "Calls per page, 1 to 100. Larger values are lowered to 100."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Number of calls to skip"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches the title or transcript text, case-insensitive"
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only transcript from this time on (ISO 8601)"
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversations",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Conversation"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "session_1773842400000",
                      "title": "Q1 Planning Review",
                      "startTime": "2026-03-18T14:00:00Z",
                      "endTime": "2026-03-18T14:45:00Z",
                      "duration": 45,
                      "segmentCount": 128
                    }
                  ],
                  "pagination": {
                    "total": 42,
                    "limit": 20,
                    "offset": 0
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "session_1773842400000",
            "description": "The call's ID"
          },
          "title": {
            "type": "string",
            "example": "Q1 Planning Review",
            "nullable": true,
            "description": "Null when the call has no key points yet"
          },
          "startTime": {
            "type": "string",
            "format": "date-time"
          },
          "endTime": {
            "type": "string",
            "format": "date-time"
          },
          "duration": {
            "type": "number",
            "description": "Minutes between the first and last segment"
          },
          "segmentCount": {
            "type": "integer"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "example": 42
          },
          "limit": {
            "type": "integer",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Get transcript

Returns the transcript recorded during the call, oldest segment first. Returns 404 for a call that doesn't exist or was deleted.

Source: https://docs.itsconvo.com/api-reference/conversations/get-transcript

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/conversations/{id}/transcript

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/transcript": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "summary": "Get transcript",
        "description": "Returns the transcript recorded during the call, oldest segment first. Returns 404 for a call that doesn't exist or was deleted.",
        "operationId": "getTranscript",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation transcript",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "segments": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Segment"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "segments": [
                      {
                        "text": "Let's review the Q1 targets.",
                        "speaker": "local",
                        "timestamp": "2026-03-18T14:01:12.000Z"
                      },
                      {
                        "text": "Revenue is up 15% from last quarter.",
                        "speaker": "remote",
                        "timestamp": "2026-03-18T14:01:18.000Z"
                      },
                      {
                        "text": "That's great progress. What about retention?",
                        "speaker": "local",
                        "timestamp": "2026-03-18T14:01:25.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Segment": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "example": "Let's review the Q1 targets."
          },
          "speaker": {
            "type": "string",
            "example": "local",
            "nullable": true,
            "description": "`local` is you, from your microphone. Other people are usually `remote`."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Get cached keypoints

Returns the saved key points. The desktop app generates them after each call. Returns 404 when the call has none yet.

Source: https://docs.itsconvo.com/api-reference/conversations/get-keypoints

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/conversations/{id}/keypoints

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/keypoints": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "summary": "Get cached keypoints",
        "description": "Returns the saved key points. The desktop app generates them after each call. Returns 404 when the call has none yet.",
        "operationId": "getKeypoints",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Cached keypoints",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/KeypointsResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "title": "Q1 Planning Review",
                    "keypoints": {
                      "title": "Q1 Planning Review",
                      "sections": [
                        {
                          "heading": "Revenue Performance",
                          "points": [
                            "Revenue increased 15% quarter-over-quarter",
                            "Enterprise segment grew fastest at 22%"
                          ]
                        },
                        {
                          "heading": "Customer Retention",
                          "points": [
                            "Retention rate held steady at 94%",
                            "Churn concentrated in SMB segment"
                          ]
                        }
                      ],
                      "decisions": [
                        "Increase enterprise sales team by 2 headcount",
                        "Launch SMB retention campaign by end of April"
                      ],
                      "actionItems": [
                        {
                          "item": "Draft enterprise hiring plan",
                          "owner": "Alice",
                          "confidence": 0.95,
                          "priority": "high"
                        },
                        {
                          "item": "Prepare SMB retention proposal",
                          "owner": "Bob",
                          "confidence": 0.87,
                          "priority": "medium"
                        }
                      ],
                      "participants": [
                        "Alice",
                        "Bob"
                      ],
                      "importantDates": [
                        {
                          "date": "2026-04-30",
                          "context": "Deadline for SMB retention campaign launch"
                        }
                      ]
                    },
                    "createdAt": "2026-03-18T15:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "KeypointsResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "Q1 Planning Review"
          },
          "keypoints": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "sections": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "heading": {
                      "type": "string"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "decisions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "actionItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "item": {
                      "type": "string"
                    },
                    "owner": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "number"
                    },
                    "priority": {
                      "type": "string",
                      "enum": [
                        "high",
                        "medium",
                        "low"
                      ]
                    }
                  }
                }
              },
              "participants": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "importantDates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "context": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Get cached feedback

Returns the saved coaching feedback for the call. Returns 404 when none has been generated.

Source: https://docs.itsconvo.com/api-reference/conversations/get-feedback

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/conversations/{id}/feedback

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/feedback": {
      "get": {
        "tags": [
          "Conversations"
        ],
        "summary": "Get cached feedback",
        "description": "Returns the saved coaching feedback for the call. Returns 404 when none has been generated.",
        "operationId": "getFeedback",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Cached feedback",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FeedbackResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "feedback": {
                      "overallScore": 8.5,
                      "topPriority": {
                        "focus": "Pause before answering Bob's pushback",
                        "quote": "Yeah no, we already considered that.",
                        "reason": "The two interruptions both came when Bob raised retention risk, and both shut the topic down before he finished the thought. Holding the pause is the single change that unblocks the retention conversation next call.",
                        "alternative": "That's a fair concern, Bob. Walk me through what you're seeing."
                      },
                      "strengths": [
                        {
                          "category": "clarity",
                          "description": "Clear and structured presentation of quarterly results",
                          "timestamp": "14:01",
                          "quote": "Let's review the Q1 targets one by one."
                        }
                      ],
                      "growthAreas": [
                        {
                          "category": "listening",
                          "description": "Interrupted Bob twice during the retention discussion",
                          "suggestion": "Pause for 2-3 seconds after others finish speaking before responding.",
                          "timestamp": "14:12"
                        }
                      ],
                      "categoryScores": {
                        "clarity": 9,
                        "listening": 7.5,
                        "timeManagement": 8.5,
                        "collaboration": 8,
                        "decisionMaking": 9
                      },
                      "talkListenRatio": 45,
                      "actionPlan": [
                        "Practice active listening by pausing before responding",
                        "Summarize others' points before adding your own"
                      ]
                    },
                    "overallScore": 8.5,
                    "userSpeakerName": "local",
                    "createdAt": "2026-03-18T15:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "FeedbackResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "feedback": {
            "type": "object",
            "properties": {
              "overallScore": {
                "type": "number",
                "example": 8.5,
                "description": "0 to 10"
              },
              "topPriority": {
                "type": "object",
                "description": "Optional. The single highest-leverage focus area to act on before the next call — synthesized from across the growth areas, not necessarily a copy of growthAreas[0]. Absent when the call was too brief/routine for a clear priority, or in feedback generated before this field existed.",
                "properties": {
                  "focus": {
                    "type": "string",
                    "description": "Short imperative theme, 4-8 words ('Slow down before committing to scope')."
                  },
                  "quote": {
                    "type": "string",
                    "description": "Verbatim anchoring moment from the user's transcript."
                  },
                  "reason": {
                    "type": "string",
                    "description": "Why this is the #1 priority for next call (1-2 sentences)."
                  },
                  "alternative": {
                    "type": "string",
                    "description": "Verbatim line the user could have said instead. Rendered as a 'Try saying' callout."
                  }
                }
              },
              "strengths": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "string",
                      "description": "Verbatim line the user said (primary content for chat-bubble rendering)."
                    },
                    "reason": {
                      "type": "string",
                      "description": "Why this specific moment landed well (1-2 sentences)."
                    }
                  }
                }
              },
              "growthAreas": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "suggestion": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "string",
                      "description": "Verbatim line the user said that could be improved."
                    },
                    "reason": {
                      "type": "string",
                      "description": "Why this moment fell short (1-2 sentences)."
                    },
                    "alternative": {
                      "type": "string",
                      "description": "Verbatim better phrasing the user could have used instead. Rendered as a 'Try saying' callout."
                    }
                  }
                }
              },
              "categoryScores": {
                "type": "object",
                "properties": {
                  "clarity": {
                    "type": "number"
                  },
                  "listening": {
                    "type": "number"
                  },
                  "timeManagement": {
                    "type": "number"
                  },
                  "collaboration": {
                    "type": "number"
                  },
                  "decisionMaking": {
                    "type": "number"
                  }
                }
              },
              "talkListenRatio": {
                "type": "number",
                "description": "Talk-to-listen ratio as a percentage (0 to 100), estimated by the model",
                "example": 45
              },
              "actionPlan": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "stats": {
                "type": "object",
                "description": "Added when the feedback is generated through the API",
                "properties": {
                  "talkListenRatio": {
                    "type": "number",
                    "description": "Same as `talkListenRatio`, 50 when the model gave none"
                  },
                  "totalMinutes": {
                    "type": "integer",
                    "description": "Minutes between the first and last segment"
                  }
                }
              }
            }
          },
          "overallScore": {
            "type": "number"
          },
          "userSpeakerName": {
            "type": "string",
            "description": "The speaker Convo scored as you: `local` (your microphone), a speaker whose name matches yours, or `Unknown`"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Share conversation

Makes the call readable by anyone with the link and returns the link. Fires `conversation.shared`.

Source: https://docs.itsconvo.com/api-reference/conversations/share-conversation

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/conversations/{id}/share

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/share": {
      "post": {
        "tags": [
          "Conversations"
        ],
        "summary": "Share conversation",
        "description": "Makes the call readable by anyone with the link and returns the link. Fires `conversation.shared`.",
        "operationId": "shareConversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Share URL generated",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "shareUrl": "https://www.itsconvo.com/shared/conversation/session_1773842400000"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "shareUrl": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Update conversation

Renames the call. Spaces around the title are removed. The title is stored with the key points, so a call without key points returns 404. Fires `conversation.updated`.

Source: https://docs.itsconvo.com/api-reference/conversations/update-conversation

API Base URL: https://www.itsconvo.com/api/v1

## PATCH /api/v1/conversations/{id}

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}": {
      "patch": {
        "tags": [
          "Conversations"
        ],
        "summary": "Update conversation",
        "description": "Renames the call. Spaces around the title are removed. The title is stored with the key points, so a call without key points returns 404. Fires `conversation.updated`.",
        "operationId": "updateConversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "New conversation title",
                    "example": "Acme pilot pricing call"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation updated",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "title": "Acme pilot pricing call"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Delete conversation

Deletes the call. It no longer appears in the API or the app, and it is unlinked from your Convo Memory contacts. The API can't restore it. Fires `conversation.deleted`.

Source: https://docs.itsconvo.com/api-reference/conversations/delete-conversation

API Base URL: https://www.itsconvo.com/api/v1

## DELETE /api/v1/conversations/{id}

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}": {
      "delete": {
        "tags": [
          "Conversations"
        ],
        "summary": "Delete conversation",
        "description": "Deletes the call. It no longer appears in the API or the app, and it is unlinked from your Convo Memory contacts. The API can't restore it. Fires `conversation.deleted`.",
        "operationId": "deleteConversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation deleted",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "deleted": true
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "deleted": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Generate keypoints

Returns the saved key points, or generates them when there are none. `forceRefresh: true` generates them again. Key points don't use AI credits. Generating fires `conversation.keypoints.ready`, plus `conversation.summary.ready` when there are sections and `conversation.action_items.ready` when there are action items.

Source: https://docs.itsconvo.com/api-reference/a-i--generation/generate-keypoints

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/conversations/{id}/keypoints

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/keypoints": {
      "post": {
        "tags": [
          "AI Generation"
        ],
        "summary": "Generate keypoints",
        "description": "Returns the saved key points, or generates them when there are none. `forceRefresh: true` generates them again. Key points don't use AI credits. Generating fires `conversation.keypoints.ready`, plus `conversation.summary.ready` when there are sections and `conversation.action_items.ready` when there are action items.",
        "operationId": "generateKeypoints",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "forceRefresh": {
                    "type": "boolean",
                    "default": false,
                    "description": "Force regeneration even if cached result exists"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated keypoints",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/KeypointsResponse"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "cached": {
                              "type": "boolean"
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "title": "Q1 Planning Review",
                    "keypoints": {
                      "title": "Q1 Planning Review",
                      "sections": [
                        {
                          "heading": "Revenue Performance",
                          "points": [
                            "Revenue increased 15% quarter-over-quarter",
                            "Enterprise segment grew fastest at 22%"
                          ]
                        },
                        {
                          "heading": "Customer Retention",
                          "points": [
                            "Retention rate held steady at 94%",
                            "Churn concentrated in SMB segment"
                          ]
                        }
                      ],
                      "decisions": [
                        "Increase enterprise sales team by 2 headcount",
                        "Launch SMB retention campaign by end of April"
                      ],
                      "actionItems": [
                        {
                          "item": "Draft enterprise hiring plan",
                          "owner": "Alice",
                          "confidence": 0.95,
                          "priority": "high"
                        },
                        {
                          "item": "Prepare SMB retention proposal",
                          "owner": "Bob",
                          "confidence": 0.87,
                          "priority": "medium"
                        }
                      ],
                      "participants": [
                        "Alice",
                        "Bob"
                      ],
                      "importantDates": [
                        {
                          "date": "2026-04-30",
                          "context": "Deadline for SMB retention campaign launch"
                        }
                      ]
                    },
                    "createdAt": "2026-03-18T15:00:00.000Z",
                    "cached": false
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "KeypointsResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "Q1 Planning Review"
          },
          "keypoints": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "sections": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "heading": {
                      "type": "string"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "decisions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "actionItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "item": {
                      "type": "string"
                    },
                    "owner": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "number"
                    },
                    "priority": {
                      "type": "string",
                      "enum": [
                        "high",
                        "medium",
                        "low"
                      ]
                    }
                  }
                }
              },
              "participants": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "importantDates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "context": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Generate feedback

Returns the saved feedback, or generates it when there is none. `forceRefresh: true` generates it again. Generating uses one AI credit. It is counted before the transcript is checked, so a 404, or a 400 for a call with fewer than 10 transcript segments, also uses one. Fires `conversation.feedback.ready`.

Source: https://docs.itsconvo.com/api-reference/a-i--generation/generate-feedback

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/conversations/{id}/feedback

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/feedback": {
      "post": {
        "tags": [
          "AI Generation"
        ],
        "summary": "Generate feedback",
        "description": "Returns the saved feedback, or generates it when there is none. `forceRefresh: true` generates it again. Generating uses one AI credit. It is counted before the transcript is checked, so a 404, or a 400 for a call with fewer than 10 transcript segments, also uses one. Fires `conversation.feedback.ready`.",
        "operationId": "generateFeedback",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "forceRefresh": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated feedback",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/FeedbackResponse"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "cached": {
                              "type": "boolean"
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "feedback": {
                      "overallScore": 8.5,
                      "topPriority": {
                        "focus": "Pause before answering Bob's pushback",
                        "quote": "Yeah no, we already considered that.",
                        "reason": "The two interruptions both came when Bob raised retention risk, and both shut the topic down before he finished the thought. Holding the pause is the single change that unblocks the retention conversation next call.",
                        "alternative": "That's a fair concern, Bob. Walk me through what you're seeing."
                      },
                      "strengths": [
                        {
                          "category": "clarity",
                          "description": "Clear and structured presentation of quarterly results",
                          "timestamp": "14:01",
                          "quote": "Let's review the Q1 targets one by one."
                        }
                      ],
                      "growthAreas": [
                        {
                          "category": "listening",
                          "description": "Interrupted Bob twice during the retention discussion",
                          "suggestion": "Pause for 2-3 seconds after others finish speaking before responding.",
                          "timestamp": "14:12"
                        }
                      ],
                      "categoryScores": {
                        "clarity": 9,
                        "listening": 7.5,
                        "timeManagement": 8.5,
                        "collaboration": 8,
                        "decisionMaking": 9
                      },
                      "talkListenRatio": 45,
                      "actionPlan": [
                        "Practice active listening by pausing before responding",
                        "Summarize others' points before adding your own"
                      ],
                      "stats": {
                        "talkListenRatio": 45,
                        "totalMinutes": 45
                      }
                    },
                    "overallScore": 8.5,
                    "userSpeakerName": "local",
                    "createdAt": "2026-03-18T15:00:00.000Z",
                    "cached": false
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AILimitExceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "FeedbackResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "feedback": {
            "type": "object",
            "properties": {
              "overallScore": {
                "type": "number",
                "example": 8.5,
                "description": "0 to 10"
              },
              "topPriority": {
                "type": "object",
                "description": "Optional. The single highest-leverage focus area to act on before the next call — synthesized from across the growth areas, not necessarily a copy of growthAreas[0]. Absent when the call was too brief/routine for a clear priority, or in feedback generated before this field existed.",
                "properties": {
                  "focus": {
                    "type": "string",
                    "description": "Short imperative theme, 4-8 words ('Slow down before committing to scope')."
                  },
                  "quote": {
                    "type": "string",
                    "description": "Verbatim anchoring moment from the user's transcript."
                  },
                  "reason": {
                    "type": "string",
                    "description": "Why this is the #1 priority for next call (1-2 sentences)."
                  },
                  "alternative": {
                    "type": "string",
                    "description": "Verbatim line the user could have said instead. Rendered as a 'Try saying' callout."
                  }
                }
              },
              "strengths": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "string",
                      "description": "Verbatim line the user said (primary content for chat-bubble rendering)."
                    },
                    "reason": {
                      "type": "string",
                      "description": "Why this specific moment landed well (1-2 sentences)."
                    }
                  }
                }
              },
              "growthAreas": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "suggestion": {
                      "type": "string"
                    },
                    "timestamp": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "string",
                      "description": "Verbatim line the user said that could be improved."
                    },
                    "reason": {
                      "type": "string",
                      "description": "Why this moment fell short (1-2 sentences)."
                    },
                    "alternative": {
                      "type": "string",
                      "description": "Verbatim better phrasing the user could have used instead. Rendered as a 'Try saying' callout."
                    }
                  }
                }
              },
              "categoryScores": {
                "type": "object",
                "properties": {
                  "clarity": {
                    "type": "number"
                  },
                  "listening": {
                    "type": "number"
                  },
                  "timeManagement": {
                    "type": "number"
                  },
                  "collaboration": {
                    "type": "number"
                  },
                  "decisionMaking": {
                    "type": "number"
                  }
                }
              },
              "talkListenRatio": {
                "type": "number",
                "description": "Talk-to-listen ratio as a percentage (0 to 100), estimated by the model",
                "example": 45
              },
              "actionPlan": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "stats": {
                "type": "object",
                "description": "Added when the feedback is generated through the API",
                "properties": {
                  "talkListenRatio": {
                    "type": "number",
                    "description": "Same as `talkListenRatio`, 50 when the model gave none"
                  },
                  "totalMinutes": {
                    "type": "integer",
                    "description": "Minutes between the first and last segment"
                  }
                }
              }
            }
          },
          "overallScore": {
            "type": "number"
          },
          "userSpeakerName": {
            "type": "string",
            "description": "The speaker Convo scored as you: `local` (your microphone), a speaker whose name matches yours, or `Unknown`"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Generate follow-up email

Drafts a follow-up email from the call. Each request uses one AI credit. A call that doesn't exist returns 404 without using one. The body is optional.

Source: https://docs.itsconvo.com/api-reference/a-i--generation/generate-email

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/conversations/{id}/email

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/email": {
      "post": {
        "tags": [
          "AI Generation"
        ],
        "summary": "Generate follow-up email",
        "description": "Drafts a follow-up email from the call. Each request uses one AI credit. A call that doesn't exist returns 404 without using one. The body is optional.",
        "operationId": "generateEmail",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recipientName": {
                    "type": "string",
                    "description": "Name of the email recipient",
                    "example": "Sarah"
                  },
                  "tone": {
                    "type": "string",
                    "enum": [
                      "professional",
                      "casual",
                      "concise"
                    ],
                    "default": "professional",
                    "description": "`professional`, `casual` or `concise`"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated email",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EmailResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "subject": "Follow-up: Q1 Planning Review",
                    "body": "Hi Sarah,\n\nThanks for joining the Q1 Planning Review today. Here are the key takeaways:\n\n- Revenue increased 15% quarter-over-quarter, with enterprise leading at 22% growth\n- Customer retention held at 94%, though SMB churn needs attention\n\nAction items:\n- Alice: Draft enterprise hiring plan by next week\n- Bob: Prepare SMB retention proposal by end of April\n\nLet me know if I missed anything.\n\nBest,\nAlice",
                    "keyPoints": [
                      "Revenue increased 15% quarter-over-quarter",
                      "Enterprise segment grew fastest at 22%",
                      "Retention rate held steady at 94%"
                    ],
                    "actionItems": [
                      "Draft enterprise hiring plan (Alice, next week)",
                      "Prepare SMB retention proposal (Bob, end of April)"
                    ],
                    "generatedAt": "2026-03-18T15:05:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AILimitExceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "EmailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "subject": {
            "type": "string",
            "example": "Follow-up: Q1 Planning Review"
          },
          "body": {
            "type": "string"
          },
          "keyPoints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actionItems": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Query conversation

Answers a question about one call from its transcript. Each request uses one AI credit. A call that doesn't exist returns 404 without using one. `suggestedQueries` are fixed follow-up questions picked from words in your question.

Source: https://docs.itsconvo.com/api-reference/a-i--generation/query-conversation

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/conversations/{id}/query

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/conversations/{id}/query": {
      "post": {
        "tags": [
          "AI Generation"
        ],
        "summary": "Query conversation",
        "description": "Answers a question about one call from its transcript. Each request uses one AI credit. A call that doesn't exist returns 404 without using one. `suggestedQueries` are fixed follow-up questions picked from words in your question.",
        "operationId": "queryConversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/conversationId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "The question to ask",
                    "example": "What were the main action items?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI-generated answer",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/QueryResponse"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "session_1773842400000",
                    "query": "What were the main action items?",
                    "response": "Two action items were identified: (1) Alice will draft an enterprise hiring plan by next week, and (2) Bob will prepare an SMB retention proposal by end of April.",
                    "metadata": {
                      "segmentsAnalyzed": 187,
                      "conversationDuration": 45
                    },
                    "suggestedQueries": [
                      "Who is responsible for each task?",
                      "What are the deadlines?",
                      "Draft an email summarizing this meeting"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/AILimitExceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "QueryResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "response": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "segmentsAnalyzed": {
                "type": "integer"
              },
              "conversationDuration": {
                "type": "number",
                "description": "Duration in minutes"
              }
            }
          },
          "suggestedQueries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Get a contact briefing

Everything Convo Memory has on one contact before your next call: the relationship summary, recent meetings, open action items and recent decisions. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, it returns 403. A contact from another account returns 404.

Source: https://docs.itsconvo.com/api-reference/contacts/get-contact-briefing

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/contacts/{id}/briefing

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/contacts/{id}/briefing": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "Get a contact briefing",
        "description": "Everything Convo Memory has on one contact before your next call: the relationship summary, recent meetings, open action items and recent decisions. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, it returns 403. A contact from another account returns 404.",
        "operationId": "getContactBriefing",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact ID from List contacts",
            "example": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71"
          },
          {
            "name": "historyLimit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 50
            },
            "description": "How many recent meetings to read for the briefing"
          }
        ],
        "responses": {
          "200": {
            "description": "The briefing",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ContactBriefing"
                    }
                  }
                },
                "example": {
                  "data": {
                    "contact": {
                      "id": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71",
                      "email": "sarah@northwind.com",
                      "displayName": "Sarah Lee",
                      "companyDomain": "northwind.com",
                      "meetingCount": 4,
                      "firstSeenAt": "2026-08-12T15:00:00Z",
                      "lastSeenAt": "2026-09-29T14:00:00Z"
                    },
                    "summary": {
                      "prose": "Sarah leads operations at Northwind and is evaluating a three-month pilot.",
                      "topics": [],
                      "open_questions": [
                        "Who signs off on the pilot budget?"
                      ]
                    },
                    "summaryGeneratedAt": "2026-09-29T15:10:00Z",
                    "recentMeetings": [
                      {
                        "sessionId": "session_1773842400000",
                        "title": "Northwind pilot review",
                        "date": "2026-09-26T14:00:00Z"
                      }
                    ],
                    "openActionItems": [
                      {
                        "item": "Send the pilot pricing to Sarah",
                        "sessionId": "session_1773842400000",
                        "hash": "9b2f6c0d4e8a1f3b5c7d9e0a2b4c6d8e",
                        "owner": "Alex Kim",
                        "priority": "high",
                        "meetingDate": "2026-09-26T14:00:00Z",
                        "meetingTitle": "Northwind pilot review"
                      }
                    ],
                    "recentDecisions": [
                      "Start the pilot with the support team"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "ContactBriefing": {
        "type": "object",
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "summary": {
            "type": "object",
            "nullable": true,
            "description": "What Convo Memory knows about this relationship, or null before a summary exists",
            "properties": {
              "prose": {
                "type": "string"
              },
              "topics": {
                "type": "array",
                "items": {}
              },
              "open_questions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "summaryGeneratedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "recentMeetings": {
            "type": "array",
            "description": "The most recent meetings with this contact, newest first",
            "items": {
              "type": "object",
              "properties": {
                "sessionId": {
                  "type": "string"
                },
                "title": {
                  "type": "string",
                  "nullable": true
                },
                "date": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "openActionItems": {
            "type": "array",
            "description": "Up to 10 open action items from those meetings, newest meeting first",
            "items": {
              "$ref": "#/components/schemas/BriefingActionItem"
            }
          },
          "recentDecisions": {
            "type": "array",
            "description": "Up to 10 decisions from those meetings, without repeats",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71"
          },
          "email": {
            "type": "string",
            "example": "sarah@northwind.com"
          },
          "displayName": {
            "type": "string",
            "nullable": true,
            "example": "Sarah Lee"
          },
          "companyDomain": {
            "type": "string",
            "nullable": true,
            "description": "The email domain; null for personal email providers",
            "example": "northwind.com"
          },
          "meetingCount": {
            "type": "integer",
            "example": 4
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "BriefingActionItem": {
        "type": "object",
        "properties": {
          "item": {
            "type": "string",
            "example": "Send the pilot pricing to Sarah"
          },
          "sessionId": {
            "type": "string",
            "example": "session_1773842400000"
          },
          "hash": {
            "type": "string",
            "description": "Identifies the action item within its conversation"
          },
          "owner": {
            "type": "string",
            "nullable": true
          },
          "priority": {
            "type": "string",
            "nullable": true,
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "meetingDate": {
            "type": "string",
            "format": "date-time"
          },
          "meetingTitle": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# List contacts

The people Convo Memory has met in your calendar meetings, most meetings first, then most recently seen. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.

Source: https://docs.itsconvo.com/api-reference/contacts/list-contacts

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/contacts

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "List contacts",
        "description": "The people Convo Memory has met in your calendar meetings, most meetings first, then most recently seen. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.",
        "operationId": "listContacts",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 200
            },
            "description": "Max results to return"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Number of results to skip"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches email or display name, case-insensitive"
          }
        ],
        "responses": {
          "200": {
            "description": "List of contacts",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Contact"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "reason": {
                      "type": "string",
                      "enum": [
                        "no-brain"
                      ],
                      "description": "Present when Convo Memory is not enabled on the account"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71",
                      "email": "sarah@northwind.com",
                      "displayName": "Sarah Lee",
                      "companyDomain": "northwind.com",
                      "meetingCount": 4,
                      "firstSeenAt": "2026-08-12T15:00:00Z",
                      "lastSeenAt": "2026-09-29T14:00:00Z"
                    }
                  ],
                  "pagination": {
                    "total": 37,
                    "limit": 50,
                    "offset": 0
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71"
          },
          "email": {
            "type": "string",
            "example": "sarah@northwind.com"
          },
          "displayName": {
            "type": "string",
            "nullable": true,
            "example": "Sarah Lee"
          },
          "companyDomain": {
            "type": "string",
            "nullable": true,
            "description": "The email domain; null for personal email providers",
            "example": "northwind.com"
          },
          "meetingCount": {
            "type": "integer",
            "example": 4
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "example": 42
          },
          "limit": {
            "type": "integer",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# List unresolved threads

Open action items from meetings with your contacts, oldest meeting first, so the ones waiting longest come first. Items you marked resolved or dismissed are left out, and so are meetings not matched to a contact. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.

Source: https://docs.itsconvo.com/api-reference/contacts/list-unresolved-threads

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/contacts/unresolved-threads

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/contacts/unresolved-threads": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "List unresolved threads",
        "description": "Open action items from meetings with your contacts, oldest meeting first, so the ones waiting longest come first. Items you marked resolved or dismissed are left out, and so are meetings not matched to a contact. Requires a Professional or Enterprise plan with Convo Memory enabled. Without Memory, the list is empty and `reason` is `no-brain`.",
        "operationId": "listUnresolvedThreads",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Max results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Open action items",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/UnresolvedThread"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "The number of items returned"
                    },
                    "reason": {
                      "type": "string",
                      "enum": [
                        "no-brain"
                      ],
                      "description": "Present when Convo Memory is not enabled on the account"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "sessionId": "session_1773842400000",
                      "actionItem": "Send the pilot pricing to Sarah",
                      "hash": "9b2f6c0d4e8a1f3b5c7d9e0a2b4c6d8e",
                      "meetingTitle": "Northwind pilot review",
                      "createdAt": "2026-09-26T14:00:00Z",
                      "stalenessDays": 9,
                      "contactId": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71",
                      "contactName": "Sarah Lee",
                      "contactCompany": "northwind.com"
                    }
                  ],
                  "total": 1
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "UnresolvedThread": {
        "type": "object",
        "properties": {
          "sessionId": {
            "type": "string",
            "description": "The conversation the action item came from",
            "example": "session_1773842400000"
          },
          "actionItem": {
            "type": "string",
            "example": "Send the pilot pricing to Sarah"
          },
          "hash": {
            "type": "string",
            "description": "Identifies the action item within its conversation"
          },
          "meetingTitle": {
            "type": "string",
            "nullable": true,
            "example": "Northwind pilot review"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the meeting started"
          },
          "stalenessDays": {
            "type": "integer",
            "description": "Days since the meeting",
            "example": 9
          },
          "contactId": {
            "type": "string",
            "example": "contact_3f2b8c1e-7d4a-4c1b-9a6e-2b5d8f0c4e71"
          },
          "contactName": {
            "type": "string",
            "nullable": true,
            "example": "Sarah Lee"
          },
          "contactCompany": {
            "type": "string",
            "nullable": true,
            "description": "The contact's company domain",
            "example": "northwind.com"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# List calendar events

Returns upcoming events from the calendar connected in the Convo desktop app, Google or Outlook, by start time. Events come in the provider's own format. Declined and cancelled events are left out. Without `timeMax`, Outlook looks 7 days ahead and Google has no end.

Source: https://docs.itsconvo.com/api-reference/calendar/list-calendar-events

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/calendar/events

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/calendar/events": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "summary": "List calendar events",
        "description": "Returns upcoming events from the calendar connected in the Convo desktop app, Google or Outlook, by start time. Events come in the provider's own format. Declined and cancelled events are left out. Without `timeMax`, Outlook looks 7 days ahead and Google has no end.",
        "operationId": "listCalendarEvents",
        "parameters": [
          {
            "name": "maxResults",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Events to return, 1 to 50"
          },
          {
            "name": "timeMin",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start of the window (ISO 8601). Defaults to now."
          },
          {
            "name": "timeMax",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End of the window (ISO 8601)"
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar events",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CalendarEvent"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "evt_abc123",
                      "summary": "Weekly Standup",
                      "start": {
                        "dateTime": "2026-03-19T09:00:00-04:00",
                        "timeZone": "America/New_York"
                      },
                      "end": {
                        "dateTime": "2026-03-19T09:30:00-04:00",
                        "timeZone": "America/New_York"
                      },
                      "attendees": [
                        {
                          "email": "alice@example.com",
                          "displayName": "Alice Chen",
                          "responseStatus": "accepted"
                        },
                        {
                          "email": "bob@example.com",
                          "displayName": "Bob Smith",
                          "responseStatus": "accepted"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Calendar access was revoked. Reconnect the calendar in the desktop app.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Calendar permissions revoked. Please reconnect your calendar."
                  }
                }
              }
            }
          },
          "404": {
            "description": "No calendar is connected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Calendar not connected. Connect your calendar in the Convo dashboard."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "CalendarEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "summary": {
            "type": "string",
            "example": "Weekly Standup"
          },
          "start": {
            "type": "object",
            "properties": {
              "dateTime": {
                "type": "string",
                "format": "date-time"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "end": {
            "type": "object",
            "properties": {
              "dateTime": {
                "type": "string",
                "format": "date-time"
              },
              "timeZone": {
                "type": "string"
              }
            }
          },
          "attendees": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                },
                "responseStatus": {
                  "type": "string"
                }
              }
            }
          }
        },
        "description": "An event in the calendar provider's own format, passed through unchanged. Google Calendar events look like this. Outlook events are Microsoft Graph events, with `subject`, `start`, `end` and `attendees[].emailAddress` instead.",
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Get profile and usage

Returns your profile, your plan and how many AI credits you have used this month.

Source: https://docs.itsconvo.com/api-reference/user/get-user-profile

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/user/profile

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/user/profile": {
      "get": {
        "tags": [
          "User"
        ],
        "summary": "Get profile and usage",
        "description": "Returns your profile, your plan and how many AI credits you have used this month.",
        "operationId": "getUserProfile",
        "responses": {
          "200": {
            "description": "User profile and usage stats",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/UserProfile"
                    }
                  }
                },
                "example": {
                  "data": {
                    "profile": {
                      "name": "Alice Chen",
                      "email": "alice@example.com",
                      "timezone": "America/New_York",
                      "language": "en",
                      "profilePictureUrl": null,
                      "createdAt": "2025-09-15T10:00:00.000Z"
                    },
                    "subscription": {
                      "tier": "professional",
                      "status": "active",
                      "currentPeriodEnd": "2026-04-15T00:00:00.000Z"
                    },
                    "apiUsage": {
                      "aiGenerations": {
                        "used": 1240,
                        "limit": 15000,
                        "remaining": 13760,
                        "resetsAt": "2026-04-01T00:00:00.000Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "UserProfile": {
        "type": "object",
        "properties": {
          "profile": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "timezone": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "profilePictureUrl": {
                "type": "string",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "subscription": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string",
                "enum": [
                  "starter",
                  "professional",
                  "enterprise"
                ]
              },
              "status": {
                "type": "string",
                "nullable": true
              },
              "currentPeriodEnd": {
                "type": "string",
                "nullable": true,
                "format": "date-time"
              }
            }
          },
          "apiUsage": {
            "type": "object",
            "properties": {
              "aiGenerations": {
                "type": "object",
                "properties": {
                  "used": {
                    "type": "integer",
                    "description": "AI credits used this month (UTC), including by the desktop app"
                  },
                  "limit": {
                    "type": "integer",
                    "description": "AI credits per month on your plan"
                  },
                  "remaining": {
                    "type": "integer",
                    "description": "`limit` minus `used`. A daily cap of a third of `limit`, or the monthly spending cap, can stop generation earlier."
                  },
                  "resetsAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The first day of next month, 00:00 UTC"
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# List webhooks

Lists your active webhooks, newest first. Secrets are not returned. Professional and Enterprise.

Source: https://docs.itsconvo.com/api-reference/webhooks/list-webhooks

API Base URL: https://www.itsconvo.com/api/v1

## GET /api/v1/webhooks

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhooks",
        "description": "Lists your active webhooks, newest first. Secrets are not returned. Professional and Enterprise.",
        "operationId": "listWebhooks",
        "responses": {
          "200": {
            "description": "Active webhooks",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34",
                      "url": "https://hooks.example.com/convo",
                      "events": [
                        "conversation.keypoints.ready",
                        "transcript.ready"
                      ],
                      "created_at": "2026-03-10T12:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Webhooks need a Professional or Enterprise plan, or the webhook limit is reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Webhooks require a Professional plan or above."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34",
            "description": "Webhook ID"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.example.com/convo"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEvent": {
        "type": "string",
        "enum": [
          "conversation.created",
          "conversation.updated",
          "conversation.keypoints.ready",
          "conversation.summary.ready",
          "conversation.action_items.ready",
          "conversation.feedback.ready",
          "conversation.shared",
          "conversation.deleted",
          "transcript.ready",
          "transcript.failed",
          "webhook.test"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Register webhook

Registers a URL for the events you choose. The URL must use HTTPS and can't point to localhost or a private network. Professional plans can have 3 webhooks and Enterprise 999. The `secret` appears only in this response.

Source: https://docs.itsconvo.com/api-reference/webhooks/create-webhook

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/webhooks

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/webhooks": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Register webhook",
        "description": "Registers a URL for the events you choose. The URL must use HTTPS and can't point to localhost or a private network. Professional plans can have 3 webhooks and Enterprise 999. The `secret` appears only in this response.",
        "operationId": "createWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook created",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookCreated"
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "wh_def456",
                    "url": "https://hooks.example.com/convo",
                    "events": [
                      "conversation.keypoints.ready"
                    ],
                    "secret": "whsec_a1b2c3d4e5f6...",
                    "createdAt": "2026-03-18T16:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Webhooks need a Professional or Enterprise plan, or the webhook limit is reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Webhooks require a Professional plan or above."
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "WebhookCreateRequest": {
        "type": "object",
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "An HTTPS URL. Localhost and private network addresses are refused.",
            "example": "https://hooks.example.com/convo"
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          }
        }
      },
      "WebhookEvent": {
        "type": "string",
        "enum": [
          "conversation.created",
          "conversation.updated",
          "conversation.keypoints.ready",
          "conversation.summary.ready",
          "conversation.action_items.ready",
          "conversation.feedback.ready",
          "conversation.shared",
          "conversation.deleted",
          "transcript.ready",
          "transcript.failed",
          "webhook.test"
        ]
      },
      "WebhookCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "secret": {
            "type": "string",
            "description": "Signing secret: `whsec_` followed by 48 hex characters. Shown only in this response.",
            "example": "whsec_3c9f0e1a7b2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Delete webhook

Deletes a webhook. Send its `id` in the JSON body. Works on any paid plan, so you can remove webhooks after a downgrade.

Source: https://docs.itsconvo.com/api-reference/webhooks/delete-webhook

API Base URL: https://www.itsconvo.com/api/v1

## DELETE /api/v1/webhooks

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/webhooks": {
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete webhook",
        "description": "Deletes a webhook. Send its `id` in the JSON body. Works on any paid plan, so you can remove webhooks after a downgrade.",
        "operationId": "deleteWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Webhook ID to delete"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook deleted",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34",
                    "deleted": true
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```

---

# Test a webhook

Sends a signed `webhook.test` event to one of your webhooks and returns your server's status code. `delivered` is true whenever your server answered, whatever the status, so check `statusCode`. If your server doesn't answer within 10 seconds, the response is 200 with `delivered: false`.

Source: https://docs.itsconvo.com/api-reference/webhooks/test-webhook

API Base URL: https://www.itsconvo.com/api/v1

## POST /api/v1/webhooks/test

```json
{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://www.itsconvo.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/webhooks/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Test a webhook",
        "description": "Sends a signed `webhook.test` event to one of your webhooks and returns your server's status code. `delivered` is true whenever your server answered, whatever the status, so check `statusCode`. If your server doesn't answer within 10 seconds, the response is 200 with `delivered: false`.",
        "operationId": "testWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "webhookId"
                ],
                "properties": {
                  "webhookId": {
                    "type": "string",
                    "description": "ID of the webhook to test",
                    "example": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Test result",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "webhookId": "8d3f6a52-1c4e-4b7a-9e2d-5f0b8c1a7e34",
                    "delivered": true,
                    "statusCode": 200
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Reset": {
                "$ref": "#/components/headers/X-RateLimit-Reset"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Webhooks need a Professional or Enterprise plan, or the webhook limit is reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Webhooks require a Professional plan or above."
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API."
      }
    },
    "parameters": {
      "conversationId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Conversation ID from List conversations",
        "example": "session_1773842400000"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests allowed per hour on your plan"
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "Requests left this hour"
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "Unix time in seconds of the next full hour (UTC), when the count resets"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "ai_limit_exceeded",
                  "validation_error",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The Authorization header is missing, or the key is wrong or revoked",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "Missing or invalid Authorization header. Use: Bearer <api_key>"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The plan doesn't allow this request, or the key only works with the MCP server",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "forbidden",
                "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Conversation not found"
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Over your hourly request limit",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds until the next full hour, when the count resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "rate_limited",
                "message": "Rate limit exceeded (100 requests per hour for starter plan)"
              }
            }
          }
        }
      },
      "AILimitExceeded": {
        "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "ai_limit_exceeded",
                "message": "Monthly AI generation limit reached. Upgrade your plan for more."
              }
            }
          }
        }
      },
      "ValidationError": {
        "description": "A field or parameter is missing or wrong. The message names it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "title is required and must be a non-empty string"
              }
            }
          }
        }
      }
    }
  }
}
```