Convo Calendar API

openapi: 3.2.0
info:
  title: Convo Calendar 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: Calendar
  description: Upcoming events from your connected Google or Outlook calendar
paths:
  /api/v1/calendar/events:
    get:
      tags:
      - Calendar
      summary: List calendar events
      description: 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.
      operationId: listCalendarEvents
      parameters:
      - name: maxResults
        in: query
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 50
        description: Events to return, 1 to 50
      - name: timeMin
        in: query
        schema:
          type: string
          format: date-time
        description: Start of the window (ISO 8601). Defaults to now.
      - name: timeMax
        in: query
        schema:
          type: string
          format: date-time
        description: End of the window (ISO 8601)
      responses:
        '200':
          description: Calendar events
          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/CalendarEvent'
              example:
                data:
                - id: evt_abc123
                  summary: Weekly Standup
                  start:
                    dateTime: '2026-03-19T09:00:00-04:00'
                    timeZone: America/New_York
                  end:
                    dateTime: '2026-03-19T09:30:00-04:00'
                    timeZone: America/New_York
                  attendees:
                  - email: alice@example.com
                    displayName: Alice Chen
                    responseStatus: accepted
                  - email: bob@example.com
                    displayName: Bob Smith
                    responseStatus: accepted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Calendar access was revoked. Reconnect the calendar in the desktop app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: Calendar permissions revoked. Please reconnect your calendar.
        '404':
          description: No calendar is connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Calendar not connected. Connect your calendar in the Convo dashboard.
        '429':
          $ref: '#/components/responses/RateLimited'
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
  schemas:
    CalendarEvent:
      type: object
      properties:
        id:
          type: string
        summary:
          type: string
          example: Weekly Standup
        start:
          type: object
          properties:
            dateTime:
              type: string
              format: date-time
            timeZone:
              type: string
        end:
          type: object
          properties:
            dateTime:
              type: string
              format: date-time
            timeZone:
              type: string
        attendees:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
              displayName:
                type: string
              responseStatus:
                type: string
      description: An event in the calendar provider's own format, passed through unchanged. Google Calendar events look like this. Outlook events are Microsoft Graph events, with `subject`, `start`, `end` and `attendees[].emailAddress` instead.
      additionalProperties: true
    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
  responses:
    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)
  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.'