Convo AI Generation API

openapi: 3.2.0
info:
  title: Convo AI Generation API
  version: 1.0.0
  description: 'The Convo API gives your code the sales calls Convo records: transcripts, key points, coaching feedback, follow-up emails, contact briefings and webhooks. Build integrations with Zapier, Make or your own applications.


    ## Authentication

    Send `Authorization: Bearer convo_...` with a key created in the Convo desktop app under **Settings → Convo API**. Keys work on Starter, Professional and Enterprise plans.


    ## Plans

    | | Starter | Professional | Enterprise |

    |---|---|---|---|

    | API keys | 1 | 3 | 10 |

    | Requests per hour | 100 | 500 | 2,000 |

    | AI credits per month | 1,500 | 15,000 | 30,000 |

    | Webhooks | No | 3 | 999 |

    | Contacts (Convo Memory) | No | With Memory | With Memory |


    The desktop app''s AI features use the same credits. See https://docs.itsconvo.com/tiers.


    ## Rate limits

    Successful responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Over the hourly limit you get `429 rate_limited` with `Retry-After`.'
  contact:
    email: ivan@itsconvo.com
  termsOfService: https://www.itsconvo.com/terms/api
servers:
- url: https://www.itsconvo.com
  description: Production
security:
- bearerAuth: []
tags:
- name: AI Generation
  description: Key points, coaching feedback, answers and follow-up emails. Feedback, query and email use AI credits from your monthly budget. Key points are free.
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'
  /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'
  /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'
  /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,


                    Thanks for joining the Q1 Planning Review today. Here are the key takeaways:


                    - Revenue increased 15% quarter-over-quarter, with enterprise leading at 22% growth

                    - Customer retention held at 94%, though SMB churn needs attention


                    Action items:

                    - Alice: Draft enterprise hiring plan by next week

                    - Bob: Prepare SMB retention proposal by end of April


                    Let me know if I missed anything.


                    Best,

                    Alice'
                  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:
  headers:
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Requests left this hour
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Requests allowed per hour on your plan
    X-RateLimit-Reset:
      schema:
        type: integer
      description: Unix time in seconds of the next full hour (UTC), when the count resets
  parameters:
    conversationId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Conversation ID from List conversations
      example: session_1773842400000
  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
    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
    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
    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
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Conversation not found
    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.
    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>'
    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)
    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
  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.'