GitBook Team Members API

openapi: 3.2.0
info:
  title: GitBook Team Members API
  description: The GitBook API
  termsOfService: https://policies.gitbook.com
  contact:
    name: API Support
    url: https://gitbook.com/support
    email: support@gitbook.com
  version: 0.0.1-beta
servers:
- url: '{host}/v1'
  variables:
    host:
      default: https://api.gitbook.com
security:
- user: []
- user-internal: []
- user-staff: []
- integration: []
- integration-installation: []
tags:
- name: team-members
  x-page-title: Team members
  x-page-description: Control membership at the team level for cohesive role management.
  x-parent: teams
  description: 'Easily add or remove users from teams, as well as fine-tune their specific roles within a team to ensure secure, well-organized collaboration.


    {% openapi-schemas spec="gitbook" schemas="TeamMember" grouped="false" %}

    The TeamMember object

    {% endopenapi-schemas %}'
paths:
  /orgs/{organizationId}/teams/{teamId}/members:
    put:
      operationId: updateMembersInOrganizationTeam
      summary: Updates members of a team
      description: Updates members of an organization team, either adding or removing them. If a the same user is included as both an add and a remove, they will be removed from the team.
      tags:
      - team-members
      security:
      - user: []
      - oauth:
        - organization:members:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMembersInOrganizationTeam'
      responses:
        '204':
          description: Members have been updated
    get:
      operationId: listTeamMembersInOrganizationById
      x-gitbook-mcp: true
      summary: List all team members
      description: Lists members, and their roles, for the specified organization team.
      tags:
      - team-members
      security:
      - user: []
      - oauth:
        - organization:members:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/teamId'
      - $ref: '#/components/parameters/listPage'
      - $ref: '#/components/parameters/listLimit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/List'
                - type: object
                  required:
                  - items
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/OrganizationTeamMember'
  /orgs/{organizationId}/teams/{teamId}/members/{userId}:
    put:
      operationId: addMemberToOrganizationTeamById
      summary: Add a team member
      description: Add or updates member in the specified organization team.
      tags:
      - team-members
      security:
      - user: []
      - oauth:
        - organization:members:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/teamId'
      - $ref: '#/components/parameters/userId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  $ref: '#/components/schemas/TeamMemberRole'
      responses:
        '204':
          description: Member has been added to the team
    delete:
      operationId: deleteMemberFromOrganizationTeamById
      summary: Delete a team member
      description: Deletes member from the specified organization team.
      tags:
      - team-members
      security:
      - user: []
      - oauth:
        - organization:members:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/teamId'
      - $ref: '#/components/parameters/userId'
      responses:
        '204':
          description: Member was not part of the team
        '205':
          description: Member has been deleted from the team
components:
  schemas:
    TeamMember:
      type: object
      properties:
        role:
          $ref: '#/components/schemas/TeamMemberRole'
      required:
      - role
    OrganizationMember:
      type: object
      properties:
        object:
          type: string
          description: Type of Object, always equals to "member"
          enum:
          - member
        id:
          type: string
          description: Unique identifier for the user.
        role:
          $ref: '#/components/schemas/MemberRoleOrGuest'
        user:
          $ref: '#/components/schemas/User'
        disabled:
          type: boolean
          description: Whatever the membership of this user is disabled and prevent them from accessing content.
        joinedAt:
          description: Date at which the user joined the organization.
          $ref: '#/components/schemas/Timestamp'
        lastSeenAt:
          description: Date at which the user was last seen active in the organization.
          $ref: '#/components/schemas/Timestamp'
        sso:
          type: boolean
          description: Whether the user can login with SSO.
        spaces:
          type: number
        teams:
          type: number
        sites:
          type: number
      required:
      - object
      - id
      - role
      - user
      - disabled
      - joinedAt
      - sso
      - spaces
      - teams
      - sites
    UpdateMembersInOrganizationTeam:
      type: object
      properties:
        add:
          type: array
          items:
            type: string
            description: A user to add. It can either be a user ID or an email.
        memberships:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TeamMember'
        remove:
          type: array
          items:
            type: string
            description: A user to remove. It can either be a user ID or an email.
    User:
      type: object
      properties:
        object:
          type: string
          description: Type of Object, always equals to "user"
          enum:
          - user
        id:
          type: string
          description: Unique identifier for the user
        displayName:
          type: string
          description: Full name for the user
        email:
          type: string
          description: Email address of the user
        photoURL:
          type: string
          description: URL of the user's profile picture
        urls:
          type: object
          description: URLs associated with the object
          properties:
            location:
              type: string
              description: URL of the user in the API
              format: uri
          required:
          - location
      required:
      - object
      - id
      - displayName
      - urls
    MemberRoleOrGuest:
      description: The role of a member in an organization, null for guests
      oneOf:
      - $ref: '#/components/schemas/MemberRole'
      - type: 'null'
    Timestamp:
      type: string
      format: date-time
    MemberRole:
      type: string
      description: '"The role of a member in an organization.

        "admin": Can administrate the content: create, delete spaces, ...

        "create": Can create content.

        "review": Can review content.

        "edit": Can edit the content (live or change requests).

        "comment": Can access the content and its discussions.

        "read": Can access the content, but cannot update it in any way.

        '
      enum:
      - admin
      - create
      - edit
      - review
      - comment
      - read
    List:
      type: object
      properties:
        next:
          type: object
          properties:
            page:
              type: string
              description: Unique identifier to query the next results page
          required:
          - page
        count:
          type: number
          description: Total count of objects in the list
    EntityId:
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      description: A unique entity identifier
    OrganizationTeamMember:
      type: object
      description: A member of a team in an organization, including its relationship to it
      properties:
        organization:
          description: User information as an organization member
          $ref: '#/components/schemas/OrganizationMember'
        team:
          description: User information as a team member
          $ref: '#/components/schemas/TeamMember'
        permissions:
          type: object
          description: The set of permissions for the team member
          properties:
            view:
              type: boolean
              description: Can the user view the team member
          required:
          - view
      required:
      - organization
      - team
      - permissions
    TeamMemberRole:
      type: string
      description: '"The role of a team member.

        "owner": Can manage team members.

        "member": Is a member of the team.

        '
      enum:
      - owner
      - member
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: The unique ID of the User
      schema:
        type: string
    listPage:
      name: page
      in: query
      description: Identifier of the page results to fetch.
      schema:
        type: string
    teamId:
      name: teamId
      in: path
      required: true
      description: The unique ID of the Team
      schema:
        $ref: '#/components/schemas/EntityId'
    listLimit:
      name: limit
      in: query
      description: The number of results per page
      schema:
        type: number
        minimum: 0
        maximum: 1000
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The unique id of the organization
      schema:
        $ref: '#/components/schemas/EntityId'
  securitySchemes:
    user:
      type: http
      scheme: bearer
    user-internal:
      type: http
      scheme: bearer
    user-staff:
      type: http
      scheme: bearer
    integration:
      type: http
      scheme: bearer
    integration-installation:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.gitbook.com/authorize
          tokenUrl: https://oauth.gitbook.com/token
          scopes:
            user:read: Read your GitBook user profile.
            organization:read: Read the organizations you belong to, their settings and metadata, and their AI agent conversations.
            organization:write: Create organizations, and update organization settings and AI agent conversations.
            organization:members:read: Read organization members, teams, invites and link invites.
            organization:members:write: Manage organization members, teams, invites and link invites.
            organization:ask: Ask AI questions across an organization's content.
            organization:search: Search across an organization's content.
            space:read: Read spaces and their content, including pages, change requests and their reviews, comments, files and revision history.
            space:write: Create, update and delete spaces and their content, including change requests (create, edit, review), comments, and content imports and exports. Merging a change request also requires change-request:merge.
            space:permissions:read: Read the users and teams who have access to spaces and collections.
            space:permissions:write: Manage who has access to spaces and collections, including inviting users and teams.
            change-request:merge: Merge change requests, publishing their changes to the space. Creating, editing and reviewing change requests only requires space:write.
            site:read: Read sites and their settings, including navigation structure, linked spaces, customization, redirects, topics, AI configuration and documentation issues.
            site:write: Create, update and delete sites and their settings, including navigation structure (sections, linked spaces, external links), customization, redirects, topics and AI configuration.
            site:publish: Publish and unpublish sites, controlling their public exposure.
            site:permissions:read: Read the users and teams who have access to sites.
            site:permissions:write: Manage who has access to sites, including inviting users and teams.
            site:auth:read: Read how visitors authenticate on a site and its security configuration, including private share links.
            site:auth:write: Manage how visitors authenticate on a site and its security configuration, including private share links.
            site:insights:read: Read site analytics and insights, including the questions visitors asked Ask AI and the answers they received.
            site:ask: Ask AI questions across a site's content.
            site:search: Search across a site's content.
            integration:read: Read integrations, their status and where they are installed.
            integration:installations:read: Read integration installations and their configuration, which can include credentials for third-party services.
            integration:installations:write: Install and configure integrations on an organization, its spaces and its sites.
            integration:publish: Publish integrations, which can request their own permissions on your content, and route their events to a development tunnel.
            integration:delete: Unpublish integrations, permanently deleting them and every installation of them.
            openapi:read: Read OpenAPI specifications.
            openapi:write: Create, update and delete OpenAPI specifications.
x-provenance:
  method: harvested
  publisher: GitBook
  source: https://api.gitbook.com/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)