# 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).