# Convo API Documentation

> Convo helps sales teams win more deals by identifying buying signals and helping reps ask the right questions while the conversation is happening. The Convo API gives your tools and agents the conversations behind it: transcripts, key points, scored feedback, follow-up emails and contact briefings, plus webhooks and an MCP server.

## Base URL

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

## Authentication

Send your key as `Authorization: Bearer convo_...`. Create it in the Convo desktop app under Settings → Convo API → Create key. It is shown only once. API access requires a Starter plan or above.

## Responses

Success: `{ "data": ... }`. Error: `{ "error": { "code": "not_found", "message": "..." } }`. New fields may be added without a version bump, so tolerate unknown keys.

## Reading these docs

- Every page as Markdown: add `.mdx` to its address, or ask for it with `Accept: text/markdown`.
- Everything in one file: https://docs.itsconvo.com/llms-full.txt
- The OpenAPI document: https://docs.itsconvo.com/api/openapi

## Guides

- [Quickstart](https://docs.itsconvo.com/index.mdx): Create an API key, check it, and read the action items from your latest call. Three requests.
- [Introduction](https://docs.itsconvo.com/introduction.mdx): What Convo does on a sales call, what the API gives you, and how requests and responses look.
- [Features](https://docs.itsconvo.com/features.mdx): What Convo does before, during and after a sales call, and which parts the API gives you.
- [Core Concepts](https://docs.itsconvo.com/core-concepts.mdx): The objects in the Convo API, how they fit together, and which endpoints return them.
- [MCP Server](https://docs.itsconvo.com/mcp.mdx): Connect Claude, ChatGPT and Cursor to your Convo calls. Sign in with OAuth, or run the local server with an API key.
- [Resources](https://docs.itsconvo.com/resources.mdx): Authentication, usage limits, and practical guidance for building with the Convo API.
- [Authentication](https://docs.itsconvo.com/authentication.mdx): How to create an API key, send it with each request, and what happens when it is missing, wrong or revoked.
- [Tier Access](https://docs.itsconvo.com/tiers.mdx): What each plan includes in the API: keys, requests per hour, AI credits, webhooks and Convo Memory.
- [Rate Limits](https://docs.itsconvo.com/rate-limits.mdx): Each plan allows a number of requests per hour. How they are counted, which headers show the count, and how to handle a 429.
- [Webhooks](https://docs.itsconvo.com/webhooks.mdx): Get a signed POST at your URL when a call is saved, summarised, scored, shared, renamed or deleted. Professional and Enterprise.
- [Error Codes](https://docs.itsconvo.com/errors.mdx): The error format and every error code, with what each one means and what to do.
- [Best Practices](https://docs.itsconvo.com/best-practices.mdx): Habits that keep an integration fast, inside its limits and safe.

## API Reference

- [Overview](https://docs.itsconvo.com/api-reference.mdx): Every Convo API endpoint, generated from the OpenAPI document.
- [List conversations](https://docs.itsconvo.com/api-reference/conversations/list-conversations.mdx): 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.
- [Get transcript](https://docs.itsconvo.com/api-reference/conversations/get-transcript.mdx): Returns the transcript recorded during the call, oldest segment first. Returns 404 for a call that doesn't exist or was deleted.
- [Get cached keypoints](https://docs.itsconvo.com/api-reference/conversations/get-keypoints.mdx): Returns the saved key points. The desktop app generates them after each call. Returns 404 when the call has none yet.
- [Get cached feedback](https://docs.itsconvo.com/api-reference/conversations/get-feedback.mdx): Returns the saved coaching feedback for the call. Returns 404 when none has been generated.
- [Share conversation](https://docs.itsconvo.com/api-reference/conversations/share-conversation.mdx): Makes the call readable by anyone with the link and returns the link. Fires `conversation.shared`.
- [Update conversation](https://docs.itsconvo.com/api-reference/conversations/update-conversation.mdx): 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`.
- [Delete conversation](https://docs.itsconvo.com/api-reference/conversations/delete-conversation.mdx): 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`.
- [Generate keypoints](https://docs.itsconvo.com/api-reference/a-i--generation/generate-keypoints.mdx): 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.
- [Generate feedback](https://docs.itsconvo.com/api-reference/a-i--generation/generate-feedback.mdx): 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`.
- [Generate follow-up email](https://docs.itsconvo.com/api-reference/a-i--generation/generate-email.mdx): 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.
- [Query conversation](https://docs.itsconvo.com/api-reference/a-i--generation/query-conversation.mdx): 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.
- [Get a contact briefing](https://docs.itsconvo.com/api-reference/contacts/get-contact-briefing.mdx): 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.
- [List contacts](https://docs.itsconvo.com/api-reference/contacts/list-contacts.mdx): 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`.
- [List unresolved threads](https://docs.itsconvo.com/api-reference/contacts/list-unresolved-threads.mdx): 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`.
- [List calendar events](https://docs.itsconvo.com/api-reference/calendar/list-calendar-events.mdx): 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.
- [Get profile and usage](https://docs.itsconvo.com/api-reference/user/get-user-profile.mdx): Returns your profile, your plan and how many AI credits you have used this month.
- [List webhooks](https://docs.itsconvo.com/api-reference/webhooks/list-webhooks.mdx): Lists your active webhooks, newest first. Secrets are not returned. Professional and Enterprise.
- [Register webhook](https://docs.itsconvo.com/api-reference/webhooks/create-webhook.mdx): 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.
- [Delete webhook](https://docs.itsconvo.com/api-reference/webhooks/delete-webhook.mdx): Deletes a webhook. Send its `id` in the JSON body. Works on any paid plan, so you can remove webhooks after a downgrade.
- [Test a webhook](https://docs.itsconvo.com/api-reference/webhooks/test-webhook.mdx): 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`.