# Convo API Documentation

> Programmatic access to your AI meeting assistant data. Build integrations, automate workflows, or connect Convo to tools like Zapier, Make.com, and IFTTT.

Convo is a real-time AI meeting assistant (macOS & Windows desktop app) that transcribes meetings, generates summaries with action items, provides communication feedback, and works invisibly across Zoom, Google Meet, Teams, Slack, and WebEx. The API lets you access this data programmatically.

## Base URL

https://www.itsconvo.com

All endpoints are prefixed with `/api/v1/`.

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer convo_your_api_key_here
```

API keys are created in the Convo desktop app: Settings > API Keys > Create New Key. Keys are prefixed with `convo_` and are hashed on the server (cannot be retrieved after creation). API access requires a Starter plan or above.

## Response Format

Success: `{ "data": { ... } }`
Error: `{ "error": { "code": "not_found", "message": "..." } }`

New fields may be added without a version bump. Your code should tolerate unknown keys.

## Tier Access

| Capability | Starter ($14.99/mo) | Professional ($37.99/mo) | Enterprise (custom) |
|---|---|---|---|
| API keys | 1 | 3 | 10 |
| Read endpoints | Yes | Yes | Yes |
| Write endpoints | Yes | Yes | Yes |
| AI generations/month | 10 | 100 | Unlimited |
| Webhooks | No | 3 | Unlimited |
| Rate limit | 100/hr | 500/hr | 2,000/hr |

AI generation endpoints (POST keypoints, feedback, email, query) consume credits. Cached results are free.

## Rate Limits

Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Exceeding limits returns HTTP 429 with a `Retry-After` header (seconds until reset).

## Endpoints

### Conversations

#### GET /api/v1/conversations
List conversations with pagination and filtering.
- Query params: `limit` (int, max 100, default 20), `offset` (int, default 0), `search` (string), `since` (ISO 8601 datetime)
- Returns: `{ data: Conversation[], pagination: { total, limit, offset } }`

#### GET /api/v1/conversations/{id}/transcript
Get the full transcript for a conversation.
- Path param: `id` (conversation session ID, e.g. "sess_a1b2c3")
- Returns: `{ data: { id, segments: [{ text, speaker, timestamp }] } }`

#### GET /api/v1/conversations/{id}/keypoints
Get cached AI-generated keypoints (summary) for a conversation. Free, no AI credit consumed.
- Returns: `{ data: KeypointsResponse }` (see schema below)

#### GET /api/v1/conversations/{id}/feedback
Get cached AI-generated communication feedback. Free, no AI credit consumed.
- Returns: `{ data: FeedbackResponse }` (see schema below)

#### POST /api/v1/conversations/{id}/share
Generate a public share URL for a conversation.
- Returns: `{ data: { id, shareUrl } }`

#### PATCH /api/v1/conversations/{id}
Update conversation title.
- Body: `{ "title": "New Title" }` (required)
- Returns: `{ data: { id, title } }`

#### DELETE /api/v1/conversations/{id}
Soft-delete a conversation (recoverable).
- Returns: `{ data: { id, deleted: true } }`

### AI Generation (consumes monthly credits)

#### POST /api/v1/conversations/{id}/keypoints
Generate AI-powered keypoints (summary, decisions, action items). Returns cached result if available (no credit consumed). Use `forceRefresh: true` to regenerate.
- Body: `{ "forceRefresh": false }` (optional)
- Returns: `{ data: { ...KeypointsResponse, cached: boolean } }`
- Error 429 `ai_limit_exceeded`: monthly limit reached

#### POST /api/v1/conversations/{id}/feedback
Generate AI-powered communication feedback with scores. Requires at least 10 transcript segments.
- Body: `{ "forceRefresh": false }` (optional)
- Returns: `{ data: { ...FeedbackResponse, cached: boolean } }`

#### POST /api/v1/conversations/{id}/query
Ask a natural-language question about a conversation.
- Body: `{ "query": "What were the main action items?" }` (required, max 500 chars)
- Returns: `{ data: { id, query, response, metadata: { segmentsAnalyzed, conversationDuration }, suggestedQueries } }`

#### POST /api/v1/conversations/{id}/email
Generate a follow-up email based on the conversation.
- Body: `{ "recipientName": "Sarah", "tone": "professional" }` (tone: "professional" | "casual" | "concise", default "professional")
- Returns: `{ data: { id, subject, body, keyPoints, actionItems, generatedAt } }`

### Calendar

#### GET /api/v1/calendar/events
List upcoming Google Calendar events. Requires Google Calendar connected in dashboard.
- Query params: `maxResults` (int, 1-50, default 10), `timeMin` (ISO 8601 datetime)
- Returns: `{ data: CalendarEvent[] }`

### User

#### GET /api/v1/user/profile
Get user profile, subscription tier, and API usage stats.
- Returns: `{ data: { profile: { name, email, timezone, language, profilePictureUrl, createdAt }, subscription: { tier, status, currentPeriodEnd }, apiUsage: { aiGenerations: { used, limit, remaining, resetsAt } } } }`

### Webhooks (Professional+ only)

#### GET /api/v1/webhooks
List all active webhook subscriptions.
- Returns: `{ data: Webhook[] }`

#### POST /api/v1/webhooks
Register a new webhook. HTTPS URLs only. The `secret` for HMAC verification is returned once on creation.
- Body: `{ "url": "https://hooks.example.com/convo", "events": ["conversation.keypoints.ready"] }` (both required)
- Returns: `{ data: { id, url, events, secret, createdAt } }`

#### DELETE /api/v1/webhooks
Delete a webhook by ID.
- Body: `{ "id": "wh_abc123" }` (required)
- Returns: `{ data: { id, deleted: true } }`

#### POST /api/v1/webhooks/test
Send a test event to a registered webhook URL.
- Body: `{ "webhookId": "wh_abc123" }` (required)
- Returns: `{ data: { webhookId, delivered, statusCode } }`

## Webhook Events

| Event | Data fields |
|---|---|
| conversation.created | conversationId |
| conversation.updated | conversationId, title |
| conversation.keypoints.ready | conversationId, title |
| conversation.summary.ready | conversationId, title, sectionCount |
| conversation.action_items.ready | conversationId, actionItemCount |
| conversation.feedback.ready | conversationId, overallScore |
| conversation.shared | conversationId, shareUrl |
| conversation.deleted | conversationId |
| transcript.ready | conversationId, segmentCount |
| transcript.failed | conversationId, error |
| webhook.test | message |

Webhook payload format:
```json
{ "event": "conversation.keypoints.ready", "data": { "conversationId": "sess_a1b2c3", "title": "Q1 Planning Review" }, "timestamp": "2026-03-19T14:30:00.000Z" }
```

Payloads are signed with HMAC-SHA256. Verify the `X-Convo-Signature` header against the raw body using the webhook secret. The event type is in the `X-Convo-Event` header. Deliveries have a 10-second timeout and are not retried.

## Data Schemas

### Conversation
`{ id: string, title: string, startTime: datetime, endTime: datetime, duration: number (minutes), segmentCount: integer, linkedCalendarEventId: string | null }`

### Segment (transcript)
`{ text: string, speaker: string, timestamp: datetime }`

### KeypointsResponse
`{ id: string, title: string, keypoints: { title: string, sections: [{ heading, points: string[] }], decisions: string[], actionItems: [{ item, owner, confidence: number, priority: "high"|"medium"|"low" }], participants: string[], importantDates: [{ date, context }] }, createdAt: datetime }`

### FeedbackResponse
`{ id: string, feedback: { overallScore: number, strengths: [{ category, description, timestamp, quote }], growthAreas: [{ category, description, suggestion, timestamp }], categoryScores: { clarity, listening, timeManagement, collaboration, decisionMaking }, talkListenRatio: number, actionPlan: string[] }, overallScore: number, userSpeakerName: string, createdAt: datetime }`

### EmailResponse
`{ id: string, subject: string, body: string, keyPoints: string[], actionItems: string[], generatedAt: datetime }`

### CalendarEvent
`{ id: string, summary: string, start: { dateTime, timeZone }, end: { dateTime, timeZone }, attendees: [{ email, displayName, responseStatus }] }`

### UserProfile
`{ profile: { name, email, timezone, language, profilePictureUrl, createdAt }, subscription: { tier: "starter"|"professional"|"enterprise", status, currentPeriodEnd }, apiUsage: { aiGenerations: { used, limit, remaining, resetsAt } } }`

## Error Codes

| Status | Code | Description |
|---|---|---|
| 400 | validation_error | Invalid request parameters or body |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Insufficient plan tier for this endpoint |
| 404 | not_found | Resource not found |
| 429 | rate_limited | Hourly rate limit exceeded |
| 429 | ai_limit_exceeded | Monthly AI generation limit reached |
| 500 | internal_error | Unexpected server error |

## Best Practices

- Check cache before generating: call GET keypoints/feedback before POST. Cached results are free.
- Handle 429 responses: read the `Retry-After` header and wait before retrying.
- Use webhooks instead of polling for real-time updates (Professional+ only).
- Store API keys in environment variables, never in source code.
- Paginate large result sets using `limit` and `offset` params (max 100 per page).

## Integrations

Convo has official integrations with Zapier and IFTTT. The Zapier app ("Convo AI") provides triggers for new meetings, summaries, and feedback events, plus actions for generating summaries, emails, and sharing meetings. IFTTT provides equivalent queries and actions.

## Documentation Pages

- Introduction: https://docs.itsconvo.com
- Features: https://docs.itsconvo.com/features
- Core Concepts: https://docs.itsconvo.com/core-concepts
- Quick Start: https://docs.itsconvo.com/quickstart
- Authentication: https://docs.itsconvo.com/authentication
- Tier Access: https://docs.itsconvo.com/tiers
- Rate Limits: https://docs.itsconvo.com/rate-limits
- Webhooks: https://docs.itsconvo.com/webhooks
- Error Codes: https://docs.itsconvo.com/errors
- Best Practices: https://docs.itsconvo.com/best-practices
- API Reference: https://docs.itsconvo.com/api-reference
- OpenAPI Spec: https://www.itsconvo.com/openapi.json

## Contact

Email: ivan@itsconvo.com
Website: https://www.itsconvo.com
Discord: https://discord.gg/k6qM4DV6dP