Convex Teams API

openapi: 3.2.0
info:
  title: Convex Management Teams API
  description: Management API for provisioning and managing Convex projects and deployments.
  license:
    name: LicenseRef-Convex
    identifier: LicenseRef-Convex
  version: 1.0.0
servers:
- url: https://api.convex.dev/v1
  description: Platform API
tags:
- name: Teams
  description: List and manage team members
paths:
  /teams/{team_id}/list_members:
    get:
      tags:
      - Teams
      summary: List team members
      description: List the members of the given team.
      operationId: listTeamMembers
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformListTeamMembersResponse'
      security:
      - PAT: []
      x-operation-id-source: normalized
      x-operation-id-original: list team members
  /teams/create_team:
    post:
      tags:
      - Teams
      summary: Create a team
      description: 'This endpoint is not publicly accessible. It is reserved for specific

        integrations that have been granted permission to create teams on behalf of

        users. To request access, contact platforms@convex.dev.'
      operationId: createTeam
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformCreateTeamArgs'
        required: true
      responses:
        '201':
          description: Team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
        '400':
          description: Invalid team name or deployment region
        '403':
          description: This application is not authorized to create teams. This endpoint is reserved for specific integrations that are allowed to create users. If you need to create teams for your users, please contact us at platforms@convex.dev
      security: []
      x-operation-id-source: normalized
      x-operation-id-original: create team
  /teams/{team_id}/list_audit_log_events:
    get:
      tags:
      - Teams
      summary: List audit log events
      description: List a team's audit log events within a time range, with optional filters.
      operationId: listAuditLogEvents
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
        schema:
          $ref: '#/components/schemas/TeamId'
      - name: from
        in: query
        description: Start of the time range, in milliseconds since epoch.
        required: true
        schema:
          type: integer
          format: int64
      - name: to
        in: query
        description: End of the time range, in milliseconds since epoch.
        required: true
        schema:
          type: integer
          format: int64
      - name: memberId
        in: query
        description: Only return events performed by this member.
        required: false
        schema:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MemberId'
      - name: action
        in: query
        required: false
        schema:
          type: string
          enum:
          - team:join
          - team:create
          - team:update
          - team:delete
          - project:create
          - project:transfer
          - project:receive
          - project:update
          - project:delete
          - defaultEnvironmentVariable:create
          - defaultEnvironmentVariable:update
          - defaultEnvironmentVariable:delete
          - deployment:create
          - deployment:delete
          - member:invite
          - member:cancelInvitation
          - member:remove
          - member:updateRole
          - project:updateMemberRole
          - billing:paymentMethod:update
          - billing:contact:update
          - billing:address:update
          - billing:subscription:create
          - billing:subscription:resume
          - billing:subscription:cancel
          - billing:subscription:changePlan
          - team:token:create
          - team:token:update
          - team:token:delete
          - team:token:view
          - project:token:create
          - project:token:update
          - project:token:delete
          - project:token:view
          - deployment:token:create
          - deployment:token:update
          - deployment:token:delete
          - deployment:token:view
          - member:token:createWithSsoAccess
          - team:domain:create
          - team:domain:delete
          - deployment:customDomain:create
          - deployment:customDomain:delete
          - deployment:backups:create
          - deployment:backups:import
          - deployment:backups:configurePeriodic
          - deployment:backups:disablePeriodic
          - deployment:backups:delete
          - team:disableExceedingSpendingLimits
          - billing:spendingLimit:update
          - team:applyReferralCode
          - oauthApplication:create
          - oauthApplication:update
          - oauthApplication:delete
          - oauthApplication:verify
          - oauthApplication:generateClientSecret
          - integration:workos:team:create
          - integration:workos:environment:create
          - integration:workos:environment:delete
          - integration:workos:environment:retrieveCredentials
          - integration:workos:team:disconnect
          - integration:workos:team:inviteMember
          - integration:workos:projectEnvironment:create
          - integration:workos:projectEnvironment:delete
          - integration:workos:projectEnvironment:retrieveCredentials
          - sso:enable
          - sso:disable
          - sso:update
          - member:loginWithSso
          - directorySync:enable
          - directorySync:disable
          - directorySync:updateGroupMapping
          - directorySync:deleteGroupMapping
          - deployment:transfer
          - deployment:receive
          - deployment:update
          - customRole:create
          - customRole:update
          - customRole:delete
      - name: limit
        in: query
        description: Maximum number of events to return (1-100, defaults to 15).
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
      - name: cursor
        in: query
        description: Cursor from a previous response to fetch the next page.
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAuditLogEventsResponse'
      security:
      - PAT: []
      - Team Token: []
      x-operation-id-source: normalized
      x-operation-id-original: list audit log events
  /teams/{team_id}/invite_team_member:
    post:
      tags:
      - Teams
      summary: Invite a team member
      description: 'Invite a member to the given team by email. `role` is required and must be

        one of `admin`, `developer`, or `custom`. Pass `custom` together with a

        non-empty `customRoles` list to invite a member into a custom role; for

        `admin` and `developer`, `customRoles` must be omitted.'
      operationId: inviteTeamMember
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationArgs'
        required: true
      responses:
        '200':
          description: ''
      security:
      - PAT: []
      x-operation-id-source: normalized
      x-operation-id-original: invite team member
  /teams/{team_id}/list_pending_invites:
    get:
      tags:
      - Teams
      summary: List pending team invitations
      description: List the pending invitations for the given team.
      operationId: listPendingTeamInvites
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformListInvitationsResponse'
      security:
      - PAT: []
      x-operation-id-source: normalized
      x-operation-id-original: list pending team invites
  /teams/{team_id}/cancel_team_member_invite:
    post:
      tags:
      - Teams
      summary: Cancel a pending team invitation
      operationId: cancelTeamMemberInvite
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelInvitationArgs'
        required: true
      responses:
        '200':
          description: ''
      security:
      - PAT: []
      x-operation-id-source: normalized
      x-operation-id-original: cancel team member invite
  /teams/{team_id}/update_team_member_role:
    post:
      tags:
      - Teams
      summary: Update a team member's role
      description: 'Sets either the member''s built-in `role` (admin/developer) or their

        `customRoles`. The two fields are mutually exclusive: setting `role`

        clears `customRoles`, and setting `customRoles` (must be non-empty)

        puts the member in the `custom` role.'
      operationId: updateTeamMemberRole
      parameters:
      - name: team_id
        in: path
        description: Team ID
        required: true
        schema:
          $ref: '#/components/schemas/TeamId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamMemberRoleArgs'
        required: true
      responses:
        '200':
          description: ''
      security:
      - PAT: []
      x-operation-id-source: normalized
      x-operation-id-original: update team member role
components:
  schemas:
    AccessTokenId:
      type: integer
      format: int64
      minimum: 0
    ProposedTeamName:
      type: string
    Role:
      type: string
      enum:
      - admin
      - developer
      - custom
    TeamMemberCustomRole:
      type: object
      description: 'A custom role attached to a team member, denormalized with the

        role''s display name so API consumers can render members without a

        separate roles lookup.'
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/CustomRoleId'
        name:
          type: string
    CancelInvitationArgs:
      type: object
      required:
      - email
      properties:
        email:
          type: string
      additionalProperties: false
    PlatformCreateTeamArgs:
      type: object
      required:
      - defaultRegion
      - name
      properties:
        defaultRegion:
          $ref: '#/components/schemas/RegionName'
        name:
          $ref: '#/components/schemas/ProposedTeamName'
    PlatformListTeamMembersResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TeamMember'
    TeamSlug:
      type: string
    PlatformListInvitationsResponse:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvitationResponse'
    ReferralCode:
      type: string
    RegionName:
      type: string
      enum:
      - aws-us-east-1
      - aws-eu-west-1
      - aws-ca-central-1
      - aws-ap-southeast-2
    TeamResponse:
      type: object
      required:
      - id
      - name
      - slug
      - suspended
      - referralCode
      properties:
        id:
          $ref: '#/components/schemas/TeamId'
        name:
          $ref: '#/components/schemas/TeamName'
        slug:
          $ref: '#/components/schemas/TeamSlug'
        creator:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MemberId'
        suspended:
          type: boolean
        referralCode:
          $ref: '#/components/schemas/ReferralCode'
        referredBy:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/TeamId'
        managedBy:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ManagedBy'
        defaultRegion:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RegionName'
        ssoLoginId:
          type:
          - string
          - 'null'
        managedByUrl:
          type:
          - string
          - 'null'
    ListAuditLogEventsResponse:
      type: object
      required:
      - items
      - pagination
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEventResponse'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    CustomRoleId:
      type: integer
      format: int64
      minimum: 0
    InvitationResponse:
      type: object
      required:
      - email
      - expired
      - role
      properties:
        email:
          type: string
        expired:
          type: boolean
        role:
          $ref: '#/components/schemas/Role'
        customRoles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TeamMemberCustomRole'
          description: 'The custom roles attached to this invitation. Present iff `role` is

            `custom`.'
    AuditLogActor:
      oneOf:
      - type: object
        title: System
        description: The internal Convex system.
        required:
        - kind
        properties:
          kind:
            type: string
            enum:
            - system
      - type: object
        title: Member
        description: A member acting via the dashboard.
        required:
        - member_id
        - kind
        properties:
          member_id:
            $ref: '#/components/schemas/MemberId'
            description: Member ID
          kind:
            type: string
            enum:
            - member
      - type: object
        title: Token
        description: A token.
        required:
        - token_id
        - kind
        properties:
          member_id:
            oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MemberId'
              description: Member ID
          token_id:
            $ref: '#/components/schemas/AccessTokenId'
            description: 'Token ID. `0` for legacy audit log rows created before token IDs

              were recorded.'
          client_id:
            type:
            - string
            - 'null'
            description: 'Client ID of the OAuth application the token was issued to or is

              managed by, if any.'
          kind:
            type: string
            enum:
            - token
      - type: object
        title: Integration
        description: An integration (OAuth application).
        required:
        - client_id
        - kind
        properties:
          client_id:
            type: string
            description: Client ID of the integration
          kind:
            type: string
            enum:
            - integration
      description: The identity that executed an audit log action.
    AuditLogEventResponse:
      type: object
      required:
      - teamId
      - actor
      - action
      - createTime
      - metadata
      properties:
        teamId:
          $ref: '#/components/schemas/TeamId'
          description: Team ID
        actor:
          $ref: '#/components/schemas/AuditLogActor'
          description: The identity that executed the action
        action:
          type: string
          enum:
          - team:join
          - team:create
          - team:update
          - team:delete
          - project:create
          - project:transfer
          - project:receive
          - project:update
          - project:delete
          - defaultEnvironmentVariable:create
          - defaultEnvironmentVariable:update
          - defaultEnvironmentVariable:delete
          - deployment:create
          - deployment:delete
          - member:invite
          - member:cancelInvitation
          - member:remove
          - member:updateRole
          - project:updateMemberRole
          - billing:paymentMethod:update
          - billing:contact:update
          - billing:address:update
          - billing:subscription:create
          - billing:subscription:resume
          - billing:subscription:cancel
          - billing:subscription:changePlan
          - team:token:create
          - team:token:update
          - team:token:delete
          - team:token:view
          - project:token:create
          - project:token:update
          - project:token:delete
          - project:token:view
          - deployment:token:create
          - deployment:token:update
          - deployment:token:delete
          - deployment:token:view
          - member:token:createWithSsoAccess
          - team:domain:create
          - team:domain:delete
          - deployment:customDomain:create
          - deployment:customDomain:delete
          - deployment:backups:create
          - deployment:backups:import
          - deployment:backups:configurePeriodic
          - deployment:backups:disablePeriodic
          - deployment:backups:delete
          - team:disableExceedingSpendingLimits
          - billing:spendingLimit:update
          - team:applyReferralCode
          - oauthApplication:create
          - oauthApplication:update
          - oauthApplication:delete
          - oauthApplication:verify
          - oauthApplication:generateClientSecret
          - integration:workos:team:create
          - integration:workos:environment:create
          - integration:workos:environment:delete
          - integration:workos:environment:retrieveCredentials
          - integration:workos:team:disconnect
          - integration:workos:team:inviteMember
          - integration:workos:projectEnvironment:create
          - integration:workos:projectEnvironment:delete
          - integration:workos:projectEnvironment:retrieveCredentials
          - sso:enable
          - sso:disable
          - sso:update
          - member:loginWithSso
          - directorySync:enable
          - directorySync:disable
          - directorySync:updateGroupMapping
          - directorySync:deleteGroupMapping
          - deployment:transfer
          - deployment:receive
          - deployment:update
          - customRole:create
          - customRole:update
          - customRole:delete
        createTime:
          type: integer
          format: int64
          description: Time the event was created, in milliseconds since epoch.
        metadata:
          $ref: '#/components/schemas/Value'
          description: Additional JSON metadata about the audit log event
        clientIp:
          type:
          - string
          - 'null'
          description: IP address of the client that performed the action, if known.
        clientUserAgent:
          type:
          - string
          - 'null'
          description: User agent of the client that performed the action, if known.
    PaginationMetadata:
      type: object
      required:
      - hasMore
      properties:
        hasMore:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
    TeamId:
      type: integer
      format: int64
      minimum: 0
    TeamMember:
      type: object
      required:
      - id
      - email
      - role
      properties:
        id:
          $ref: '#/components/schemas/MemberId'
        name:
          type:
          - string
          - 'null'
          description: The name of the team member
        email:
          type: string
          description: The email of the team member
        role:
          $ref: '#/components/schemas/Role'
          description: 'The role of the team member. `custom` indicates the member''s

            permissions come from the attached `customRoles`.'
        customRoles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TeamMemberCustomRole'
          description: 'The custom roles attached to this team member. Present iff

            `role` is `custom`.'
    Value: {}
    UpdateTeamMemberRoleArgs:
      type: object
      required:
      - memberId
      properties:
        memberId:
          $ref: '#/components/schemas/MemberId'
        role:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Role'
            description: 'Set the member''s built-in role to `admin` or `developer`. Mutually

              exclusive with `customRoles`. The `custom` value is not accepted

              here; assign `customRoles` to put the member in the custom state.'
        customRoles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomRoleId'
          description: 'Replace the member''s custom roles. Mutually exclusive with `role`.

            Must be non-empty. Sets the member''s role to `custom`.'
      additionalProperties: false
    MemberId:
      type: integer
      format: int64
      minimum: 0
    ManagedBy:
      oneOf:
      - type: string
        enum:
        - vercel
      - type: object
        required:
        - oauthApp
        properties:
          oauthApp:
            type: string
    TeamName:
      type: string
    CreateInvitationArgs:
      type: object
      required:
      - email
      - role
      properties:
        email:
          type: string
        role:
          $ref: '#/components/schemas/Role'
          description: 'Role to assign when the invitation is accepted.

            Pass `custom` together with a non-empty `customRoles` list to invite a

            member into a custom role; `admin` and `developer` must be sent without

            `customRoles`.'
        customRoles:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomRoleId'
          description: 'Custom roles to attach when `role` is `custom`. Required and non-empty

            in that case, and forbidden otherwise.'
  securitySchemes:
    OAuth_Project_Token:
      type: http
      scheme: bearer
      description: Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api).
    OAuth_Team_Token:
      type: http
      scheme: bearer
      description: Obtained through a [Convex OAuth application](https://docs.convex.dev/management-api).
    PAT:
      type: http
      scheme: bearer
      bearerFormat: PAT
      description: Personal access token created in the Convex dashboard under user settings.
    Preview_Deploy_Key:
      type: http
      scheme: bearer
      description: Preview deploy key scoped to a project. Allowed only when operating on preview deployments in the key's project.
    Team_Token:
      type: http
      scheme: bearer
      description: Created in the dashboard under team settings for any team you can manage.
x-provenance:
  method: harvested
  publisher: Convex
  source: https://api.convex.dev/v1/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)