openapi: 3.2.0 info: title: GitBook Organization Invites 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: organization-invites x-page-title: Organization invites x-page-description: Streamline the invitation process for new members joining your organization. x-parent: organizations description: Use this API to create and revoke invitations for new members. By automating invite flows, you can maintain a cohesive onboarding experience for collaborators and speed up team expansion. paths: /orgs/{organizationId}/invites: post: operationId: inviteUsersToOrganization summary: Invite users in an organization tags: - organization-invites security: - user: [] - oauth: - organization:members:write parameters: - $ref: '#/components/parameters/organizationId' responses: '200': description: OK content: application/json: schema: type: object properties: users: type: array items: type: string description: The unique identifiers of the users who were added to the organization invited: type: number description: The number of users who were added to the organization failedSSOEmails: type: array items: type: string description: A list of emails who were invited to the organization, but who were not added as SSO users as they are members of another org required: - users - invited '400': $ref: '#/components/responses/BadRequestError' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InviteUsersToOrganization' /orgs/{organizationId}/invites/{inviteId}: post: operationId: joinOrganizationWithInvite summary: Join an organization with an invite tags: - organization-invites security: - user: [] - oauth: - organization:members:write parameters: - $ref: '#/components/parameters/organizationId' - $ref: '#/components/parameters/inviteId' responses: '200': description: OK content: application/json: schema: type: object properties: {} /orgs/{organizationId}/link-invites: get: operationId: listOrganizationInviteLinks summary: List organization invites tags: - organization-invites security: - user: [] - oauth: - organization:members:read parameters: - $ref: '#/components/parameters/organizationId' - $ref: '#/components/parameters/listPage' - $ref: '#/components/parameters/listLimit' responses: '200': description: List of invite links in the organization. content: application/json: schema: allOf: - $ref: '#/components/schemas/List' - type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/InviteLinkToOrganization' post: operationId: createOrganizationInvite summary: Create an organization invite tags: - organization-invites security: - user: [] - oauth: - organization:members:write parameters: - $ref: '#/components/parameters/organizationId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrganizationInvite' responses: '201': description: The organization invite has been created content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteLink' /orgs/{organizationId}/link-invites/{inviteId}: get: operationId: getOrganizationInviteLink summary: Get an organization by its ID tags: - organization-invites security: - user: [] - oauth: - organization:members:read parameters: - $ref: '#/components/parameters/organizationId' - $ref: '#/components/parameters/inviteId' responses: '200': description: Invite link in the organization. content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteLink' patch: operationId: updateOrganizationInviteById summary: Update an organization invite tags: - organization-invites security: - user: [] - oauth: - organization:members:write parameters: - $ref: '#/components/parameters/organizationId' - $ref: '#/components/parameters/inviteId' requestBody: required: true content: application/json: schema: oneOf: - type: object description: Update role of an organization invite properties: role: $ref: '#/components/schemas/MemberRoleOrGuest' required: - role - type: object description: Update level of an organization content invite properties: level: $ref: '#/components/schemas/MemberRoleOrGuest' required: - level responses: '200': description: The organization invite has been updated content: application/json: schema: $ref: '#/components/schemas/OrganizationInviteLink' components: schemas: GitSyncOperationDirection: type: string enum: - export - import CreateOrganizationInvite: oneOf: - $ref: '#/components/schemas/CreateInviteToOrganization' - $ref: '#/components/schemas/CreateInviteToSpace' - $ref: '#/components/schemas/CreateInviteToCollection' MemberRoleOrGuest: description: The role of a member in an organization, null for guests oneOf: - $ref: '#/components/schemas/MemberRole' - type: 'null' DefaultLevel: description: Default level for a piece of content oneOf: - $ref: '#/components/schemas/MemberRoleOrGuest' - type: string enum: - inherit Expression: type: string description: Expression to evaluate minLength: 0 maxLength: 1024 MergeRulesConfigurationInherit: type: object description: The merge rules inherits from the organization configuration. properties: type: type: string enum: - inherit required: - type PreviousGitSyncState: type: object description: What is still known about a target's Git Sync after its installation was removed. Never returned alongside `gitSync`, which describes a live installation. required: - url properties: url: type: string description: The URL to the directory of the repository tree the content synced with before its Git Sync installation was removed, at the branch it synced. MergeRulesConfigurationRules: type: object description: The merge rules are composed of individual rules that must all pass. properties: type: type: string enum: - rules rules: type: array items: $ref: '#/components/schemas/MergeRule' required: - type - rules MergeRule: oneOf: - type: object properties: rule: type: string enum: - require_specific_reviewers users: type: array description: List of user IDs. items: type: string required: - rule - users - type: object properties: rule: type: string enum: - require_one_of_specific_reviewers users: type: array description: List of user IDs. items: type: string required: - rule - users - type: object properties: rule: type: string enum: - allow_bypass users: type: array description: List of user IDs. items: type: string required: - rule - users - type: object properties: rule: type: string enum: - require_at_least_one_review - require_at_least_one_approved_review - require_all_reviews_approved - require_agent_review - require_up_to_date_change_request - require_change_request_subject - require_change_request_description - require_author_to_merge required: - rule - type: object description: The merge rule is written in the advanced custom expression syntax. properties: rule: type: string enum: - custom expression: $ref: '#/components/schemas/Expression' message: type: string description: Optional message to display when the expression evaluates to false. required: - rule - expression CreateInviteToOrganization: type: object properties: role: $ref: '#/components/schemas/MemberRoleOrGuest' description: The role of the member in the organization required: - role 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 InviteLinkToCollection: type: object description: An invite link to a specific collection in an organization properties: object: type: string description: Type of Object, always equals to "invite" enum: - invite id: type: string description: Unique identifier for the invite link to the collection level: $ref: '#/components/schemas/MemberRoleOrGuest' description: The level of the member in the target collection redundant: type: boolean description: An invite is redundant if the requesting user already has all necessary permissions. collection: $ref: '#/components/schemas/Collection' description: The collection the member has been invited to required: - object - id - level - redundant - collection CreateInviteToCollection: type: object properties: level: $ref: '#/components/schemas/MemberRoleOrGuest' description: The level of the member in the target collection collection: type: string description: The ID of collection the member has been invited to required: - level - collection Space: type: object properties: object: type: string description: Type of Object, always equals to "space" enum: - space id: type: string description: Unique identifier for the space title: $ref: '#/components/schemas/SpaceTitle' emoji: description: An emoji for this space. It'll match the emoji shown in the GitBook app. $ref: '#/components/schemas/Emoji' visibility: $ref: '#/components/schemas/ContentVisibility' createdAt: $ref: '#/components/schemas/Timestamp' updatedAt: $ref: '#/components/schemas/Timestamp' deletedAt: $ref: '#/components/schemas/Timestamp' editMode: $ref: '#/components/schemas/SpaceEditMode' type: type: string description: Kind of space. Only set to `styleguide` for spaces holding a team's writing style guide; omitted for regular spaces. enum: - styleguide mergeRules: $ref: '#/components/schemas/MergeRulesSpaceConfiguration' urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the space in the API format: uri app: type: string description: URL of the space in the application format: uri published: type: string description: URL of the published version of the space. Only defined when visibility is not "private." format: uri public: type: string description: URL of the public version of the space. Only defined when visibility is "public". format: uri icon: description: URL of the icon of this space, if defined. $ref: '#/components/schemas/URL' required: - app - location organization: type: string description: ID of the organization owning this space parent: type: string description: ID of the parent collection. language: $ref: '#/components/schemas/TranslationLanguage' gitSync: $ref: '#/components/schemas/GitSyncState' previousGitSync: $ref: '#/components/schemas/PreviousGitSyncState' imports: description: 'Import runs targeting this space, still running or ended recently, most recent first. Only returned when fetching a single space. ' type: array items: $ref: '#/components/schemas/ContentImportRun' visitorAuth: $ref: '#/components/schemas/VisitorAuth' revision: type: string description: ID of the active revision in the space. defaultLevel: $ref: '#/components/schemas/DefaultLevel' comments: type: number description: Count of opened comments on the space. changeRequests: type: number description: Total count of change requests on the space. changeRequestsOpen: type: number description: Count of open change requests on the space. changeRequestsDraft: type: number description: Count of draft change requests on the space. internal_poweredByV2: type: boolean description: Whether the space is powered by V2 of the content system. internal_singleWebsocket: type: boolean description: Whether the space uses a single websocket connection for all real-time communication. permissions: type: object description: The set of permissions for the space properties: view: type: boolean description: Can the user view the space content. access: type: boolean description: Can the user access the space in the application. admin: type: boolean description: Can the user edit the title, install integrations, and manage the space. viewInviteLinks: type: boolean description: Can the user view the invite links of the space. edit: type: boolean description: Can the user edit the content of the space by creating a change request. triggerGitSync: type: boolean description: Can the user trigger a git sync. comment: type: boolean description: Can the user comment on the content. merge: type: boolean description: Can the user merge change requests. review: type: boolean description: Can the user review change requests. installIntegration: type: boolean description: Can the user install integrations in the space. required: - view - access - admin - viewInviteLinks - edit - triggerGitSync - comment - merge - review - installIntegration required: - object - id - title - emoji - organization - visibility - revision - createdAt - updatedAt - comments - changeRequests - changeRequestsOpen - changeRequestsDraft - mergeRules - urls - defaultLevel - permissions VisitorAuth: oneOf: - $ref: '#/components/schemas/VisitorAuthCustomBackend' - allOf: - $ref: '#/components/schemas/VisitorAuthIntegrationBackend' - type: object properties: integration: type: string description: Name of integration being used as the backend for authenticated access required: - integration VisitorAuthCustomBackend: type: object title: Custom backend for authenticated access properties: backend: type: string description: Custom backend for authenticated access enum: - custom required: - backend ContentImportRun: type: object properties: object: description: Type of Object, always equals to "import-run" type: string enum: - import-run id: description: Unique ID of the import type: string startedAt: description: Date when the import has started $ref: '#/components/schemas/Timestamp' completedAt: description: Filled when the imported is in status "completed" $ref: '#/components/schemas/Timestamp' createdAt: description: Date when the import was requested $ref: '#/components/schemas/Timestamp' updatedAt: description: Date when the import was last updated $ref: '#/components/schemas/Timestamp' status: description: Status of the import type: string enum: - pending - in-progress - completed - failed - cancelled reason: description: Reason for the import failure when `status` is `failed`. type: string source: description: Where the content is imported from. $ref: '#/components/schemas/ContentImportSource' target: description: Where the content is imported into. $ref: '#/components/schemas/ContentImportTarget' site: description: ID of the site the target space belongs to, when it belongs to exactly one. type: string createdBy: description: ID of the user who started the import. type: string urls: type: object description: URLs associated with the object properties: location: description: URL of the import run in the API type: string format: uri required: - location pages: description: Pages included in the import type: array items: type: object properties: id: description: ID of page type: string sourceURL: description: Source URL where the page has been imported from type: string type: description: Type of page type: string enum: - page - folder status: description: Status of the page type: string enum: - complete - pending required: - id - type - status required: - id - status GitSyncInstallationStatus: type: string enum: - unauthenticated - active - pending OrganizationInviteLink: type: object description: An invite link created in an organization oneOf: - $ref: '#/components/schemas/InviteLinkToOrganization' - $ref: '#/components/schemas/InviteLinkToSpace' - $ref: '#/components/schemas/InviteLinkToCollection' GitSyncProvider: type: string description: The provider of the Git Sync installation. enum: - github - gitlab - github-legacy MergeRulesStandaloneConfiguration: oneOf: - $ref: '#/components/schemas/MergeRulesConfigurationRules' - $ref: '#/components/schemas/MergeRulesConfigurationNone' Timestamp: type: string format: date-time Email: type: string format: email description: User email example: contact@gitbook.com EntityId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A unique entity identifier Emoji: type: string maxLength: 50 format: emoji description: Unicode codepoint or character of the emoji example: 🎉 ContentImportSource: oneOf: - type: object properties: type: type: string enum: - website url: $ref: '#/components/schemas/URL' required: - type - url - type: object properties: type: type: string enum: - file files: description: Files to import type: array maxItems: 50 items: description: Key of file type: string required: - type - files ContentVisibility: type: string description: "* `public`: Anyone can access the content, and the content is indexed by search engines.\n* `unlisted`: Anyone can access the content, and the content is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the content.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the content.\n* `in-collection`: Anyone who can access the parent collection can access the content.\n Only available for spaces in a collection.\n* `private`: Authorized members can access the content.\n" enum: - public - unlisted - share-link - visitor-auth - in-collection - private InviteLinkToOrganization: type: object description: An invite link to an organization properties: object: type: string description: Type of Object, always equals to "invite" enum: - invite id: type: string description: Unique identifier for the invite link to the organization role: $ref: '#/components/schemas/MemberRoleOrGuest' description: The role in the organization the invite link is for redundant: type: boolean description: An invite is redundant if the requesting user already has all necessary permissions. required: - object - id - role - redundant GitSyncState: type: object properties: repoName: type: string description: Repository name. installationStatus: $ref: '#/components/schemas/GitSyncInstallationStatus' installationProvider: $ref: '#/components/schemas/GitSyncProvider' integration: type: string deprecated: true description: The integration name providing the Git Sync. installationId: type: string description: The ID of the Git Sync installation. parentInstallationId: type: string description: The ID of the parent Git Sync installation, if any. url: type: string description: The URL to the repository tree, used when rendering public content. installationProjectDirectory: type: string description: Directory in the repository this content syncs from, resolved against the parent installation when the installation is managed by a site. Absent when the content syncs from the root of the repository. operation: type: object description: The latest operation on the Git Sync installation. properties: state: $ref: '#/components/schemas/GitSyncOperationState' direction: $ref: '#/components/schemas/GitSyncOperationDirection' startedAt: $ref: '#/components/schemas/Timestamp' endedAt: $ref: '#/components/schemas/Timestamp' error: type: string description: Why the operation failed, when it did. errorAction: $ref: '#/components/schemas/GitSyncOperationErrorAction' required: - state - direction - startedAt operationTimeout: type: integer description: How long an operation is allowed to run before it is terminated (in milliseconds). updatedAt: description: When the Git provider details were last updated $ref: '#/components/schemas/Timestamp' required: - installationId - installationProvider - installationStatus InviteUsersToOrganization: type: object properties: emails: type: array items: oneOf: - $ref: '#/components/schemas/Email' description: The email address of the user to invite as a member - type: object properties: email: description: The email address of the user to invite as a member $ref: '#/components/schemas/Email' role: $ref: '#/components/schemas/MemberRoleOrGuest' required: - email - role role: description: Default role to set on newly invited members. $ref: '#/components/schemas/MemberRoleOrGuest' sso: description: If true, invites the user as an SSO user of the organization. Defaults to false. type: boolean required: - emails Collection: type: object properties: object: type: string description: Type of Object, always equals to "collection" enum: - collection id: type: string description: Unique identifier for the collection title: $ref: '#/components/schemas/CollectionTitle' description: $ref: '#/components/schemas/CollectionDescription' organization: type: string description: ID of the organization owning this collection parent: type: string description: ID of the parent collection, if any defaultLevel: $ref: '#/components/schemas/DefaultLevel' urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the collection in the API format: uri app: type: string description: URL of the collection in the application format: uri required: - app - location permissions: type: object description: The set of permissions for the collection properties: view: type: boolean description: Can the user view the collection. admin: type: boolean description: Can the user edit the title/description. viewInviteLinks: type: boolean description: Can the user view the invite links of the collection. create: type: boolean description: Can the user create spaces/collections in this collection. required: - view - admin - viewInviteLinks - create required: - object - id - title - organization - urls - defaultLevel - permissions CreateInviteToSpace: type: object properties: level: $ref: '#/components/schemas/MemberRoleOrGuest' description: The level of the member in the target space space: type: string description: The ID of space the member has been invited to required: - level - space CollectionTitle: type: string description: Title of the collection maxLength: 50 GitSyncOperationErrorAction: type: object description: An action the user can take to resolve a failed Git Sync operation. properties: label: type: string description: Label for the action. url: type: string format: uri description: URL where the user can resolve the failure. required: - label - url SpaceTitle: type: string description: Title of the space maxLength: 50 MergeRulesSpaceConfiguration: oneOf: - $ref: '#/components/schemas/MergeRulesConfigurationInherit' - $ref: '#/components/schemas/MergeRulesStandaloneConfiguration' MergeRulesConfigurationNone: type: object description: The merge rules are disabled, change requests can be merged without review. properties: type: type: string enum: - none required: - type GitSyncOperationState: type: string description: '* `running`: The operation is still running * `failure`: The operation failed * `success`: The operation was successful * `timeout`: The operation timed out ' enum: - running - failure - success - timeout URL: type: string format: uri maxLength: 2048 ContentImportTarget: type: object properties: space: type: string description: ID of the space to import in changeRequest: type: string description: ID of the change request to import in page: type: string description: ID of the page to import in required: - space SpaceEditMode: type: string description: 'Determines how a Space can be edited. * `live`: Users can directly edit the space * `locked`: All edits are locked for this space. ' enum: - live - locked InviteLinkToSpace: type: object description: An invite link to a specific space in an organization properties: object: type: string description: Type of Object, always equals to "invite" enum: - invite id: type: string description: Unique identifier for the invite link to the space level: $ref: '#/components/schemas/MemberRoleOrGuest' description: The level of the member in the target space redundant: type: boolean description: An invite is redundant if the requesting user already has all necessary permissions. space: $ref: '#/components/schemas/Space' description: The space the member has been invited to required: - object - id - level - redundant - space 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 TranslationLanguage: type: string enum: - en - fr - de - es - it - pt - pt-br - ru - ja - zh - zh-tw - yue - ko - ar - hi - nl - pl - tr - sv - 'no' - da - fi - el - cs - hu - ro - th - vi - id - ms - he - uk - sk - bg - hr - lt - lv - et - sl - fr-ca - es-mx - es-419 VisitorAuthIntegrationBackend: type: object title: Integration backend for authenticated access properties: backend: type: string description: Integration as backend for authenticated access enum: - integration required: - backend CollectionDescription: type: string description: Description of the collection minLength: 0 maxLength: 100 parameters: inviteId: name: inviteId in: path required: true description: The unique id of the invite schema: $ref: '#/components/schemas/EntityId' listLimit: name: limit in: query description: The number of results per page schema: type: number minimum: 0 maximum: 1000 listPage: name: page in: query description: Identifier of the page results to fetch. schema: type: string organizationId: name: organizationId in: path required: true description: The unique id of the organization schema: $ref: '#/components/schemas/EntityId' responses: BadRequestError: description: Bad Request content: application/json: schema: type: object required: - error properties: error: type: object properties: code: type: integer format: int32 enum: - 400 message: type: string required: - code - message 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)