Convo Conversations API

openapi: 3.2.0
info:
  title: Convo Conversations 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: Conversations
  description: List, read, rename, share and delete your recorded calls
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'
  /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'
  /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'
  /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'
  /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'
  /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'
    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:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 42
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
    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
    Conversation:
      type: object
      properties:
        id:
          type: string
          example: session_1773842400000
          description: The call's ID
        title:
          type:
          - string
          - 'null'
          example: Q1 Planning Review
          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
    Segment:
      type: object
      properties:
        text:
          type: string
          example: Let's review the Q1 targets.
        speaker:
          type:
          - string
          - 'null'
          example: local
          description: '`local` is you, from your microphone. Other people are usually `remote`.'
        timestamp:
          type: string
          format: date-time
  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
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Conversation not found
    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.'