openapi: 3.1.0 info: title: GitBook 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: [] - user-internal-or-staff: [] - integration: [] - integration-installation: [] tags: - name: organizations x-page-icon: building x-page-title: Organizations x-page-description: Manage your organizations and group your members, spaces, and resources under one collaborative structure. description: | The Organizations API provides a robust way to handle the administrative structure of your GitBook workspace. By creating and configuring organizations, you can group multiple users, spaces, and collections, simplifying your permission management and fostering efficient collaboration for teams of any size. {% openapi-schemas spec="gitbook" schemas="Organization" grouped="false" %} The Organization object {% endopenapi-schemas %} - name: organization-members x-page-title: Organization members x-page-description: Handle all aspects of membership within an organization, from listing to role management. x-parent: organizations description: | Organization members can be managed through this API, which lets you invite and manage users under a particular organization. You can define roles and permissions to ensure your team has the right level of access. - 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. - name: organization-ask x-page-title: Organization AI ask x-page-description: Unlock AI-driven answers for your organization's content and data. x-parent: organizations description: | Enhance your team's knowledge base with the Organization AI ask endpoint, which allows you to query AI models trained on your organization's GitBook content for quick, intelligent responses. - name: sites x-page-icon: globe x-page-title: Docs sites x-page-description: Manage your published docs sites. description: | The Docs Sites API lets you programmatically manage published documentation sites within your organization. You can list and update all sites created under a specific organization, making it easy to audit or interact with site metadata at scale. {% openapi-schemas spec="gitbook" schemas="Site" grouped="false" %} The Site object {% endopenapi-schemas %} - name: site-share-links x-page-title: Site share links x-page-description: Control how you share docs externally by managing share links for a site. x-parent: sites description: | Manage the lifecycle of share links for your published sites. This includes generating new links for external sharing and revoking or updating existing ones. {% openapi-schemas spec="gitbook" schemas="ShareLink" grouped="false" %} The ShareLink object {% endopenapi-schemas %} - name: site-structure x-page-title: Site structure x-page-description: Retrieve and manipulate the entire hierarchical layout of a site. x-parent: sites description: | Provides a complete overview of how content is organized on a site. With this API, you can discover page nesting, identify sections, and reorder site elements as needed. {% openapi-schemas spec="gitbook" schemas="SiteStructure" grouped="false" %} The SiteStructure object {% endopenapi-schemas %} - name: site-publishing-auth x-page-title: Site auth x-page-description: Manage the authentication needed for publishing your site. x-parent: sites description: | Configure the credentials or tokens required to publish documentation externally. This helps ensure your site is consistently kept up to date. {% openapi-schemas spec="gitbook" schemas="SitePublishingAuth" grouped="false" %} The SitePublishingAuth object {% endopenapi-schemas %} - name: site-preview x-page-title: Site preview x-page-description: Fetch an up-to-date preview of your site before publishing. x-parent: sites description: | Quickly generate a preview of how your site's content and layout will appear once published, allowing for final checks and refinement prior to going live. - name: site-customization x-page-title: Site customization x-page-description: Customize the look and feel of your docs site. x-parent: sites description: | Update your site's branding, styling, and layout to match your organization's identity. This includes theming elements like color palette, logos, and more. {% openapi-schemas spec="gitbook" schemas="SiteCustomizationSettings" grouped="false" %} The SiteCustomizationSettings object {% endopenapi-schemas %} - name: site-agent-settings x-page-title: Site agent settings x-page-description: Configure site-specific issue remediation behavior and agent instructions. x-parent: sites description: | Configure how site issue remediation should behave and provide site-specific instructions for the editing and topic analyst agents. {% openapi-schemas spec="gitbook" schemas="SiteAgentSettings" grouped="false" %} The SiteAgentSettings object {% endopenapi-schemas %} - name: site-spaces x-page-title: Site spaces x-page-description: Control which spaces are linked and displayed in a docs site. x-parent: sites description: | Associate or dissociate your organization's spaces to keep your content organized. This is particularly useful for larger organizations with numerous spaces. {% openapi-schemas spec="gitbook" schemas="SiteSpace" grouped="false" %} The SiteSpace object {% endopenapi-schemas %} - name: site-sections x-page-title: Site sections x-page-description: Create and organize high-level sections for your docs site. x-parent: sites description: | Sections help partition your site's content at the top level. They can be modified, deleted, or reorganized to reflect your site's changing structure. {% openapi-schemas spec="gitbook" schemas="SiteSection" grouped="false" %} The SiteSection object {% endopenapi-schemas %} - name: site-section-groups x-page-title: Site section groups x-page-description: Group and manage sections of your docs for easier organization. x-parent: sites description: | Section groups let you bundle multiple top-level sections together, offering additional structuring capabilities and simplifying navigation for your readers. {% openapi-schemas spec="gitbook" schemas="SiteSectionGroup" grouped="false" %} The SiteSectionGroup object {% endopenapi-schemas %} - name: site-redirects x-page-title: Site redirects x-page-description: Establish redirects for pages that have moved or changed in your docs site. x-parent: sites description: | Keep your site's content fresh without breaking old links. This API allows you to create and manage redirection rules. {% openapi-schemas spec="gitbook" schemas="SiteRedirect" grouped="false" %} The SiteRedirect object {% endopenapi-schemas %} - name: site-mcp-servers x-page-title: Site MCP servers x-page-description: Configure external MCP servers used by your site. x-parent: sites description: | Manage Model Context Protocol (Mcp) servers used by your site. {% openapi-schemas spec="gitbook" schemas="SiteMcpServer" grouped="false" %} The SiteMcpServer object {% endopenapi-schemas %} - name: site-channels x-page-title: Site channels x-page-description: Configure site channels for your docs site. x-parent: sites description: | Manage the channels used as origins for questions and answers in your site ask data. {% openapi-schemas spec="gitbook" schemas="SiteChannel" grouped="false" %} The SiteChannel object {% endopenapi-schemas %} - name: site-ads x-page-title: Site ads x-page-description: Control and customize ad placements on your docs site. x-parent: sites description: | Manage the advertisement strategy within your docs. You can specify ad placements, track usage, and adjust settings to best fit your organization's needs. - name: site-permissions x-page-title: Site permissions x-page-description: Manage which members and teams can access or contribute to a docs site. x-parent: sites description: | Invite, remove, or update users and teams permissions for a site. This provides a way to tightly control collaboration and visibility among your teammates. - name: site-insights x-page-title: Site insights x-page-description: Analyze traffic and engagement metrics for your docs site. x-parent: sites description: | This API delivers insights about how visitors interact with your site, including page views and user engagement, helping you measure and optimize your content strategy. - name: site-ai x-page-title: Site AI x-page-description: Build conversational AI agents for your docs site. x-parent: sites description: | Build advanced conversational AI experiences within your docs site that go beyond basic Q&A. - name: site-ask x-page-title: Site AI ask x-page-description: Allow AI-driven queries within a specific docs site. x-parent: sites description: | Give your users a way to ask content-aware AI queries that are scoped entirely to the site's published documents. - name: site-context x-page-title: Site context x-page-description: Manage context records, connections, and topics for a docs site. x-parent: sites description: | Manage the contextual records and topics used by your site to power AI experiences and insights. {% openapi-schemas spec="gitbook" schemas="ContextRecord,ContextConnection,SiteTopic,SiteFinding,SiteFindingPage" grouped="false" %} The Site Context objects {% endopenapi-schemas %} - name: site-questions x-page-title: Site questions x-page-description: Review questions, answers, and sources generated for a docs site. x-parent: sites description: | Inspect the canonical questions asked on your site, the generated answers linked to each question, and the sources used for each answer. {% openapi-schemas spec="gitbook" schemas="SiteQuestion,SiteQuestionAnswer,SiteQuestionAnswerWithResponse,SiteQuestionAnswerSource" grouped="false" %} The Site Questions objects {% endopenapi-schemas %} - name: collections x-page-icon: folder x-page-title: Collections x-page-description: Organize and manage grouped sets of spaces for better content structure. description: | Collections let you bundle multiple spaces under a unified entity, making large-scale content easier to handle. You can sort content by subject, department, or any grouping logic. {% openapi-schemas spec="gitbook" schemas="Collection" grouped="false" %} The Collection object {% endopenapi-schemas %} - name: collection-permissions x-page-title: Collection permissions x-page-description: Manage which members and teams can access or contribute to a collection of spaces. x-parent: collections description: | Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content. - name: spaces x-page-icon: book-sparkles x-page-title: Spaces x-page-description: Create, maintain, and remove content spaces. description: | Spaces are containers for your documentation or knowledge base content. Use this API to create new spaces, manage existing ones, and delete or archive spaces you no longer need. {% openapi-schemas spec="gitbook" schemas="Space" grouped="false" %} The Space object {% endopenapi-schemas %} - name: space-content x-page-title: Space content x-page-description: Import, export, and search content in a space. x-parent: spaces description: | Handle your space content programmatically by creating, updating, or listing pages and files. Ideal for bulk operations or synchronizing with external systems. - name: space-comments x-page-title: Space comments x-page-description: Integrate and manage user comments in a space. x-parent: spaces description: | Comments are a powerful way to gather feedback on your documentation. Use this API to post, list, update, or delete comments and keep conversations organized. {% openapi-schemas spec="gitbook" schemas="Comment" grouped="false" %} The Comment object {% endopenapi-schemas %} - name: space-embeds x-page-title: Space embeds x-page-description: Render or resolve embedded content within a space. x-parent: spaces description: | Automatically fetch metadata or previews for embedded resources such as videos, images, or external docs, enabling richer content experiences in your space. - name: space-permissions x-page-title: Space permissions x-page-description: Manage which members and teams roles and permissions on a per-space basis. x-parent: spaces description: | Give your collaborators the right level of access for specific spaces, or assign entire teams to your spaces and streamline the process of granting or revoking access at scale, without dealing with individual user roles. - name: space-integrations x-page-title: Space integrations x-page-description: Connect external tools and plugins to enhance your space functionality. x-parent: spaces description: | This API handles the registration and removal of integrations, automating how data flows between GitBook and your chosen external services. - name: space-git x-page-title: Git x-page-description: Connect Git repositories to your space for seamless version control. x-parent: spaces description: | Manage the linkage between your GitBook space and external Git repositories, enabling commits, merges, and pull requests directly tied to your documentation. - name: change-requests x-page-icon: code-pull-request x-page-title: Change requests x-page-description: Review and collaborate on proposed documentation changes before merging. description: | This API helps you keep your space clean by letting contributors propose changes, review them, and then merge or discard as needed. {% openapi-schemas spec="gitbook" schemas="ChangeRequest" grouped="false" %} The ChangeRequest object {% endopenapi-schemas %} - name: change-request-content x-page-title: Change request content x-page-description: Manage the actual content changes associated with a change request. x-parent: change-requests description: | Retrieve or update the pages and files tied to an open change request. This lets you preview alterations and merge them when ready. - name: change-request-contributors x-page-title: Change request contributors x-page-description: See who's participating in the change request. x-parent: change-requests description: | Quickly access the full list of collaborators and their contributions within a change request for better traceability and communication. {% openapi-schemas spec="gitbook" schemas="UserContributor" grouped="false" %} The UserContributor object {% endopenapi-schemas %} - name: change-request-reviewers x-page-title: Change request reviewers x-page-description: Assign or list requested reviewers for a change request. x-parent: change-requests description: | Ensure quality by requesting and tracking reviewer feedback in your GitBook flow. This endpoint helps orchestrate the entire review cycle. {% openapi-schemas spec="gitbook" schemas="ChangeRequestRequestedReviewer" grouped="false" %} The ChangeRequestRequestedReviewer object {% endopenapi-schemas %} - name: change-request-comments x-page-title: Change request comments x-page-description: Engage in threaded conversations on proposed changes. x-parent: change-requests description: | This API powers the inline discussion around any new or updated documentation. Participate in comment threads and resolve them after reaching consensus. {% openapi-schemas spec="gitbook" schemas="Comment" grouped="false" %} The Comment object {% endopenapi-schemas %} - name: analytics x-page-icon: chart-line x-page-title: Analytics x-page-description: Tap into metrics that reveal your content's performance and usage patterns. description: | Gather data-driven insights on how users interact with your spaces, pages, or entire site. Analytics can highlight trends and guide future content improvements. - name: translations x-page-icon: language x-page-title: Translations x-page-description: Configure multi-language support and translation options for your documentation. description: | The Translations API provides ways to localize your content into various languages. It supports custom strings, default language settings, and more. - name: translation-languages x-page-title: Translations languages x-page-description: Manage the individual language configurations for your docs translation setup. x-parent: translations description: | Enable or disable specific languages, configure default text direction, or adjust advanced translation settings to ensure clarity for your global audience. {% openapi-schemas spec="gitbook" schemas="TranslationLanguageSettings" grouped="false" %} The TranslationLanguageSettings object {% endopenapi-schemas %} - name: imports x-page-icon: cloud-arrow-up x-page-title: Imports x-page-description: Import content into GitBook. description: | The Imports API provides allows you to import content into GitBook. - name: glossary x-page-title: Glossary x-page-description: Manage custom terms translations used by the translation feature. x-parent: translations description: | Define terms and specify their translations for different languages to ensure consistent wording. {% openapi-schemas spec="gitbook" schemas="GlossaryEntry" grouped="false" %} The GlossaryEntry object {% endopenapi-schemas %} - name: integrations x-page-icon: puzzle-piece x-page-title: Integrations x-page-description: Install and handle third-party integrations for extended GitBook functionality. description: | Expand the capabilities of GitBook by connecting it with various external platforms—CRM, finding trackers, or CI/CD pipelines—through standardized integration endpoints. - name: urls x-page-icon: link x-page-title: URLs x-page-description: Configure where and how your GitBook content can be accessed. description: | Manage official endpoints, direct deep links, or short links for your content. This allows you to keep track of multiple custom URLs or vanity links under one system. - name: openapi x-page-icon: code x-page-title: OpenAPI x-page-description: Upload, access, or version-control your OpenAPI specifications directly in GitBook. description: | The OpenAPI endpoints let you integrate your existing or newly generated OpenAPI definitions into GitBook. This includes uploading, updating, and retrieving specs. {% openapi-schemas spec="gitbook" schemas="OpenAPISpec" grouped="false" %} The OpenAPISpec object {% endopenapi-schemas %} - name: openapi-versions x-page-title: OpenAPI spec versions x-page-description: Track changes to your OpenAPI documents by versioning them. x-parent: openapi description: | Keep a history of your OpenAPI specs, enabling you to compare different versions, revert, or maintain multiple concurrent versions for testing or documentation. {% openapi-schemas spec="gitbook" schemas="OpenAPISpecVersion" grouped="false" %} The OpenAPISpecVersion object {% endopenapi-schemas %} - name: custom-fonts x-page-icon: font x-page-title: Custom fonts x-page-description: Bring your own fonts to personalize your documentation style. description: | Upload and manage custom fonts for branding or aesthetic purposes. Once added, fonts can be applied to your spaces or sites to achieve a unique look. {% openapi-schemas spec="gitbook" schemas="CustomizationFontDefinition" grouped="false" %} The CustomizationFontDefinition object {% endopenapi-schemas %} - name: billing x-page-icon: credit-card x-page-title: Billing x-page-description: Organize payment details and subscription plans for your organization. description: | Centralize billing activities here, including updating payment methods, adjusting subscriptions, or reviewing invoices. Simplify how you track and control costs. - name: hive x-page-icon: network-wired x-page-title: Hive x-page-description: Bring teams together and share resources effectively across GitBook. description: | Hive is a collaborative layer over your GitBook data, designed to streamline knowledge sharing, cross-project tasks, and reduce duplicate efforts among your teammates. - name: subdomains x-page-icon: diagram-project x-page-title: Subdomains x-page-description: Manage and configure organization-specific subdomains for your docs. description: | Provide a branded subdomain for each organization to create a consistent user experience. This API supports subdomain creation, DNS checks, and more. {% openapi-schemas spec="gitbook" schemas="Subdomain" grouped="false" %} The Subdomain object {% endopenapi-schemas %} - name: users x-page-icon: users x-page-title: Users x-page-description: Retrieve and manage user information and profiles. description: | The Users API allows you to fetch data about GitBook users, including the authenticated account or other team members by ID. This is crucial for customizing permissions, personalizing content, or establishing user-specific flows. {% openapi-schemas spec="gitbook" schemas="User" grouped="false" %} The User object {% endopenapi-schemas %} - name: teams x-page-icon: people-group x-page-title: Teams x-page-description: Create and manage teams as reusable groups of users. description: | Teams offer a convenient way to assign roles and access to multiple users at once. This helps maintain large-scale projects more efficiently by reducing overhead in user-by-user management. {% openapi-schemas spec="gitbook" schemas="Team" grouped="false" %} The Team object {% endopenapi-schemas %} - 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 %} - name: sso x-page-icon: lock x-page-title: SSO x-page-description: Configure Single Sign-On solutions to unify your organization's authentication. description: | Tie GitBook into your corporate identity management and authentication providers (like SAML or OAuth). This centralizes user authentication and improves security. {% openapi-schemas spec="gitbook" schemas="Subdomain" grouped="false" %} The Subdomain object {% endopenapi-schemas %} - name: storage x-page-icon: database x-page-title: Storage x-page-description: Upload and store files directly within your GitBook organization. description: | Whether you're hosting images, documents, or other assets, Storage endpoints allow you to integrate those files into your documentation and spaces seamlessly. - name: custom-hostnames x-page-icon: server x-page-title: Custom hostnames x-page-description: Serve your GitBook content from fully branded, custom hostnames. description: | Extend your brand identity by mapping personalized domain names to your docs. This can help unify your documentation site with your existing company properties. {% openapi-schemas spec="gitbook" schemas="CustomHostname" grouped="false" %} The CustomHostname object {% endopenapi-schemas %} - name: system x-page-icon: gears x-page-title: System info x-page-description: Programmatically check GitBook API system status and version details. description: | Use these endpoints to monitor the overall health of GitBook's infrastructure or to retrieve version information for debugging and compliance purposes. paths: /: get: operationId: getApiInformation tags: - system summary: Get API information description: Access the release version and build date of the GitBook codebase. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ApiInformation" /user: get: operationId: getAuthenticatedUser summary: Get profile of authenticated user tags: - users - critical security: - user: [] description: | Returns details about the user associated with the authentication provided in the request's authorization header. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "404": description: User not found $ref: "#/components/responses/NotFoundError" /user/notifications/token: post: operationId: createUserNotificationsToken summary: Create a JWT to access the in-app notifications service description: | Generates a JWT for the authenticated user. This token is used by the frontend notifications client to access user endpoints. tags: - users security: - user-internal: [] responses: "200": description: The notifications service User JWT content: application/json: schema: $ref: "#/components/schemas/APITemporaryToken" "/users/{userId}": get: operationId: getUserById summary: Get a user by its ID tags: - users - critical security: - user: [] description: | Provides publicly available information about someone with a GitBook account. parameters: - $ref: "#/components/parameters/userId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "404": description: User not found $ref: "#/components/responses/NotFoundError" patch: operationId: updateUserById summary: Update a user by its ID tags: - users - critical security: - user: [] description: | Update a GitBook account's details. parameters: - $ref: "#/components/parameters/userId" requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: displayName: type: string description: Full name for the user minLength: 1 maxLength: 64 photoURL: $ref: "#/components/schemas/URL" responses: "200": description: The user has been updated content: application/json: schema: $ref: "#/components/schemas/User" "404": description: User not found $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}": get: operationId: getSpaceById summary: Get a space by its ID tags: - spaces - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/siteShareKey" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Space" patch: operationId: updateSpaceById summary: Update a space tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" requestBody: required: true content: application/json: schema: allOf: - type: object properties: editMode: $ref: "#/components/schemas/SpaceEditMode" title: $ref: "#/components/schemas/SpaceTitle" defaultLevel: $ref: "#/components/schemas/DefaultLevel" language: $ref: "#/components/schemas/TranslationLanguage" mergeRules: $ref: "#/components/schemas/MergeRulesSpaceConfiguration" - oneOf: - type: object title: Emoji properties: emoji: $ref: "#/components/schemas/Emoji" required: - emoji - type: object title: Icon properties: icon: $ref: "#/components/schemas/URL" required: - icon - type: object title: Remove icon or emoji properties: emoji: type: "null" icon: type: "null" responses: "200": description: The space has been updated content: application/json: schema: $ref: "#/components/schemas/Space" delete: operationId: deleteSpaceById summary: Delete a space description: Deleted spaces will be permanently removed after 7 days. tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "204": description: Space did not exist "205": description: Space has been deleted "/spaces/{spaceId}/duplicate": post: operationId: duplicateSpace summary: Duplicate a space tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "201": description: Space duplicated headers: Location: description: API URL for the newly created space schema: type: string content: application/json: schema: $ref: "#/components/schemas/Space" "/spaces/{spaceId}/restore": post: operationId: restoreSpace summary: Restore a deleted space description: Only spaces deleted in the last 7 days can be restored. tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "200": description: Space restored content: application/json: schema: $ref: "#/components/schemas/Space" "/spaces/{spaceId}/move": post: operationId: moveSpace summary: Move a space to a new position tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: parent: description: The unique id of the parent collection type: - string - "null" position: description: Where to move the space. By default, it will be moved at the end. $ref: "#/components/schemas/ContentPosition" responses: "200": description: Space moved content: application/json: schema: $ref: "#/components/schemas/Space" "400": description: Invalid position space or collection provided $ref: "#/components/responses/BadRequestError" "404": description: No matching Space found for given ID $ref: "#/components/responses/NotFoundError" "409": description: Operation would not result in any update $ref: "#/components/responses/ConflictError" "/spaces/{spaceId}/embed": get: operationId: getEmbedByUrlInSpace summary: Resolve a URL to an embed in a given space tags: - space-embeds security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - name: url in: query required: true description: URL to resolve schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Embed" "/spaces/{spaceId}/search": get: operationId: searchSpaceContent summary: Search content in a space tags: - space-content security: - user: [] parameters: - name: query in: query required: true schema: type: string maxLength: 512 - $ref: "#/components/parameters/spaceId" - $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/SearchPageResult" "/spaces/{spaceId}/git/import": post: operationId: importGitRepository summary: Import a Git repository tags: - space-git security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "204": description: Operation to import the repository has been started. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ImportGitRepository" "/spaces/{spaceId}/git/export": post: operationId: exportToGitRepository summary: Export the to a Git repository tags: - space-git security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "204": description: Operation to export the space has been started. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ExportToGitRepository" "/spaces/{spaceId}/git/info": get: operationId: getSpaceGitInfo summary: Get space Git info description: Get metadata about the Git Sync provider currently set up on the space. tags: - space-git security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "200": description: The Git Sync info for the space content: application/json: schema: $ref: "#/components/schemas/GitSyncState" "404": description: No Git provider currently set up on the space $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/git/legacy-installation": delete: operationId: deleteLegacyGitInstallation summary: Remove the legacy Git Sync installation from the space to be able to upgrade it to use the new Git integrations tags: - space-git security: - user-internal: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "204": description: The legacy Git installation was already removed "205": description: The legacy Git installation was successfully removed "/spaces/{spaceId}/permissions": post: operationId: inviteToSpace summary: Invite a user or a team to a space tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "204": description: OK "404": description: No team or user with the provided Id $ref: "#/components/responses/NotFoundError" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InviteUsersAndTeams" "/spaces/{spaceId}/permissions/teams/{teamId}": patch: operationId: updateTeamPermissionInSpace summary: Update an org team's permission in a space tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/teamId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" responses: "204": description: Team permission was updated "404": description: No team found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeTeamFromSpace summary: Remove an org team from a space tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/teamId" responses: "204": description: The team was not found in the space "205": description: The team has been removed from the space "400": description: Team does not have access to space $ref: "#/components/responses/BadRequestError" "/spaces/{spaceId}/permissions/users": get: operationId: listUserPermissionsInSpace summary: List space user permissions tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of users who have been added to a space. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserContentPermission" "404": description: No space was found with the given Id $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/permissions/users/{userId}": patch: operationId: updateUserPermissionInSpace summary: Update space user permissions tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/userId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" responses: "204": description: User permission was updated "404": description: No user found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeUserFromSpace summary: Remove a space user tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/userId" responses: "204": description: The user was not found in the space "205": description: The user has been removed from the space "/spaces/{spaceId}/permissions/teams": get: operationId: listTeamPermissionsInSpace summary: List an org team's permission in a space tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of teams who have been added to a space. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: type: object description: Permission of a team in a space. properties: permission: $ref: "#/components/schemas/MemberRole" team: $ref: "#/components/schemas/OrganizationTeam" required: - permission - team "404": description: No space was found with the given Id $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/content": get: operationId: getCurrentRevision summary: Get a space current revision tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Revision" "/spaces/{spaceId}/content/template": post: operationId: applyTemplateToSpace summary: Apply a template to a space. tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "201": description: Template applied to space. requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/ApplySpaceTemplate" - type: object properties: changeRequestId: type: string description: The ID of the change request to apply the template to. If not provided, the template is applied to the main content. "/spaces/{spaceId}/content/pages": get: operationId: listPages summary: List all space pages tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/RevisionPage" required: - pages "/spaces/{spaceId}/content/files": get: operationId: listFiles summary: List all space files tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" 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/RevisionFile" "/spaces/{spaceId}/content/files/{fileId}": get: operationId: getFileById summary: Get a space file by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/fileId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionFile" "/spaces/{spaceId}/content/files/{fileId}/backlinks": get: operationId: listSpaceFileBacklinks summary: List all space file backlink locations tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/fileId" - $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/ContentLocation" "/spaces/{spaceId}/content/page/{pageId}": get: operationId: getPageById summary: Get a space page by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPage" "/spaces/{spaceId}/content/page/{pageId}/links": get: operationId: listPageLinksInSpace summary: List all space page links tags: - space-content - links - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: status in: query schema: $ref: "#/components/schemas/ContentReferenceStatus" responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object properties: stats: $ref: "#/components/schemas/ContentReferencesStats" items: type: array items: $ref: "#/components/schemas/ContentReferenceUsage" required: - items - stats "/spaces/{spaceId}/content/page/{pageId}/backlinks": get: operationId: listSpacePageBacklinks summary: List all space page backlink locations tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/pageId" - $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/ContentLocation" "/spaces/{spaceId}/content/page/{pageId}/meta-links": get: operationId: listSpacePageMetaLinks summary: List all meta links for a space page tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/pageId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPageMetaLinks" "/spaces/{spaceId}/content/path/{pagePath}": get: operationId: getPageByPath summary: Get a space page by its path tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/pagePath" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageGroup" "/spaces/{spaceId}/content/reusable-contents/{reusableContentId}": get: operationId: getReusableContentById summary: Get a space reusable content by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/reusableContentId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionReusableContent" "/spaces/{spaceId}/content/computed/document": post: operationId: getComputedDocument summary: Get a space computed document tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/documentSchema" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/ComputedContentSourceDocument" seed: type: string description: Seed to use for the generation of IDs. required: - source - seed responses: "200": description: Document computed content: application/json: schema: $ref: "#/components/schemas/JSONDocument" "/spaces/{spaceId}/content/computed/revision": post: operationId: getComputedRevision summary: Get a space computed revision tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/ComputedContentSourceRevision" seed: type: string description: Seed to use for the generation of IDs. required: - source - seed responses: "200": description: Computed pages and files content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/RevisionPage" files: type: array items: $ref: "#/components/schemas/RevisionFile" reusableContents: type: array items: $ref: "#/components/schemas/RevisionReusableContent" required: - pages - files - reusableContents "/spaces/{spaceId}/documents/{documentId}": get: operationId: getDocumentById summary: Get a space document by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - name: documentId in: path required: true description: ID of the document in the space schema: type: string - $ref: "#/components/parameters/documentSchema" responses: "200": description: Document content: application/json: schema: $ref: "#/components/schemas/JSONDocument" "/spaces/{spaceId}/change-requests": post: operationId: createChangeRequest summary: Create a change request tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" responses: "201": description: Change Request Created headers: Location: description: API URL for the newly created change-request schema: type: string content: application/json: schema: $ref: "#/components/schemas/ChangeRequest" requestBody: required: true content: application/json: schema: type: object properties: subject: type: string description: Subject of the change-request template: $ref: "#/components/schemas/ApplySpaceTemplate" description: Template to apply to the change request additionalProperties: true get: operationId: listChangeRequestsForSpace summary: List all change requests tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/spaceId" - name: status in: query required: false schema: $ref: "#/components/schemas/ChangeRequestStatus" default: open description: If defined, only change requests matching this status will be returned. - name: creator in: query required: false schema: type: string description: If defined, only change requests created by this user will be returned. - name: contributor in: query required: false schema: type: string description: If defined, only change requests with contributions from this user will be returned. - name: requestedReviewer in: query required: false schema: type: string description: If defined, only change requests with a requested reviewer for this user will be returned. - name: topic in: query required: false schema: type: string description: If defined, only change requests linked to this site topic will be returned. - name: orderBy in: query required: false schema: $ref: "#/components/schemas/ChangeRequestOrderBy" responses: "200": description: List of the space's change requests content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequest" "/spaces/{spaceId}/change-requests/{changeRequestId}": get: operationId: getChangeRequestById summary: Get a change request by its ID tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "200": description: The matching change request content: application/json: schema: $ref: "#/components/schemas/ChangeRequest" "404": description: The change request could not be found. $ref: "#/components/responses/NotFoundError" patch: operationId: updateChangeRequestById summary: Update a change request tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" requestBody: required: true content: application/json: schema: type: object properties: subject: $ref: "#/components/schemas/ChangeRequestSubject" description: $ref: "#/components/schemas/JSONDocument" links: $ref: "#/components/schemas/ChangeRequestLinks" status: type: string enum: - draft - open - archived responses: "200": description: The change request has been updated content: application/json: schema: $ref: "#/components/schemas/ChangeRequest" "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": post: operationId: mergeChangeRequest summary: Merge a change request tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "200": description: OK content: application/json: schema: type: object properties: revision: type: string description: ID of the resulting revision result: type: string enum: - merge - conflicts required: - revision - result "/spaces/{spaceId}/change-requests/{changeRequestId}/update": post: operationId: updateChangeRequest summary: Pull primary content into the change request tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "200": description: OK content: application/json: schema: type: object properties: revision: type: string description: ID of the resulting revision result: type: string enum: - update - conflicts required: - revision - result "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": get: operationId: getReviewsByChangeRequestId summary: List all change request reviews tags: - change-requests-reviews security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/documentFormat" - in: query name: outdated description: Filter reviews marked as outdated. schema: type: boolean - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: All reviews for the given change request. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequestReview" "404": description: The change request or space could not be found. $ref: "#/components/responses/NotFoundError" post: operationId: submitChangeRequestReview summary: Submit a change request review tags: - change-requests-reviews security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "201": headers: Location: description: API URL for the newly created review schema: type: string description: A new review has been created. content: application/json: schema: $ref: "#/components/schemas/ChangeRequestReview" requestBody: required: true content: application/json: schema: type: object properties: status: description: The status of the submitted review. $ref: "#/components/schemas/ChangeRequestReviewStatus" comment: description: Optionally, provide a comment along with the review. $ref: "#/components/schemas/Document" required: - status "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews/{reviewId}": get: operationId: getChangeRequestReviewById summary: Get a change request review by its ID tags: - change-requests-reviews security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/reviewId" - $ref: "#/components/parameters/documentFormat" responses: "200": description: The matching change request review. content: application/json: schema: $ref: "#/components/schemas/ChangeRequestReview" "404": description: The change request review could not be found. $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers": get: operationId: getRequestedReviewersByChangeRequestId summary: Get all change request reviewers tags: - change-request-reviewers security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: A list of requested reviewers content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequestRequestedReviewer" post: operationId: requestReviewersForChangeRequest summary: Request change request reviewers tags: - change-request-reviewers security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "200": description: The requests have successfully been sent. content: application/json: schema: type: object properties: users: type: array description: The user requests that were sent. items: $ref: "#/components/schemas/ChangeRequestRequestedReviewer" requestBody: required: true content: application/json: schema: type: object properties: users: type: array description: An array of user ids that will be requested. items: type: string subject: type: string description: Optionally, update the subject of the change request when requesting reviewers. description: $ref: "#/components/schemas/JSONDocument" description: Optionally, update the description of the change request when requesting reviewers. required: - users "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers/{userId}": delete: operationId: removeRequestedReviewerFromChangeRequest summary: Remove a reviewer from a change request tags: - change-request-reviewers security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/userId" responses: "204": description: Reviewer was not found "205": description: The reviewer has been removed from the change request "/spaces/{spaceId}/change-requests/{changeRequestId}/links": get: operationId: listChangeRequestLinks summary: List all change request links tags: - change-requests-links - links - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: status in: query required: false schema: $ref: "#/components/schemas/ContentReferenceStatus" - name: brokenContext in: query required: false schema: type: string enum: - change-request - space responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object properties: stats: $ref: "#/components/schemas/ContentReferencesStats" items: type: array items: $ref: "#/components/schemas/ContentReferenceUsage" required: - items - stats "404": description: The change request could not be found. $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/change-requests/{changeRequestId}/comments": get: operationId: listCommentsInChangeRequest summary: List all change request comments tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/listOrder" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/status" - $ref: "#/components/parameters/targetPage" - $ref: "#/components/parameters/authors" 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/Comment" post: operationId: postCommentInChangeRequest summary: Create a change request comment tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostCommentSchema" responses: "200": description: The comment was posted. content: application/json: schema: $ref: "#/components/schemas/Comment" "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}": get: operationId: getCommentInChangeRequest summary: Get a change request comment tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/documentFormat" responses: "200": description: The returned comment. content: application/json: schema: $ref: "#/components/schemas/Comment" delete: operationId: deleteCommentInChangeRequest summary: Delete a change request comment tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" responses: "204": description: Comment did not exist. "205": description: The comment has been deleted. put: operationId: updateCommentInChangeRequest summary: Update a change request comment tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateCommentSchema" responses: "200": description: The comment was updated. content: application/json: schema: $ref: "#/components/schemas/Comment" "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies": get: operationId: listCommentRepliesInChangeRequest summary: List all change request comment replies tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/documentFormat" 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/CommentReply" post: operationId: postCommentReplyInChangeRequest summary: Create a change request comment reply tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/documentFormat" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostCommentReplySchema" responses: "200": description: The reply was posted. content: application/json: schema: $ref: "#/components/schemas/CommentReply" "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies/{commentReplyId}": get: operationId: getCommentReplyInChangeRequest summary: Get a change request comment reply tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" - $ref: "#/components/parameters/documentFormat" responses: "200": description: The returned comment reply. content: application/json: schema: $ref: "#/components/schemas/CommentReply" put: operationId: updateCommentReplyInChangeRequest summary: Update a change request comment reply tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateCommentSchema" responses: "200": description: The reply was updated. content: application/json: schema: $ref: "#/components/schemas/CommentReply" delete: operationId: deleteCommentReplyInChangeRequest summary: Delete a change request comment reply tags: - change-request-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" responses: "204": description: Comment reply did not exist. "205": description: The comment has been deleted. "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": get: operationId: getContributorsByChangeRequestId summary: Get all contribors of a change request tags: - change-request-contributors security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" responses: "200": description: Contributors on the change request content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequestUserContributor" "404": description: The change request could not be found. $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/change-requests/{changeRequestId}/content": get: operationId: getRevisionOfChangeRequestById summary: Get a change request the latest content revision tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Revision" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/pages": get: operationId: listPagesInChangeRequest summary: List all change request pages tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/RevisionPage" required: - pages "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files": get: operationId: listFilesInChangeRequestById summary: List all change request files tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" 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/RevisionFile" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}": get: operationId: getFileInChangeRequestById summary: Get a change request file by its ID tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/fileId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionFile" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}/backlinks": get: operationId: listChangeRequestFileBacklinks summary: List all backlink locations of a change request file tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/fileId" - $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/ContentLocation" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}": get: operationId: getPageInChangeRequestById summary: Get a change request page by its ID tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPage" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/links": get: operationId: listPageLinksInChangeRequest summary: List all change request links tags: - change-request-content - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object properties: stats: $ref: "#/components/schemas/ContentReferencesStats" items: type: array items: $ref: "#/components/schemas/ContentReferenceUsage" required: - items - stats "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/backlinks": get: operationId: listChangeRequestPageBacklinks summary: List all backlink locations of a change request page tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/pageId" - $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/ContentLocation" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/meta-links": get: operationId: listChangeRequestPageMetaLinks summary: List all meta links of a change request page tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/pageId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPageMetaLinks" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/reusable-contents/{reusableContentId}": get: operationId: getReusableContentInChangeRequestById summary: Get a change request reusable content by its ID tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/reusableContentId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionReusableContent" "/spaces/{spaceId}/change-requests/{changeRequestId}/changes": get: operationId: getChangeRequestChanges summary: Get change request semantic changes description: Return the semantic changes between a change request and its base revision. tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - name: limit in: query description: Limit the number of changes returned schema: type: number default: 10 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionSemanticChanges" "404": description: The change request could not be found. $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/change-requests/{changeRequestId}/pdf": get: operationId: getChangeRequestPDF summary: Get a URL of the content of a change request as PDF tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - in: query name: only description: Generate a PDF only for the provided page. schema: type: boolean - in: query name: page description: ID of a specific page to generate a PDF for. schema: type: string responses: "200": description: URL of the PDF content: application/json: schema: type: object properties: url: description: Temporary URL to print the content. The URL will work for 1h. $ref: "#/components/schemas/URL" required: - url "/spaces/{spaceId}/revisions/{revisionId}": get: operationId: getRevisionById summary: Get a space revision tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Revision" "/spaces/{spaceId}/revisions/{revisionId}/changes": get: operationId: getRevisionSemanticChanges summary: Get space revision semantic changes description: Return the semantic changes between a revision and its parent. tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" - name: limit in: query description: Limit the number of changes returned schema: type: number default: 10 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionSemanticChanges" "/spaces/{spaceId}/revisions/{revisionId}/pages": get: summary: List all pages in a space revision operationId: listPagesInRevisionById tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: type: object properties: pages: type: array items: $ref: "#/components/schemas/RevisionPage" required: - pages "/spaces/{spaceId}/revisions/{revisionId}/files": get: summary: List all space revision files operationId: listFilesInRevisionById tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" 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/RevisionFile" "/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}": get: summary: Get a space revision file by its ID operationId: getFileInRevisionById tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/fileId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionFile" "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": get: operationId: getPageInRevisionById summary: Get a space revision page by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPage" "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}/document": get: operationId: getPageDocumentInRevisionById summary: Get the document of a page in a revision tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/pageId" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/JSONDocument" "/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}": get: operationId: getPageInRevisionByPath summary: Get a space revision page by its path tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/pagePath" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageGroup" "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}/meta-links": get: operationId: listRevisionPageMetaLinks summary: List all meta links for a revision page tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/pageId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionPageMetaLinks" "/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}": get: operationId: getPageInChangeRequestByPath summary: Get a change request page by its path tags: - change-request-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $ref: "#/components/parameters/pagePath" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageGroup" "/spaces/{spaceId}/revisions/{revisionId}/reusable-contents/{reusableContentId}": get: operationId: getReusableContentInRevisionById summary: Get a space revision reusable content by its ID tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/reusableContentId" - $ref: "#/components/parameters/revisionMetadata" - $ref: "#/components/parameters/revisionComputed" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/RevisionReusableContent" "/spaces/{spaceId}/revisions/{revisionId}/reusable-contents/{reusableContentId}/document": get: operationId: getReusableContentDocumentInRevisionById summary: Get the document of a reusable content in a revision tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/revisionId" - $ref: "#/components/parameters/reusableContentId" - $ref: "#/components/parameters/documentEvaluated" - $ref: "#/components/parameters/documentDereferenced" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/JSONDocument" "/spaces/{spaceId}/comments": get: operationId: listCommentsInSpace summary: List all space comments tags: - space-comments - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/listOrder" - $ref: "#/components/parameters/status" - $ref: "#/components/parameters/documentFormat" - $ref: "#/components/parameters/targetPage" - $ref: "#/components/parameters/authors" 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/Comment" post: operationId: postCommentInSpace summary: Create a space comment tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostCommentSchema" responses: "200": description: The comment was posted. content: application/json: schema: $ref: "#/components/schemas/Comment" "/spaces/{spaceId}/comments/{commentId}": get: operationId: getCommentInSpace summary: Get a space comment tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/documentFormat" responses: "200": description: The returned comment. content: application/json: schema: $ref: "#/components/schemas/Comment" delete: operationId: deleteCommentInSpace summary: Delete a space comment tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" responses: "204": description: Comment did not exist. "205": description: The comment has been deleted. put: operationId: updateCommentInSpace summary: Update a space comment tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateCommentSchema" responses: "200": description: The comment was updated. content: application/json: schema: $ref: "#/components/schemas/Comment" "/spaces/{spaceId}/comments/{commentId}/replies": get: operationId: listCommentRepliesInSpace summary: List all space comment replies tags: - space-comment security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/documentFormat" 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/CommentReply" post: operationId: postCommentReplyInSpace summary: Create a space comment reply tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostCommentReplySchema" responses: "200": description: The reply was posted. content: application/json: schema: $ref: "#/components/schemas/CommentReply" "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": get: operationId: getCommentReplyInSpace summary: Get a space comment reply tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" - $ref: "#/components/parameters/documentFormat" responses: "200": description: The returned comment reply. content: application/json: schema: $ref: "#/components/schemas/CommentReply" put: operationId: updateCommentReplyInSpace summary: Update a space comment reply tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateCommentReplySchema" responses: "200": description: The reply was updated. content: application/json: schema: $ref: "#/components/schemas/CommentReply" delete: operationId: deleteCommentReplyInSpace summary: Delete a space comment reply tags: - space-comments security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/commentId" - $ref: "#/components/parameters/commentReplyId" responses: "204": description: Comment reply did not exist. "205": description: The comment has been deleted. "/spaces/{spaceId}/commenters": get: operationId: listCommentersInSpace summary: List all users who commented in a space tags: - space-comments - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $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/OrganizationMember" "/spaces/{spaceId}/change-requests/{changeRequestId}/commenters": get: operationId: listCommentersInChangeRequest summary: List all users who commented in a CR tags: - change-request-comments - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/changeRequestId" - $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/OrganizationMember" "/spaces/{spaceId}/permissions/aggregate": get: operationId: listPermissionsAggregateInSpace summary: List all space users permissions tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: role in: query description: If defined, only members with this role will be returned. schema: $ref: "#/components/schemas/MemberRole" responses: "200": description: Listing of users who can access the space. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserContentPermission" "/spaces/{spaceId}/integrations": get: operationId: listSpaceIntegrations summary: List integrations enabled in a space tags: - space-integrations security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/integrationSearchQuery" responses: "200": description: Listing of integrations enabled in the space. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/Integration" "/spaces/{spaceId}/integration-blocks": get: operationId: listSpaceIntegrationsBlocks summary: List all space integrations blocks tags: - space-integrations parameters: - $ref: "#/components/parameters/spaceId" responses: "200": description: list of installed integration blocks content: application/json: schema: $ref: "#/components/schemas/SpaceIntegrationBlocks" "404": $ref: "#/components/responses/NotFoundError" "/spaces/{spaceId}/pdf": get: operationId: getSpacePDF summary: Get a URL of the content of a space as PDF tags: - space-content security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - in: query name: only description: Generate a PDF only for the provided page. schema: type: boolean - in: query name: page description: ID of a specific page to generate a PDF for. schema: type: string responses: "200": description: URL of the PDF content: application/json: schema: type: object properties: url: description: Temporary URL to print the content. The URL will work for 1h. $ref: "#/components/schemas/URL" required: - url "/spaces/{spaceId}/links": get: operationId: listSpaceLinks summary: Get all links in a space including their status and location where they appear. tags: - spaces - links - critical security: - user: [] parameters: - $ref: "#/components/parameters/spaceId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: status in: query schema: $ref: "#/components/schemas/ContentReferenceStatus" responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object properties: stats: $ref: "#/components/schemas/ContentReferencesStats" items: type: array items: $ref: "#/components/schemas/ContentReferenceUsage" required: - items - stats "404": description: The space could not be found. $ref: "#/components/responses/NotFoundError" "/collections/{collectionId}": get: operationId: getCollectionById summary: Get a collection by its ID tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Collection" patch: operationId: updateCollectionById summary: Update a collection tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/CollectionTitle" description: $ref: "#/components/schemas/CollectionDescription" defaultLevel: $ref: "#/components/schemas/DefaultLevel" responses: "200": description: The collection has been updated content: application/json: schema: $ref: "#/components/schemas/Collection" delete: operationId: deleteCollectionById summary: Delete a collection tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" responses: "204": description: Collection did not exist "205": description: Collection has been deleted "/collections/{collectionId}/spaces": get: operationId: listSpacesInCollectionById summary: List all collection spaces tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $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/Space" "/collections/{collectionId}/move": post: operationId: moveCollection summary: Move a collection to a new position. tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: parent: description: The unique id of the parent collection type: - string - "null" position: description: Where to move the collection. By default, it will be moved at the end. $ref: "#/components/schemas/ContentPosition" responses: "200": description: Collection moved content: application/json: schema: $ref: "#/components/schemas/Collection" "400": description: Invalid position space or collection provided $ref: "#/components/responses/BadRequestError" "404": description: No matching Collection found for given ID $ref: "#/components/responses/NotFoundError" "409": description: Operation would not result in any update $ref: "#/components/responses/ConflictError" "/collections/{collectionId}/transfer": post: operationId: transferCollection summary: Transfer a collection tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" requestBody: required: true content: application/json: schema: type: object properties: organization: type: string description: The unique id of the target organization required: - organization responses: "200": description: Collection transferred content: application/json: schema: $ref: "#/components/schemas/Collection" "404": description: No matching Collection found for given ID $ref: "#/components/responses/NotFoundError" "409": description: Transfer would not result in any update $ref: "#/components/responses/ConflictError" "412": description: The collection cannot be moved. $ref: "#/components/responses/PreconditionFailedError" "/collections/{collectionId}/permissions": post: operationId: inviteToCollection summary: Invite to a collection tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" responses: "204": description: OK "404": description: No team or user with the provided Id $ref: "#/components/responses/NotFoundError" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InviteUsersAndTeams" "/collections/{collectionId}/permissions/teams": get: operationId: listTeamPermissionsInCollection summary: List an org team's permission in collection tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of teams who have been added to a collection. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: type: object description: Permission of a team in a content. properties: permission: $ref: "#/components/schemas/MemberRole" team: $ref: "#/components/schemas/OrganizationTeam" required: - permission - team "/collections/{collectionId}/permissions/teams/{teamId}": patch: operationId: updateTeamPermissionInCollection summary: Update an org team's permission in a collection tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/teamId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" responses: "204": description: Team permission was updated "404": description: No team found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeTeamFromCollection summary: Remove an org team from a collection tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/teamId" responses: "204": description: The team was not found in the collection "205": description: The team has been removed from the collection "/collections/{collectionId}/permissions/users": get: operationId: listUserPermissionsInCollection summary: List collection user permissions tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of users who have been added to a collection. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserContentPermission" "404": description: No space found with the given Id $ref: "#/components/responses/NotFoundError" "/collections/{collectionId}/permissions/users/{userId}": patch: operationId: updateUserPermissionInCollection summary: Update a collection user permission tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/userId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" responses: "204": description: User permission was updated "404": description: No user found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeUserFromCollection summary: Remove a user from a collection tags: - collection-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/userId" responses: "204": description: The user was not found in the collection "205": description: The user has been removed from the collection "/collections/{collectionId}/permissions/aggregate": get: operationId: listPermissionsAggregateInCollection summary: List all collections users permissions tags: - space-permissions security: - user: [] parameters: - $ref: "#/components/parameters/collectionId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: role in: query description: If defined, only members with this role will be returned. schema: $ref: "#/components/schemas/MemberRole" responses: "200": description: Listing of users who can access the collections. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserContentPermission" /integrations: get: operationId: listIntegrations summary: List all public integrations tags: - integrations parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/integrationSearchQuery" - $ref: "#/components/parameters/integrationSearchCategory" - $ref: "#/components/parameters/integrationSearchBlockDomain" - $ref: "#/components/parameters/integrationSearchBlocks" - $ref: "#/components/parameters/integrationSearchContentSources" - $ref: "#/components/parameters/integrationSearchOwner" - $ref: "#/components/parameters/integrationSearchScope" - $ref: "#/components/parameters/integrationSearchTarget" responses: "200": description: Paginated list of integrations content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/Integration" "/integrations/{integrationName}": get: operationId: getIntegrationByName summary: Get an integration by its name tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" responses: "200": description: Integration content: application/json: schema: $ref: "#/components/schemas/Integration" "404": description: No matching integration found for given name $ref: "#/components/responses/NotFoundError" post: operationId: publishIntegration summary: Publish an integration tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Integration" "404": description: Organization could not be found for the given hostname $ref: "#/components/responses/NotFoundError" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PublishIntegration" delete: operationId: unpublishIntegration summary: Unpublish an integration tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" responses: "204": description: Integration did not exist "205": description: Integration has been deleted "/integrations/{integrationName}/installations": get: operationId: listIntegrationInstallations summary: List all integration installations tags: - integrations security: - integration: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: externalId in: query description: External Id to filter by schema: type: string 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/IntegrationInstallation" post: operationId: installIntegration summary: Install an integration tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/OrganizationTarget" responses: "201": headers: Location: description: URL for the installed integration schema: type: string description: Integration installed successfully content: application/json: schema: $ref: "#/components/schemas/IntegrationInstallation" "404": $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/events": get: operationId: listIntegrationEvents summary: List all integration events tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Paginated list of integration events content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/IntegrationEvent" "/integrations/{integrationName}/events/{eventId}": get: operationId: getIntegrationEvent summary: Get an integration event by its ID tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/integrationEventId" responses: "200": description: Integration event content: application/json: schema: type: object required: - event properties: event: $ref: "#/components/schemas/IntegrationEvent" trace: $ref: "#/components/schemas/IntegrationEventTrace" "404": $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/spaces": get: operationId: listIntegrationSpaceInstallations summary: List all integration space installations tags: - integrations security: - integration: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: externalId in: query description: External Id to filter by schema: type: string - name: extended in: query description: If true, returns the space object in each items. If false, returns the space ID in each items. schema: type: boolean default: false 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/IntegrationSpaceInstallation" "/integrations/{integrationName}/sites": get: operationId: listIntegrationSiteInstallations summary: List all integration site installations tags: - integrations security: - integration: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: externalId in: query description: External ID to filter by schema: type: string - name: extended in: query description: If true, returns the site object in each items. If false, returns the site ID in each items. schema: type: boolean default: false 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/IntegrationSiteInstallation" "/integrations/{integrationName}/dev": put: operationId: setIntegrationDevelopmentMode summary: Enable integration dev mode tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" requestBody: required: true content: application/json: schema: type: object properties: tunnelUrl: type: string description: URL of the tunnel to dispatch integration events to minLength: 1 maxLength: 256 all: type: boolean default: false description: | If set to true, all requests will be forwarded to the tunnel, not just from the owning organization. required: - tunnelUrl responses: "204": description: Updated development mode successfully "404": $ref: "#/components/responses/NotFoundError" delete: operationId: disableIntegrationDevelopmentMode summary: Disable integration dev mode tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" responses: "205": description: Disabled development mode successfully "/integrations/{integrationName}/render": get: operationId: renderIntegrationUIWithGet summary: Render an integration UI with GET method tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - name: request in: query required: true description: LZ-string compressed JSON request schema: type: string responses: "200": description: ContentKit element to render content: application/json: schema: $ref: "#/components/schemas/ContentKitRenderOutput" headers: Cache-Control: schema: type: string post: operationId: renderIntegrationUIWithPost summary: Render an integration UI with POST method tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" responses: "200": description: ContentKit element to render content: application/json: schema: $ref: "#/components/schemas/ContentKitRenderOutput" headers: Cache-Control: schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RenderIntegrationUI" "/integrations/{integrationName}/tasks": post: operationId: queueIntegrationTask summary: Queue an integration task tags: - integrations security: - integration: [] parameters: - $ref: "#/components/parameters/integrationName" requestBody: required: true content: application/json: schema: type: object properties: task: type: object description: Payload for the integration task schedule: type: number description: Number of seconds to wait before executing the task, defaults to 0 minimum: 0 maximum: 86400 required: - task responses: "204": description: Integration task created successfully "404": $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/installations/{installationId}": get: operationId: getIntegrationInstallationById summary: Get an integration installation by its ID tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" responses: "200": description: Integration installation content: application/json: schema: $ref: "#/components/schemas/IntegrationInstallation" "404": $ref: "#/components/responses/NotFoundError" patch: operationId: updateIntegrationInstallation summary: Update an integration installation tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" responses: "200": description: The installation has been updated. content: application/json: schema: $ref: "#/components/schemas/IntegrationInstallation" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateIntegrationInstallation" delete: operationId: uninstallIntegration summary: Uninstall an integration tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" responses: "204": description: Integration installation did not exist "205": description: Integration uninstalled successfully "/integrations/{integrationName}/installations/{installationId}/tokens": post: operationId: createIntegrationInstallationToken summary: Create an integration installation API token description: | Creates a temporary API token of an integration's installation that has access to the installation and it's scopes. You must be authenticated as the integration to obtain this token. tags: - integrations security: - integration: [] parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" responses: "200": description: The API token for the installation content: application/json: schema: $ref: "#/components/schemas/APITemporaryToken" "404": description: Installation could not be found $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/installations/{installationId}/spaces": get: operationId: listIntegrationInstallationSpaces summary: List all space integration installations tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: extended in: query description: If true, returns the space object in each items. If false, returns the space ID in each items. schema: type: boolean default: false 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/IntegrationSpaceInstallation" post: operationId: installIntegrationOnSpace summary: Install an integration on a space parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - name: extended in: query description: If true, returns the space object in each items. If false, returns the space ID in each items. schema: type: boolean default: false requestBody: required: true content: application/json: schema: type: object required: - space properties: space: type: string description: ID of the space to install the integration on responses: "201": headers: Location: description: URL for the installed integration schema: type: string description: Integration installed successfully on space content: application/json: schema: $ref: "#/components/schemas/IntegrationSpaceInstallation" "404": $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}": get: operationId: getIntegrationSpaceInstallation summary: Get an integration space installation tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/spaceId" - name: extended in: query description: If true, returns the space object in each items. If false, returns the space ID in each items. schema: type: boolean default: false responses: "200": description: Integration space installation content: application/json: schema: $ref: "#/components/schemas/IntegrationSpaceInstallation" "404": $ref: "#/components/responses/NotFoundError" patch: operationId: updateIntegrationSpaceInstallation summary: Update an integration space installation tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/spaceId" - name: extended in: query description: If true, returns the space object in each items. If false, returns the space ID in each items. schema: type: boolean default: false responses: "200": description: The space installation has been updated. content: application/json: schema: $ref: "#/components/schemas/IntegrationSpaceInstallation" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateIntegrationSpaceInstallation" delete: operationId: uninstallIntegrationFromSpace summary: Uninstall an integration from a space tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/spaceId" responses: "204": description: The space installation did not exist. "205": description: The space installation has been deleted. "/integrations/{integrationName}/installations/{installationId}/sites": get: operationId: listIntegrationInstallationSites summary: List all site integration installations tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: extended in: query description: If true, returns the site object in each items. If false, returns the site ID in each items. schema: type: boolean default: false 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/IntegrationSiteInstallation" post: operationId: installIntegrationOnSite summary: Install an integration on a site tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - name: extended in: query description: If true, returns the site object in each items. If false, returns the site ID in each items. schema: type: boolean default: false requestBody: required: true content: application/json: schema: type: object required: - siteId properties: siteId: type: string description: ID of the site to install the integration on responses: "201": headers: Location: description: URL for the installed integration on the site schema: type: string description: Integration installed successfully on site content: application/json: schema: $ref: "#/components/schemas/IntegrationSiteInstallation" "404": $ref: "#/components/responses/NotFoundError" "/integrations/{integrationName}/installations/{installationId}/sites/{siteId}": get: operationId: getIntegrationSiteInstallation summary: Get an integration site installation tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/siteId" - name: extended in: query description: If true, returns the site object in each items. If false, returns the site ID in each items. schema: type: boolean default: false responses: "200": description: Integration site installation content: application/json: schema: $ref: "#/components/schemas/IntegrationSiteInstallation" "404": $ref: "#/components/responses/NotFoundError" patch: operationId: updateIntegrationSiteInstallation summary: Update an integration site installation tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/siteId" - name: extended in: query description: If true, returns the site object in each items. If false, returns the site ID in each items. schema: type: boolean default: false responses: "200": description: The site installation has been updated. content: application/json: schema: $ref: "#/components/schemas/IntegrationSiteInstallation" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateIntegrationSiteInstallation" delete: operationId: uninstallIntegrationFromSite summary: Uninstall an integration from a site tags: - integrations parameters: - $ref: "#/components/parameters/integrationName" - $ref: "#/components/parameters/installationId" - $ref: "#/components/parameters/siteId" responses: "204": description: The site installation did not exist. "205": description: The site installation has been deleted. /orgs: get: operationId: listOrganizationsForAuthenticatedUser summary: Get the list of organizations for the currently authenticated user tags: - organizations - critical security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object properties: items: type: array items: $ref: "#/components/schemas/Organization" required: - items "/orgs/{organizationId}": get: operationId: getOrganizationById summary: Get an organization by its ID tags: - organizations - critical parameters: - $ref: "#/components/parameters/organizationId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Organization" "404": description: No matching organization found for given id $ref: "#/components/responses/NotFoundError" patch: operationId: updateOrganizationById summary: Update an organization tags: - organizations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/OrganizationTitle" emailDomains: $ref: "#/components/schemas/OrganizationEmailDomains" hostname: $ref: "#/components/schemas/OrganizationHostname" defaultRole: $ref: "#/components/schemas/MemberRoleOrGuest" defaultContent: oneOf: - $ref: "#/components/schemas/OrganizationDefaultContent" - type: "null" logo: oneOf: - $ref: "#/components/schemas/URL" - type: "null" sso: type: boolean ai: type: boolean inviteLinks: type: boolean mergeRules: $ref: "#/components/schemas/MergeRulesStandaloneConfiguration" responses: "200": description: The organization has been updated content: application/json: schema: $ref: "#/components/schemas/Organization" "400": description: Invalid default content space or collection provided $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/members": get: operationId: listMembersInOrganizationById summary: List all organization members tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/listOrder" - name: role description: The Role to filter the member list by in: query schema: oneOf: - $ref: "#/components/schemas/MemberRole" - type: string enum: - guest - name: search in: query description: A query to filter the member list (displayName and email) schema: type: string - name: sort in: query description: The property to sort the results by. When sorting by lastSeenAt, only active members will be listed. schema: type: string default: joinedAt enum: - joinedAt - lastSeenAt 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/OrganizationMember" "/orgs/{organizationId}/members/{userId}": get: operationId: getMemberInOrganizationById summary: Get an organization member by its ID tags: - organization-members - critical security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OrganizationMember" patch: operationId: updateMemberInOrganizationById summary: Update an organization member tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" responses: "200": description: The member has been updated content: application/json: schema: $ref: "#/components/schemas/OrganizationMember" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" delete: operationId: removeMemberFromOrganizationById summary: Delete an organization member tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" responses: "204": description: Member did not exist in the organization. "205": description: The member was deleted from the organization. "/orgs/{organizationId}/ping": post: operationId: updateOrganizationMemberLastSeenAt summary: Update an organization member last seen at tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" responses: "200": description: Organization member has been updated. Optionally returns a JWT token to attach to the user. content: application/json: schema: type: object properties: gitbookVisitorClaims: description: A JTW token containing the claims to attach to this user. type: string "/orgs/{organizationId}/members/{userId}/sso": post: operationId: setUserAsSSOMemberForOrganization summary: Set a user as an SSO member of an organization tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" responses: "200": description: The user has been added as an SSO member of the organization. content: application/json: schema: $ref: "#/components/schemas/OrganizationMember" "/orgs/{organizationId}/members/{userId}/spaces": get: operationId: listSpacesForOrganizationMember summary: List an organization member space permissions tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/listOrder" responses: "200": description: Listing of spaces that can be accessed by the user in the organization. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/MemberContentPermission" "/orgs/{organizationId}/members/{userId}/teams": get: operationId: listTeamsForOrganizationMember summary: List all organization member teams tags: - organization-members security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/userId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - in: query name: title description: If provided, only teams whose name contains the given parameter will be returned. Case insensitive. schema: type: string responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: type: object required: - team - member properties: team: $ref: "#/components/schemas/OrganizationTeam" member: $ref: "#/components/schemas/TeamMember" "/orgs/{organizationId}/teams": get: operationId: listTeamsInOrganizationById summary: List all teams tags: - teams security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - in: query name: owner description: The unique identifier of a member of the organization. Only teams they can manage will be returned. schema: type: string - in: query name: title description: If provided, only teams whose name contains the given parameter will be returned. Case insensitive. schema: type: string 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/OrganizationTeam" put: operationId: createOrganizationTeam summary: Create a team tags: - teams security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" responses: "201": description: Team has been created content: application/json: schema: $ref: "#/components/schemas/OrganizationTeam" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/OrganizationTeamTitle" members: description: A list of organization member identifiers type: array items: type: string required: - title "/orgs/{organizationId}/teams/{teamId}": get: operationId: getTeamInOrganizationById summary: Get a team tags: - teams security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/teamId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OrganizationTeam" patch: operationId: updateTeamInOrganizationById summary: Update a team tags: - teams security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/teamId" responses: "200": description: The team has been updated content: application/json: schema: $ref: "#/components/schemas/OrganizationTeam" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/OrganizationTeamTitle" required: - title delete: operationId: removeTeamFromOrganizationById summary: Delete a team tags: - teams security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/teamId" responses: "204": description: The team did not exist in the organization. "205": description: The team was deleted from the organization. "/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: [] 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 summary: List all team members description: | Lists members, and their roles, for the specified organization team. tags: - team-members security: - user: [] 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: [] 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: [] 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 "/orgs/{organizationId}/invites": post: operationId: inviteUsersToOrganization summary: Invite users in an organization tags: - organization-invites security: - user: [] 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: [] 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: [] 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: [] 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: [] 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: [] 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" delete: operationId: deleteOrganizationInviteById summary: Deletes an organization invite. tags: - organizations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/inviteId" responses: "204": description: Organization invite did not exist "205": description: The organization invite has been deleted "/orgs/{organizationId}/join": post: operationId: joinOrganization summary: Join an organization description: | Join an organization if the user's verified email domain matches one of the organization's allowed email domains. This endpoint allows existing users to join organizations they're eligible for based on their email domain. tags: - organizations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" responses: "204": description: Successfully joined the organization "400": description: User's email domain is not valid $ref: "#/components/responses/BadRequestError" "404": description: Organization not found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/search": get: operationId: searchOrganizationContent summary: Search content in an organization tags: - organizations security: - user: [] parameters: - name: query in: query required: true schema: type: string maxLength: 512 - $ref: "#/components/parameters/organizationId" - $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/SearchSpaceResult" "/orgs/{organizationId}/change-requests": get: operationId: listChangeRequestsForOrganization summary: List all change requests in an organization tags: - change-requests security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/organizationId" - name: status in: query required: false schema: type: array description: If defined, only change requests matching the statuses will be returned. items: $ref: "#/components/schemas/ChangeRequestStatus" default: - open - name: creator in: query required: false schema: type: string description: If defined, only change requests created by this user will be returned. - name: contributor in: query required: false schema: type: string description: If defined, only change requests with contributions from this user will be returned. - name: requestedReviewer in: query required: false schema: type: string description: If defined, only change requests with a requested reviewer for this user will be returned. - name: topic in: query required: false schema: type: string description: If defined, only change requests linked to this site topic will be returned. - name: orderBy in: query required: false schema: $ref: "#/components/schemas/ChangeRequestOrderBy" responses: "200": description: List of the organization's change requests content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequest" "/orgs/{organizationId}/spaces": get: operationId: listSpacesInOrganizationById summary: List all spaces tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $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/Space" post: operationId: createSpace summary: Create a space tags: - spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateSpace" responses: "201": description: Space created headers: Location: description: API URL for the newly created space schema: type: string content: application/json: schema: $ref: "#/components/schemas/Space" "/orgs/{organizationId}/collections": get: operationId: listCollectionsInOrganizationById summary: List all collections tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: nested in: query description: If true, all nested collections will be listed schema: type: boolean default: true 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/Collection" post: operationId: createCollection summary: Create a collection tags: - collections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: content: application/json: schema: type: object properties: title: type: string maxLength: 50 parent: type: string description: ID of a parent collection responses: "201": description: Collection created headers: Location: description: API URL for the newly created collection schema: type: string content: application/json: schema: $ref: "#/components/schemas/Collection" "/orgs/{organizationId}/integrations": get: operationId: listOrganizationIntegrations summary: List all public integrations along with private ones trusted by the specific org. tags: - integrations parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/integrationSearchQuery" - $ref: "#/components/parameters/integrationSearchCategory" - $ref: "#/components/parameters/integrationSearchBlockDomain" - $ref: "#/components/parameters/integrationSearchBlocks" - $ref: "#/components/parameters/integrationSearchContentSources" - $ref: "#/components/parameters/integrationSearchOwner" - $ref: "#/components/parameters/integrationSearchScope" - $ref: "#/components/parameters/integrationSearchTarget" responses: "200": description: List of integrations. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/Integration" "/orgs/{organizationId}/integrations/{integrationName}/installation_status": get: operationId: getOrganizationIntegrationStatus summary: Get the status of an integration tags: - integrations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/integrationName" responses: "200": description: Integration installation status content: application/json: schema: properties: status: $ref: "#/components/schemas/IntegrationInstallationStatus" required: - status "404": $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/installations": get: operationId: listOrganizationInstallations summary: List all integration installations tags: - integrations parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/integrationSearchQuery" responses: "200": description: List of integrations with the associated installations. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: type: object properties: installation: $ref: "#/components/schemas/IntegrationInstallation" integration: $ref: "#/components/schemas/Integration" required: - integration - installation "/orgs/{organizationId}/integrations/installations-status": get: operationId: listOrganizationIntegrationsStatus summary: List all integration statuses tags: - integrations - critical parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: target in: query description: Filter installations by their target (organization, space, or site). When not provided, defaults to organization-level installations for backwards compatibility schema: type: string default: organization enum: - organization - space - site responses: "200": description: List of installed integrations and their statuses content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/InstalledIntegration" "/orgs/{organizationId}/saml": get: operationId: listSAMLProvidersInOrganizationById summary: List all SAML providers description: | Lists SAML providers configured for the specified organization. tags: - sso security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $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/OrganizationSAMLProvider" post: operationId: createOrganizationSAMLProvider summary: Create a new SAML provider tags: - sso security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: label: $ref: "#/components/schemas/SAMLProviderLabel" entityID: $ref: "#/components/schemas/SAMLProviderEntityID" certificate: $ref: "#/components/schemas/SAMLProviderCertificate" ssoURL: $ref: "#/components/schemas/URL" defaultTeam: type: string defaultRole: $ref: "#/components/schemas/MemberRoleOrGuest" required: - label responses: "201": description: SAML Provider created headers: Location: description: API URL for the newly created SAML Provider schema: type: string content: application/json: schema: $ref: "#/components/schemas/OrganizationSAMLProvider" "/orgs/{organizationId}/saml/{samlProviderId}": get: operationId: getOrganizationSAMLProviderById summary: Get a SAML provider by its ID tags: - sso security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/samlProviderId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OrganizationSAMLProvider" "404": description: No matching provider found $ref: "#/components/responses/NotFoundError" patch: operationId: updateOrganizationSAMLProvider summary: Update a SAML provider tags: - sso security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/samlProviderId" requestBody: required: true content: application/json: schema: type: object properties: label: $ref: "#/components/schemas/SAMLProviderLabel" entityID: $ref: "#/components/schemas/SAMLProviderEntityID" certificate: $ref: "#/components/schemas/SAMLProviderCertificate" ssoURL: $ref: "#/components/schemas/URL" defaultTeam: type: string defaultRole: $ref: "#/components/schemas/MemberRoleOrGuest" responses: "200": description: SAML provider has been updated content: application/json: schema: $ref: "#/components/schemas/OrganizationSAMLProvider" delete: operationId: deleteOrganizationSAMLProvider summary: Delete a SAML provider tags: - sso security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/samlProviderId" responses: "204": description: SAML provider did not exist "205": description: SAML provider has been deleted "/orgs/{organizationId}/sso": get: operationId: listSSOProviderLoginsInOrganization summary: List all SSO provider login infos tags: - sso parameters: - $ref: "#/components/parameters/organizationId" responses: "200": description: OK content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/OrganizationSSOProviderLogin" "/orgs/{organizationId}/ask": post: operationId: askInOrganization summary: Ask a question in an organization description: Ask a question to an AI across spaces that is accessible by the currently authenticated target. tags: - organization-ask security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/documentFormat" - name: details in: query description: Return query details in the result schema: type: boolean requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SearchAIQuery" responses: "200": description: OK content: application/json: schema: type: object properties: answer: $ref: "#/components/schemas/SearchAIAnswer" "/orgs/{organizationId}/ask/questions": get: operationId: getRecommendedQuestionsInOrganization summary: List recommended questions to ask in an organization tags: - organization-ask parameters: - $ref: "#/components/parameters/organizationId" security: - user: [] responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SearchAIRecommendedQuestions" "/orgs/{organizationId}/ask/questions/stream": get: operationId: streamRecommendedQuestionsInOrganization summary: List recommended questions to ask in an organization (streamed) tags: - organization-ask parameters: - $ref: "#/components/parameters/organizationId" security: - user: [] responses: "200": description: OK content: text/event-stream: schema: $ref: "#/components/schemas/SearchAIRecommendedQuestionStream" "/orgs/{organizationId}/ask/stream": get: operationId: streamAskInOrganization summary: Ask a question in an organization (streamed) description: Ask a question to an AI across spaces that is accessible by the currently authenticated target and stream the answer as a Server-Sent Events URL. tags: - organization-ask security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - name: query in: query required: true schema: type: string - $ref: "#/components/parameters/documentFormat" - name: details in: query description: Return query details in the result schema: type: boolean responses: "200": description: OK content: text/event-stream: schema: $ref: "#/components/schemas/SearchAIAnswerStream" "/orgs/{organizationId}/openapi": get: operationId: listOpenAPISpecs summary: List all OpenAPI spec tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $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/OpenAPISpec" post: operationId: createOpenAPISpec summary: Create an OpenAPI spec tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: slug: $ref: "#/components/schemas/OpenAPISpecSlug" source: $ref: "#/components/schemas/OpenAPISpecSource" required: - source - slug responses: "201": description: OpenAPI specification has been created content: application/json: schema: $ref: "#/components/schemas/OpenAPISpec" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/openapi/{specSlug}": get: operationId: getOpenAPISpecBySlug summary: Get an OpenAPI spec by its slug tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OpenAPISpec" "404": description: No matching OpenAPI specification found $ref: "#/components/responses/NotFoundError" put: operationId: createOrUpdateOpenAPISpecBySlug summary: Create or update an OpenAPI spec tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/OpenAPISpecSource" required: - source responses: "200": description: OpenAPI specification has been updated content: application/json: schema: $ref: "#/components/schemas/OpenAPISpec" "201": description: OpenAPI specification has been created content: application/json: schema: $ref: "#/components/schemas/OpenAPISpec" "400": $ref: "#/components/responses/BadRequestError" patch: operationId: updateOpenAPISpecBySlug summary: Update OpenAPI spec visibility tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" requestBody: required: true content: application/json: schema: type: object properties: visibility: $ref: "#/components/schemas/OpenAPISpecVisibility" required: - visibility responses: "200": description: OpenAPI specification visibility has been updated content: application/json: schema: $ref: "#/components/schemas/OpenAPISpec" "400": $ref: "#/components/responses/BadRequestError" "404": description: No matching OpenAPI specification found $ref: "#/components/responses/NotFoundError" delete: operationId: deleteOpenAPISpecBySlug summary: Delete an OpenAPI spec tags: - openapi security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" responses: "204": description: Specification did not exist "205": description: OpenAPI specification has been deleted "/orgs/{organizationId}/openapi/{specSlug}/versions": get: operationId: listOpenAPISpecVersions summary: List all OpenAPI spec versions tags: - openapi-versions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" - $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/OpenAPISpecVersion" "404": description: No matching OpenAPI specification found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/openapi/{specSlug}/versions/latest": get: operationId: getLatestOpenAPISpecVersion summary: Get the latest OpenAPI spec version tags: - openapi-versions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OpenAPISpecVersion" "404": description: No matching OpenAPI specification version found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content": get: operationId: getLatestOpenAPISpecVersionContent summary: Get the latest OpenAPI spec version content tags: - openapi-versions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OpenAPISpecContent" "404": description: No matching OpenAPI specification version found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}": get: operationId: getOpenAPISpecVersionById summary: Get an OpenAPI spec version by its ID tags: - openapi-versions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" - $ref: "#/components/parameters/openapiSpecVersionId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OpenAPISpecVersion" "404": description: No matching OpenAPI specification version found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content": get: operationId: getOpenAPISpecVersionContentById summary: Get an OpenAPI spec version content by its ID tags: - openapi-versions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/openapiSpecSlug" - $ref: "#/components/parameters/openapiSpecVersionId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OpenAPISpecContent" "404": description: No matching OpenAPI specification version found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/agent-instructions": get: operationId: getOrganizationAgentInstructions summary: Get Docs agent instructions for an organization tags: - organizations - agents security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/OrganizationAgentInstructions" put: operationId: updateOrganizationAgentInstructions summary: Update Docs agent instructions for an organization tags: - organizations - agents security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object required: - instructions properties: instructions: $ref: "#/components/schemas/JSONDocument" description: Document describing the Docs agent instructions. responses: "200": description: Updated instructions content: application/json: schema: $ref: "#/components/schemas/OrganizationAgentInstructions" "/orgs/{organizationId}/translations": get: operationId: listTranslations summary: List all the translations tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $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/Translation" post: operationId: createTranslation summary: Create a translation tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/TranslationSource" language: $ref: "#/components/schemas/TranslationLanguage" instructions: $ref: "#/components/schemas/JSONDocument" required: - language - source responses: "201": description: Translation has been created content: application/json: schema: $ref: "#/components/schemas/Translation" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/translations/{translationId}": get: operationId: getTranslation summary: Get a translation by its ID tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/translationId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Translation" "404": description: No matching translation found $ref: "#/components/responses/NotFoundError" put: operationId: updateTranslation summary: Update a translation tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/translationId" requestBody: required: true content: application/json: schema: type: object required: - instructions properties: instructions: $ref: "#/components/schemas/JSONDocument" responses: "200": description: Translation has been updated content: application/json: schema: $ref: "#/components/schemas/Translation" "400": $ref: "#/components/responses/BadRequestError" delete: operationId: deleteTranslation summary: Delete a translation tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/translationId" responses: "204": description: Translation did not exist "205": description: Translation has been deleted "/orgs/{organizationId}/translations/{translationId}/run": post: operationId: runTranslation summary: Run a translation again tags: - translations security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/translationId" responses: "204": description: Translation run triggered "404": description: No matching translation found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/translations-glossary": get: operationId: listGlossaryEntries summary: List glossary entries tags: - glossary security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: orderBy in: query description: Sort results by language key schema: $ref: "#/components/schemas/TranslationLanguage" 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/GlossaryEntry" put: operationId: updateGlossaryEntries summary: Update glossary entries tags: - glossary security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: operations: type: array items: $ref: "#/components/schemas/GlossaryBatchOperation" required: - operations responses: "204": description: Glossary entries updated "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/translations-glossary/{glossaryEntryId}": get: operationId: getGlossaryEntry summary: Get a glossary entry by its ID tags: - glossary security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/glossaryEntryId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/GlossaryEntry" "404": $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/storage/upload": post: operationId: generateStorageUploadURL summary: Create a signed URL to upload a file description: Generate a pre-signed URL that can be used to upload a file to storage tags: - storage security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object required: - file - kind properties: file: $ref: "#/components/schemas/StorageFileMetadata" kind: $ref: "#/components/schemas/StorageUploadKind" responses: "201": description: Successfully generated signed URL for file upload content: application/json: schema: $ref: "#/components/schemas/StorageUploadURL" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/fonts": get: operationId: listCustomFonts summary: List all custom fonts tags: - custom-fonts security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" 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/CustomizationFontDefinition" "404": $ref: "#/components/responses/NotFoundError" put: operationId: createCustomFont summary: Create a custom font tags: - custom-fonts security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object description: Defines a custom font and associated font faces with storage references. properties: fontFamily: $ref: "#/components/schemas/FontFamily" fontFaces: type: array description: | Array of font faces specifying weights and their corresponding storage keys. At least one font face with weight 400 (regular) must be provided. items: type: object properties: weight: $ref: "#/components/schemas/FontWeight" storageKey: $ref: "#/components/schemas/StorageFileKey" required: - weight - storageKey minItems: 1 required: - fontFamily - fontFaces responses: "201": description: Custom font created successfully. content: application/json: schema: $ref: "#/components/schemas/CustomizationFontDefinition" "404": $ref: "#/components/responses/NotFoundError" "412": description: Invalid request data, such as missing required font weights. $ref: "#/components/responses/PreconditionFailedError" "/orgs/{organizationId}/fonts/{fontId}": get: operationId: getCustomFont summary: Get a custom font by its ID tags: - custom-fonts security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/fontId" responses: "200": description: Custom font. content: application/json: schema: $ref: "#/components/schemas/CustomizationFontDefinition" "404": description: Organization or font not found. $ref: "#/components/responses/NotFoundError" post: operationId: updateCustomFont summary: Update a custom font tags: - custom-fonts security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/fontId" requestBody: required: true content: application/json: schema: type: object description: Defines a custom font and associated font faces with storage references. properties: fontFamily: $ref: "#/components/schemas/FontFamily" fontFaces: type: array description: | Array of font faces specifying weights and their corresponding storage keys. Passing null as the storage key will remove that weight. items: type: object properties: weight: $ref: "#/components/schemas/FontWeight" storageKey: oneOf: - $ref: "#/components/schemas/StorageFileKey" - type: "null" required: - weight - storageKey responses: "201": description: Custom font created successfully. content: application/json: schema: $ref: "#/components/schemas/CustomizationFontDefinition" "404": $ref: "#/components/responses/NotFoundError" "412": description: Invalid request data, such as missing required font weights. $ref: "#/components/responses/PreconditionFailedError" delete: operationId: deleteCustomFont summary: Delete a custom font tags: - custom-fonts security: - user-internal: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/fontId" responses: "204": description: Organization or font not found. "205": description: Custom font deleted successfully. "/org/{organizationId}/imports": post: operationId: startImportRun summary: Import content into a space from a website tags: - imports security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/ContentImportSource" target: $ref: "#/components/schemas/ContentImportTarget" enhance: description: Enhance the imported content with AI default: true type: boolean required: - source - target responses: "201": description: Import run created successfully. content: application/json: schema: $ref: "#/components/schemas/ContentImportRun" "400": $ref: "#/components/responses/BadRequestError" "404": $ref: "#/components/responses/NotFoundError" "/org/{organizationId}/imports/{importRunId}/cancel": post: operationId: cancelImportRun summary: Cancel an import run tags: - imports security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/importRunId" responses: "201": description: Import run canceled successfully. content: application/json: schema: $ref: "#/components/schemas/ContentImportRun" "400": $ref: "#/components/responses/BadRequestError" "404": $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites": get: operationId: listSites summary: List all sites tags: - sites - critical security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: space in: query description: Identifier of the space to filter the sites by required: false schema: type: string - name: title in: query description: Filter sites by their title required: false schema: type: string - name: published in: query description: Filter sites by their published status required: false schema: type: boolean - name: type in: query description: Filter by site type required: false schema: type: array items: $ref: "#/components/schemas/SiteType" 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/Site" post: operationId: createSite summary: Create a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" requestBody: content: application/json: schema: type: object properties: type: description: The type of the site, defaults to Basic $ref: "#/components/schemas/SiteType" title: $ref: "#/components/schemas/SiteTitle" visibility: $ref: "#/components/schemas/SiteVisibility" spaces: type: array description: ID of spaces to be added to the site items: type: string responses: "201": description: Site created headers: Location: description: API URL for the newly created site schema: type: string content: application/json: schema: $ref: "#/components/schemas/Site" "/orgs/{organizationId}/sites/{siteId}": get: operationId: getSiteById summary: Get a site by its ID tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Site" "404": description: No matching site found $ref: "#/components/responses/NotFoundError" patch: operationId: updateSiteById summary: Update a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/SiteTitle" visibility: $ref: "#/components/schemas/SiteVisibility" basename: $ref: "#/components/schemas/SiteBasename" adaptiveContent: $ref: "#/components/schemas/SiteAdaptiveContent" permissionsModel: $ref: "#/components/schemas/SitePermissionsModel" defaultLevel: $ref: "#/components/schemas/DefaultLevel" defaultSiteSpace: type: string description: ID of the site-space to be used as the default at the root level. If site has sections, this will mark the default site space in the site's default section. defaultSiteSection: type: string description: ID of the site-section to be used as the default. proxy: description: | Configure a proxy URL for a site. For example, you can use it to host the site on a subdirectory of your domain like `https://company.com/docs`. Use `null` to remove the proxy. oneOf: - $ref: "#/components/schemas/SiteProxyOrigin" - type: "null" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Site" delete: operationId: deleteSiteById summary: Delete a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "204": description: Site did not exist "205": description: Site has been deleted "/orgs/{organizationId}/sites/{siteId}/adaptive-schema": get: operationId: getSiteAdaptiveSchema summary: Get the JSON schema describing the attributes expected for an Adaptive content site visitor. tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: The JSON schema that defines the attributes expected from a visitor of the Adaptive content site. content: application/json: schema: $ref: "#/components/schemas/SiteAdaptiveSchema" "404": description: No visitor attributes schema found for the site. $ref: "#/components/responses/NotFoundError" default: $ref: "#/components/responses/UnexpectedError" put: operationId: updateSiteAdaptiveSchema summary: Update the JSON schema of the attributes expected for an Adaptive content site visitor. tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: jsonSchema: description: The JSON schema to set on the site. $ref: "#/components/schemas/SiteAdaptiveJSONSchema" required: - jsonSchema responses: "200": description: The site adaptive schema has been updated. content: application/json: schema: $ref: "#/components/schemas/SiteAdaptiveSchema" "400": $ref: "#/components/responses/BadRequestError" default: $ref: "#/components/responses/UnexpectedError" "/orgs/{organizationId}/sites/{siteId}/adaptive-schema/template-conditions": get: operationId: listSiteAdaptiveTemplateConditions summary: List templates of conditions generated based on the site visitor schema that can be used in adaptive content expressions. tags: - sites parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: List of template conditions generated based on the site visitor schema. content: application/json: schema: type: object properties: items: type: array items: $ref: "#/components/schemas/SiteAdaptiveTemplateCondition" required: - items "/orgs/{organizationId}/sites/{siteId}/published": get: operationId: getPublishedContentSite summary: Get a published site description: Get the complete profile of a site in an organization to provide the published experience. It includes site, customization, structure, integration scripts etc. tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteShareKey" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/PublishedContentSite" "404": description: No matching site found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/publish": post: operationId: publishSite summary: Publish a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: Site published successfully content: application/json: schema: oneOf: - $ref: "#/components/schemas/Site" - type: object description: User needs to checkout in order to publish the site. properties: type: type: string enum: - checkout sessionId: type: string description: Stripe payment session ID required: - type - sessionId "/orgs/{organizationId}/sites/{siteId}/unpublish": post: operationId: unpublishSite summary: Unpublish a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: Site unpublished successfully content: application/json: schema: $ref: "#/components/schemas/Site" "/orgs/{organizationId}/sites/{siteId}/share-links": get: operationId: listSiteShareLinks summary: List all share links tags: - site-share-links security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: search in: query description: Search share links by name or key schema: type: string 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/ShareLink" post: operationId: createSiteShareLink summary: Create a share link tags: - site-share-links security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/ShareLinkName" required: - name responses: "201": description: The share link has been created headers: Location: description: API URL for the newly created share link schema: type: string content: application/json: schema: $ref: "#/components/schemas/ShareLink" "/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}": patch: operationId: updateSiteShareLinkById summary: Update a share link tags: - site-share-links security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/shareLinkId" requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: active: type: boolean name: $ref: "#/components/schemas/ShareLinkName" responses: "200": description: The site share link has been updated content: application/json: schema: $ref: "#/components/schemas/ShareLink" delete: operationId: deleteSiteShareLinkById summary: Deletes a share link tags: - site-share-links security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/shareLinkId" responses: "204": description: Site share link did not exist "205": description: Site share link has been deleted "/orgs/{organizationId}/sites/{siteId}/structure": get: operationId: getSiteStructure summary: Get a site structure description: Get the complete structure of a site that includes all its site-sections and site-spaces. tags: - site-structure security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteShareKey" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteStructure" "404": description: No matching site found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/structure/sort": patch: operationId: sortSiteStructure summary: Move a site space, site section or site section group to a new position in the site structure. tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: content: application/json: schema: type: object properties: item: description: pointer to the item (site space, site section or site section group) being moved. $ref: "#/components/schemas/SiteStructureItemPointer" position: description: The position to move the item to. When not provided the item is moved to the end of the site structure. $ref: "#/components/schemas/SiteStructureItemMovePosition" required: - item - position responses: "200": description: Item successfully moved content: application/json: schema: $ref: "#/components/schemas/SiteStructureItem" "400": description: Invalid move position provided $ref: "#/components/responses/BadRequestError" "404": description: No matching item found $ref: "#/components/responses/NotFoundError" default: $ref: "#/components/responses/UnexpectedError" "/orgs/{organizationId}/sites/{siteId}/publishing/auth": get: operationId: getSitePublishingAuthById summary: Get a site auth config tags: - site-publishing-auth security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SitePublishingAuth" "400": $ref: "#/components/responses/BadRequestError" patch: operationId: updateSitePublishingAuthById summary: Update a site auth config tags: - site-publishing-auth security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SitePublishingAuthUpdate" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SitePublishingAuth" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate": post: operationId: regenerateSitePublishingAuthById summary: Regenerate a site auth description: Regenerate the publishing authentication settings for a site. This will re-generate the private key. tags: - site-publishing-auth security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SitePublishingAuth" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/publishing/preview": get: operationId: getSitePublishingPreviewById summary: Get a site preview URL description: Generate a URL to preview the published content of a site. The URL will be valid for 1 hour. tags: - site-preview security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: siteSpace in: query description: ID of the site-space to preview. If not provided, the default site-space will be used. schema: type: string - name: claims in: query description: Rison encoded string of attributes/assertions about the visitor for which we want to preview the site. schema: type: string - name: draft in: query description: Whether to include draft content in the preview. Defaults to true schema: type: boolean default: true - name: target in: query description: Target URL of the preview. If not provided, the default site preview URL will be used. schema: type: string responses: "200": description: OK content: application/json: schema: type: object properties: url: $ref: "#/components/schemas/URL" required: - url "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/customization": get: operationId: getSiteCustomizationById summary: Get a site customization settings tags: - site-customization security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteCustomizationUnmasked" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteCustomizationSettings" "400": $ref: "#/components/responses/BadRequestError" put: operationId: updateSiteCustomizationById summary: Update a site customization settings tags: - site-customization security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SiteCustomizationSettingsInput" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteCustomizationSettings" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/integration-scripts": get: operationId: listSiteIntegrationScripts summary: List the scripts to embed in published content for a site. tags: - integrations - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/SiteIntegrationScript" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/integrations": get: operationId: listSiteIntegrations summary: List integrations enabled in a site. tags: - integrations - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/integrationSearchQuery" responses: "200": description: Listing of integrations enabled in the site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/Integration" "/orgs/{organizationId}/sites/{siteId}/site-spaces": post: operationId: addSpaceToSite summary: Add a space to a site tags: - site-spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: spaceId: type: string description: ID of the space sectionId: type: string description: ID of the section to add the space to. If not provided, the space will be added to the default section or at the root level if the site has no sections. draft: type: boolean default: false description: Whether the site space should be created as draft. Defaults to false. required: - spaceId responses: "201": description: Space added to the site headers: Location: description: API URL for the newly created site-space relationship schema: type: string content: application/json: schema: $ref: "#/components/schemas/SiteSpace" get: operationId: listSiteSpaces summary: List all the site spaces tags: - site-spaces - critical security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteShareKey" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: default in: query description: If true, only the default site space will be returned. If false, only the non-default site spaces are returned. If undefined, all site spaces are returned. schema: type: boolean 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/SiteSpace" "/orgs/{organizationId}/sites/{siteId}/section-groups": get: operationId: listSiteSectionGroups summary: List all site section groups tags: - site-section-groups security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $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/SiteSectionGroup" post: operationId: addSectionGroupToSite summary: Add a section group to a site tags: - site-section-groups security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/SiteSectionGroupTitle" icon: oneOf: - $ref: "#/components/schemas/Icon" - type: "null" sections: type: array items: type: string description: IDs of the sections to be added to the section group parent: type: string description: ID of the parent section group to nest this group under. If not provided, the section group will be added at the root of the site. draft: type: boolean description: Whether the section group should be created in draft mode. required: - title responses: "201": description: Section group added to the site headers: Location: description: API URL for the newly created site-section-group relationship schema: type: string content: application/json: schema: $ref: "#/components/schemas/SiteSectionGroup" "/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}": patch: operationId: updateSiteSectionGroupById summary: Update a site section group tags: - site-section-groups security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionGroupId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/SiteSectionGroupTitle" localizedTitle: $ref: "#/components/schemas/LocalizedString128" icon: oneOf: - $ref: "#/components/schemas/Icon" - type: "null" draft: type: boolean description: Whether the site section group is draft and not live. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteSectionGroup" delete: operationId: deleteSiteSectionGroupById summary: Delete a site section group tags: - site-section-groups security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionGroupId" responses: "204": description: Site section group did not exist "205": description: Site section group has been deleted "/orgs/{organizationId}/sites/{siteId}/sections": post: operationId: addSectionToSite summary: Add a section to a site tags: - site-sections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: spaceId: type: string description: ID of the space to be added to the section as a site space variant title: oneOf: - $ref: "#/components/schemas/SiteSectionTitle" - type: "null" icon: oneOf: - $ref: "#/components/schemas/Icon" - type: "null" draft: type: boolean description: Whether the section should be created in draft mode. siteSectionGroupId: type: string description: ID of the section group to create the section in required: - spaceId responses: "201": description: Section added to the site headers: Location: description: API URL for the newly created site-section relationship schema: type: string content: application/json: schema: $ref: "#/components/schemas/SiteSection" get: operationId: listSiteSections summary: List all site sections tags: - site-sections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteShareKey" - $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/SiteSection" "/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}": patch: operationId: updateSiteSectionById summary: Update a site section tags: - site-sections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionId" requestBody: required: true content: application/json: schema: type: object properties: title: $ref: "#/components/schemas/SiteSectionTitle" localizedTitle: $ref: "#/components/schemas/LocalizedString128" path: $ref: "#/components/schemas/SiteSectionPath" defaultSiteSpace: type: string description: ID of the site-space to be used as the default in this section. condition: description: Conditional expression used to evaluate whether the site section should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed. oneOf: - $ref: "#/components/schemas/Expression" - type: "null" icon: oneOf: - $ref: "#/components/schemas/Icon" - type: "null" draft: type: boolean description: Whether the site section is draft and not live. description: oneOf: - $ref: "#/components/schemas/SiteSectionDescription" - type: "null" localizedDescription: $ref: "#/components/schemas/LocalizedString256" siteSectionGroupId: description: ID of the section group to move the section into. Set to null to move the section to the root of the site. oneOf: - type: string - type: "null" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteSection" delete: operationId: deleteSiteSectionById summary: Delete a site section tags: - site-sections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionId" responses: "204": description: Site section did not exist "205": description: Site section has been deleted "/orgs/{organizationId}/sites/{siteId}/search": post: operationId: searchSiteContent summary: Search in a site tags: - sites security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" requestBody: required: true content: application/json: schema: allOf: - type: object required: - query properties: query: type: string maxLength: 512 - oneOf: - type: object required: - scope properties: scope: description: Define the scope of the search. $ref: "#/components/schemas/SiteSearchScope" - type: object properties: mode: description: Search only in the site spaces provided. Deprecated, use scope instead. deprecated: true type: string enum: - specific siteSpaceIds: type: array minLength: 1 items: type: string required: - siteSpaceIds - type: object properties: mode: description: Search in the current site space and all section's defaults. Deprecated, use scope instead. deprecated: true type: string enum: - current siteSpaceId: type: string required: - mode - siteSpaceId - type: object properties: mode: description: Search in all site-spaces. Deprecated, use scope instead. deprecated: true type: string enum: - all required: - mode responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: oneOf: - $ref: "#/components/schemas/SearchSpaceResult" - $ref: "#/components/schemas/SearchRecordResult" discriminator: propertyName: type "/orgs/{organizationId}/sites/{siteId}/ask": post: operationId: streamAskInSite summary: Ask a question in a site description: The response is streamed. tags: - site-ask security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/documentFormat" requestBody: required: true content: application/json: schema: type: object required: - question - scope properties: question: type: string maxLength: 512 context: type: object description: | You may optionally provide additional information about the context of the question. This doesn't affect the scope of the search, but GitBook may use this information to provide a better answer. Generally speaking, you should provide as much context as possible. properties: siteSpaceId: type: string scope: $ref: "#/components/schemas/SiteSearchScope" responses: "200": description: OK content: text/event-stream: schema: $ref: "#/components/schemas/SearchAIAnswerStream" "/orgs/{organizationId}/sites/{siteId}/ask/questions": get: operationId: streamRecommendedQuestionsInSite summary: List recommended questions to ask in a site description: The response is streamed. tags: - site-ask security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: siteSpaceId in: query description: The ID of the site space to filter the recommended questions for. schema: type: string - name: spaceId in: query description: The ID of the space to filter the recommended questions for. deprecated: true schema: type: string responses: "200": description: OK content: text/event-stream: schema: $ref: "#/components/schemas/SearchAIRecommendedQuestionStream" "/orgs/{organizationId}/sites/{siteId}/context-records": get: operationId: listSiteContextRecords summary: List all context records tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: type in: query description: Filter context records by type. schema: $ref: "#/components/schemas/ContextRecordType" - name: connector in: query description: Filter context records by connector type. schema: $ref: "#/components/schemas/ContextConnector" - name: connection in: query description: Filter context records by connection id. schema: type: string - name: topic in: query description: Filter context records by associated site topic ID. schema: type: string 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/ContextRecord" put: operationId: upsertSiteContextRecords summary: Create or update context records tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: array items: $ref: "#/components/schemas/ContextRecordInput" responses: "204": description: The context records have been created or updated "/orgs/{organizationId}/sites/{siteId}/context-records/{siteContextRecordId}": get: operationId: getSiteContextRecordById summary: Get a context record tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteContextRecordId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContextRecord" "/orgs/{organizationId}/sites/{siteId}/scans": get: operationId: listSiteScans summary: List all site scans tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: topic in: query description: Filter scans by associated site topic ID. schema: type: string - name: status in: query description: Filter scans by status. schema: $ref: "#/components/schemas/SiteScanStatus" 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/SiteScan" post: operationId: createSiteScan summary: Enqueue a new site scan tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object required: - topic properties: topic: type: string description: The site topic ID to scan. responses: "202": description: Site scan has been enqueued content: application/json: schema: $ref: "#/components/schemas/SiteScan" "/orgs/{organizationId}/sites/{siteId}/scans/{siteScanId}": get: operationId: getSiteScanById summary: Get a site scan by ID tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteScanId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteScan" "/orgs/{organizationId}/sites/{siteId}/findings": get: operationId: listSiteFindings summary: List all site context findings tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: topic in: query description: Filter findings by associated site topic ID. schema: type: string - name: status in: query description: Filter findings by status. schema: $ref: "#/components/schemas/SiteFindingStatus" - name: type in: query description: Filter findings by type. schema: $ref: "#/components/schemas/SiteFindingType" - name: severity in: query description: Filter findings by estimated severity. schema: $ref: "#/components/schemas/SiteFindingSeverity" 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/SiteFinding" "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}": get: operationId: getSiteFindingById summary: Get a site finding by ID tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteFinding" patch: operationId: updateSiteFindingById summary: Update a site finding tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - open - canceled required: - status responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteFinding" "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests": get: operationId: listChangeRequestsForSiteFinding summary: List change requests linked to a site finding tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "200": description: List of change requests linked to the site finding content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ChangeRequest" post: operationId: triggerChangeRequestsForSiteFinding summary: Process a site finding into change requests tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "202": description: Site finding processing has been started "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/pages": get: operationId: listPagesForSiteFinding summary: List pages linked to a site finding tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "200": description: List of pages linked to the site finding content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/SiteFindingPage" "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/questions": get: operationId: listQuestionsForSiteFinding summary: List questions linked to a site finding tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "200": description: List of questions linked to the site finding content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/SiteQuestion" "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/records": get: operationId: listRecordsForSiteFinding summary: List records linked to a site finding tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteFindingId" responses: "200": description: List of records linked to the site finding content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/ContextRecord" "/orgs/{organizationId}/sites/{siteId}/context-connections": get: operationId: listSiteContextConnections summary: List all context connections tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $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/ContextConnection" post: operationId: createSiteContextConnection summary: Create a context connection tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/ContextConnectorSetup" - type: object properties: usageSettings: $ref: "#/components/schemas/ContextUsageSettings" responses: "201": description: Created connection content: application/json: schema: $ref: "#/components/schemas/ContextConnection" "/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}": get: operationId: getSiteContextConnectionById summary: Get a context connection tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteContextConnectionId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContextConnection" patch: operationId: updateSiteContextConnectionById summary: Update a context connection tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteContextConnectionId" requestBody: required: true content: application/json: schema: anyOf: - $ref: "#/components/schemas/ContextConnectorSetup" - type: object properties: usageSettings: $ref: "#/components/schemas/ContextUsageSettings" label: $ref: "#/components/schemas/ContextConnectionLabel" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/ContextConnection" delete: operationId: deleteSiteContextConnectionById summary: Delete a context connection tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteContextConnectionId" responses: "204": description: Context connection did not exist "205": description: Context connection deleted "/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}/sync": post: operationId: syncSiteContextConnection summary: Trigger a sync for a context connection tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteContextConnectionId" responses: "204": description: Sync started "400": description: Connection was synced less than an hour ago or invalid connector $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/topics": get: operationId: listSiteTopics summary: List all topics tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: from in: query description: Filter stats to answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter stats to answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" responses: "200": description: OK content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/SiteTopic" "/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}": get: operationId: getSiteTopicById summary: Get a topic tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteTopicId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteTopic" patch: operationId: updateSiteTopicById summary: Update a topic tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteTopicId" requestBody: required: true content: application/json: schema: type: object properties: usageSettings: $ref: "#/components/schemas/SiteTopicUsageSettings" required: - usageSettings responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteTopic" "/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}/findings": delete: operationId: deleteSiteTopicFindings summary: Delete all findings for a topic tags: - site-context security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteTopicId" responses: "204": description: Topic had no findings or did not exist "205": description: Topic findings deleted "/orgs/{organizationId}/sites/{siteId}/questions": get: operationId: listSiteQuestions summary: List all questions in a site tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: from in: query description: Filter stats to answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter stats to answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: type in: query description: Filter questions by question type. schema: $ref: "#/components/schemas/SiteQuestionType" - name: relevance in: query description: Filter questions by question relevance. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" - name: answered in: query description: Filter questions by answer resolution. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerResolution" - name: topic in: query description: Filter questions by associated site topic IDs. schema: type: array items: type: string - $ref: "#/components/parameters/listOrder" - name: sort in: query description: Sort questions by latest ask activity, answered rate, or positive feedback rate. If omitted, ordering stays on canonical question creation date to preserve current behavior. schema: type: string enum: - askedAt - stats.answered - stats.feedback - stats.answers - $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/SiteQuestion" "/orgs/{organizationId}/sites/{siteId}/questions/{siteQuestionId}": get: operationId: getSiteQuestionById summary: Get a site question by ID tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteQuestionId" - name: from in: query description: Filter stats to answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter stats to answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: relevance in: query description: Filter stats by question relevance. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" - name: answered in: query description: Filter stats by answer resolution. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerResolution" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteQuestion" "/orgs/{organizationId}/sites/{siteId}/questions/{siteQuestionId}/sources": get: operationId: listSiteQuestionSources summary: List sources for a question tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteQuestionId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: from in: query description: Filter sources to answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter sources to answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: relevance in: query description: Filter answer sources by question relevance. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" - name: answered in: query description: Filter answer sources by answer resolution. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerResolution" 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/SiteQuestionAnswerSource" "/orgs/{organizationId}/sites/{siteId}/question-stats": get: operationId: getSiteQuestionStats summary: Get question stats for a site tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: from in: query description: Filter stats to answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter stats to answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: topic in: query description: Filter stats by associated site topic IDs. schema: type: array items: type: string - name: relevance in: query description: Filter stats by question relevance. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" - name: answered in: query description: Filter stats by answer resolution. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerResolution" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteQuestionStats" "/orgs/{organizationId}/sites/{siteId}/answers": get: operationId: listSiteQuestionAnswers summary: List all answers for a site tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - name: question in: query description: Filter answers to a specific site question ID. schema: type: string - name: from in: query description: Filter answers created at or after this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: to in: query description: Filter answers created at or before this timestamp. schema: $ref: "#/components/schemas/Timestamp" - name: language in: query description: Filter answers by ISO language code. schema: type: string - name: answered in: query description: Filter answers by answered resolution. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerResolution" - name: helpfulness in: query description: Filter answers by answered helpfulness. schema: $ref: "#/components/schemas/SiteQuestionAnswerHelpfulness" - name: relevance in: query description: Filter answers by question relevance. schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" - name: question.type in: query description: Filter answers by question type. schema: $ref: "#/components/schemas/SiteQuestionType" - name: topic in: query description: Filter answers by associated site topic ID. schema: type: string - name: thread in: query description: Filter answers by thread root answer ID. Includes the root answer itself. schema: type: string - $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/SiteQuestionAnswer" "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}": get: operationId: getSiteQuestionAnswerById summary: Get a site answer by ID tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteQuestionAnswerId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteQuestionAnswerWithResponse" "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}/thread": get: operationId: getSiteQuestionAnswerThreadById summary: Get a site answer thread by answer ID tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteQuestionAnswerId" responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/SiteQuestionAnswerWithResponse" "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}/sources": get: operationId: listSiteQuestionAnswerSources summary: List the sources for an answer tags: - site-questions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteQuestionAnswerId" - $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/SiteQuestionAnswerSource" "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}": patch: operationId: updateSiteSpaceById summary: Update a site space tags: - site-spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" requestBody: required: true content: application/json: schema: type: object properties: path: $ref: "#/components/schemas/SiteSpacePath" condition: description: Conditional expression used to evaluate whether the site space should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed. oneOf: - $ref: "#/components/schemas/Expression" - type: "null" spaceId: type: string description: The content that this site space points to. If not set, the space will remain unchanged. hidden: type: boolean description: Whether the site space is hidden. If true, the site space will not be shown in the site's navigation. If not set, the hidden state will remain unchanged. If set to false, the site space will be shown in site navigation. draft: type: boolean description: Whether the site space should be kept in draft mode. Setting it to false makes the site space live. responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteSpace" delete: operationId: deleteSiteSpaceById summary: Delete a site space tags: - site-spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" responses: "204": description: Site space did not exist "205": description: Site space has been deleted "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization": get: operationId: getSiteSpaceCustomizationById summary: Get a site space customization settings tags: - site-customization security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" - $ref: "#/components/parameters/siteCustomizationUnmasked" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteCustomizationSettings" "400": $ref: "#/components/responses/BadRequestError" patch: operationId: overrideSiteSpaceCustomizationById summary: Override a site space customization settings tags: - site-customization security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" requestBody: required: true content: application/json: schema: description: The settings that overrides the site customization settings. type: object properties: title: description: Title to use for the published site variant. If not defined, the title will not be changed. If set to null, the title will be unset and will fallback to the content title. oneOf: - $ref: "#/components/schemas/SiteTitle" - type: "null" localizedTitle: description: Localized titles for the site variant, keyed by locale. If not defined, the localized title will not be changed. If set to null, all localized titles will be removed. oneOf: - $ref: "#/components/schemas/LocalizedString128" - type: "null" styling: type: object properties: theme: description: The site theme. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationTheme" - type: "null" primaryColor: description: The primary color used for links and UI text. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" infoColor: description: Used for informational messages and neutral alerts. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" successColor: description: Used for showing positive actions or achievements. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" warningColor: description: Used for showing important information or non-critical warnings. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" dangerColor: description: Used for destructive actions or raising attention to critical information. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" tint: description: The tint will color the site’s UI beyond links and buttons, such as header, sidebar and background. By default, the tint colour is the same as your Primary colour, but you can set a custom one too. oneOf: - $ref: "#/components/schemas/CustomizationTint" - type: "null" corners: description: The style of the corners to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationCorners" - type: "null" depth: description: The depth of elements on the site. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationDepth" - type: "null" links: description: The style for links to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationLinksStyle" - type: "null" icons: description: The icons style to use for the content. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationIconsStyle" - type: "null" sidebar: description: Various styles for the sidebar. Each can be Set to null to reset the override. type: object properties: background: oneOf: - $ref: "#/components/schemas/CustomizationSidebarBackgroundStyle" - type: "null" list: oneOf: - $ref: "#/components/schemas/CustomizationSidebarListStyle" - type: "null" search: description: Styling for the search button at the top of the site. oneOf: - $ref: "#/components/schemas/CustomizationSearchStyle" - type: "null" background: description: The style of background to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationBackground" - type: "null" codeTheme: description: The code theme to use. Set to null to reset the override. type: object properties: default: oneOf: - $ref: "#/components/schemas/CustomizationThemedCodeTheme" - type: "null" openapi: oneOf: - $ref: "#/components/schemas/CustomizationThemedCodeTheme" - type: "null" internationalization: type: object deprecated: true properties: locale: description: The locale to use for the non-custom elements of the UI. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationLocale" - type: "null" required: - locale favicon: description: The favicon to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationFavicon" - type: "null" announcement: $ref: "#/components/schemas/CustomizationAnnouncement" header: type: object properties: preset: description: The theme preset to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationHeaderPreset" - type: "null" logo: description: The header logo to use. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedURL" - type: "null" primaryLink: description: The destination to open when visitors click the site title/logo in the header. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/ContentRef" - type: "null" backgroundColor: description: The background color used in the header. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" linkColor: description: The color used by the links in the header. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedColor" - type: "null" links: type: - array - "null" description: The links that are displayed in the header. Set to null to reset the override. items: $ref: "#/components/schemas/CustomizationHeaderItem" footer: type: object properties: logo: description: The logo displayed in the footer. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationThemedURL" - type: "null" groups: type: - array - "null" description: The links groups that are displayed in the footer. Set to null to reset the override. items: $ref: "#/components/schemas/CustomizationFooterGroup" copyright: type: - string - "null" description: The copyright text that is displayed in the footer. Set to null to reset the override. maxLength: 300 themes: type: object properties: default: description: The theme mode default value. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/CustomizationDefaultThemeMode" - type: "null" toggeable: description: Should the reader be able to switch between dark and light mode. Set to null to reset the override. type: - boolean - "null" pdf: type: object properties: enabled: type: - boolean - "null" description: If true, PDF export is enabled for the published site. Set to null to reset the override. required: - enabled feedback: type: object properties: enabled: type: - boolean - "null" description: If true, feedback gathering is enabled. Set to null to reset the override. required: - enabled git: type: object properties: showEditLink: type: - boolean - "null" description: Whether the published site should show a link to edit the content on the git provider set up in the Git Sync. Set to null to reset the override. required: - showEditLink externalLinks: type: object properties: target: description: How external links should open. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/SiteExternalLinksTarget" - type: "null" required: - target pagination: type: object properties: enabled: type: - boolean - "null" description: Whether the pagination navigation should be displayed on pages. Set to null to reset the override. required: - enabled trademark: type: object properties: enabled: type: - boolean - "null" description: Whether the GitBook trademark ("Powered by GitBook") should be visible. Set to null to reset the override. required: - enabled privacyPolicy: type: object properties: url: description: The custom link to the privacy policy. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/URL" - type: "null" socialPreview: type: object properties: url: description: The URL for the social preview image. Set to null to reset the override. oneOf: - $ref: "#/components/schemas/URL" - type: "null" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteCustomizationSettings" "400": $ref: "#/components/responses/BadRequestError" delete: operationId: deleteSiteSpaceCustomizationById summary: Delete a site space customization settings tags: - site-customization security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" responses: "204": description: Customization settings did not exist "205": description: Site space customization removed "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/move": post: operationId: moveSiteSectionGroup deprecated: true summary: Move a site section group to a new position. (Deprecated) use sortSiteStructure instead. tags: - site-section-groups security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionGroupId" requestBody: content: application/json: schema: type: object properties: position: description: The position where to move the site section group. When not provided the site section group is moved at the end of the site. $ref: "#/components/schemas/SiteSectionGroupMovePosition" responses: "200": description: Site section group moved content: application/json: schema: $ref: "#/components/schemas/SiteSectionGroup" "400": description: Invalid move site section group position provided $ref: "#/components/responses/BadRequestError" "404": description: No matching site section group found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move": post: operationId: moveSiteSection deprecated: true summary: Move a site section to a new position. (Deprecated) use sortSiteStructure instead. tags: - site-sections security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSectionId" requestBody: content: application/json: schema: type: object properties: position: description: The position where to move the site section. When not provided the site section is moved at the end of the site. $ref: "#/components/schemas/SiteSectionMovePosition" responses: "200": description: Site section moved content: application/json: schema: $ref: "#/components/schemas/SiteSection" "400": description: Invalid move site section position provided $ref: "#/components/responses/BadRequestError" "404": description: No matching Site section found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move": post: operationId: moveSiteSpace deprecated: true summary: Move a site space to a new position. (Deprecated) use sortSiteStructure instead. tags: - site-spaces security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteSpaceId" requestBody: content: application/json: schema: type: object properties: position: description: The position where to move the site space. When not provided the site space is moved at the end of the site. $ref: "#/components/schemas/SiteSpaceMovePosition" responses: "200": description: Site space moved content: application/json: schema: $ref: "#/components/schemas/SiteSpace" "400": description: Invalid move site space position provided $ref: "#/components/responses/BadRequestError" "404": description: No matching Site space found $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/permissions": post: operationId: inviteToSite summary: Invite a user or a team to a site tags: - site-permissions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "204": description: OK "404": description: No team or user with the provided Id $ref: "#/components/responses/NotFoundError" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InviteSiteUsersAndTeams" "/orgs/{organizationId}/sites/{siteId}/permissions/aggregate": get: operationId: listPermissionsAggregateInSite summary: List all sites users permissions tags: - site-users security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of users who can access the site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserSitePermission" "/orgs/{organizationId}/sites/{siteId}/permissions/users": get: operationId: listUserPermissionsInSite summary: List site user permissions tags: - site-users security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of users who have been added to a site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/UserSitePermissionOverride" "404": description: No site was found with the given Id $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/permissions/users/{userId}": patch: operationId: updateUserPermissionInSite summary: Update site user permissions tags: - site-users security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/userId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRole" responses: "204": description: User permission was updated "404": description: No user found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeUserFromSite summary: Remove a site user tags: - site-users security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/userId" responses: "204": description: The user was not found in the site "205": description: The user has been removed from the site "/orgs/{organizationId}/sites/{siteId}/permissions/teams": get: operationId: listTeamPermissionsInSite summary: List an org team's permission in a site tags: - site-permissions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" responses: "200": description: Listing of teams who have been added to a site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/TeamSitePermissionOverride" "404": description: No site was found with the given Id $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/permissions/teams/{teamId}": patch: operationId: updateTeamPermissionInSite summary: Update an org team's permission in a site tags: - site-permissions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/teamId" requestBody: required: true content: application/json: schema: type: object properties: role: $ref: "#/components/schemas/MemberRole" responses: "204": description: Team permission was updated "404": description: No team found with the given ID $ref: "#/components/responses/NotFoundError" delete: operationId: removeTeamFromSite summary: Remove an org team from a site tags: - site-permissions security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/teamId" responses: "204": description: The team was not found in the site "205": description: The team has been removed from the site "/orgs/{organizationId}/sites/{siteId}/ai/response": post: operationId: streamAIResponseInSite summary: Generate an AI response in a site description: | Generate an AI response in a conversation. tags: - site-ai security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object required: - input properties: previousResponseId: type: string description: The ID of the previous response to continue from input: type: array description: The messages to send to the AI agent. items: $ref: "#/components/schemas/AIMessageInput" model: $ref: "#/components/schemas/AIModel" tools: type: array description: Custom tools to provide to the AI agent. items: $ref: "#/components/schemas/AIToolDefinition" toolCall: $ref: "#/components/schemas/AIToolCallResult" session: $ref: "#/components/schemas/SiteInsightsSession" channel: type: object description: The channel from which the question was asked, if applicable. required: - type properties: type: $ref: "#/components/schemas/SiteCoreChannelType" responses: "200": description: OK content: text/event-stream: schema: $ref: "#/components/schemas/AIStreamResponse" "/orgs/{organizationId}/sites/{siteId}/agent-settings": get: operationId: getSiteAgentSettingsById summary: Get site agent settings tags: - site-agent-settings security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteAgentSettings" "400": $ref: "#/components/responses/BadRequestError" put: operationId: updateSiteAgentSettingsById summary: Update site agent settings tags: - site-agent-settings security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SiteAgentSettingsInput" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteAgentSettings" "400": $ref: "#/components/responses/BadRequestError" "/orgs/{organizationId}/sites/{siteId}/insights/events": post: operationId: trackEventsInSiteById summary: Track site events tags: - site-insights parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "204": description: Events have been tracked. requestBody: required: true content: application/json: schema: type: object properties: events: type: array items: $ref: "#/components/schemas/SiteInsightsEvent" required: - events "/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate": post: operationId: aggregateSiteEvents summary: Query site events security: - user: [] tags: - site-insights parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SiteInsightsQueryEventsAggregation" responses: "200": description: Aggregated events in the site. content: application/json: schema: $ref: "#/components/schemas/SiteInsightsQueryEventsAggregationResult" "/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments": get: operationId: listSiteVisitorSegments summary: List a site visitor segments tags: - site-insights parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" responses: "200": description: List of visitor segments in the site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/SiteInsightsVisitorSegment" "/orgs/{organizationId}/sites/{siteId}/ads": post: operationId: updateSiteAdsById summary: Update a site ads settings tags: - site-ads security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: false content: application/json: schema: type: object properties: status: type: string enum: - in-review - disabled topic: $ref: "#/components/schemas/SiteAdsTopic" responses: "204": description: OK "/orgs/{organizationId}/sites/{siteId}/redirects": post: operationId: createSiteRedirect summary: Create a site redirect tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/SiteRedirectSourcePath" captureWildcard: type: boolean default: false description: Capture and append the wildcard-matched suffix to the destination URL. draft: type: boolean default: false description: Whether the redirect is draft and not live. destination: $ref: "#/components/schemas/SiteRedirectInputDestination" required: - source - destination responses: "201": description: The redirect was created successfully. content: application/json: schema: $ref: "#/components/schemas/SiteRedirect" put: operationId: bulkUpsertSiteRedirects summary: Create or update site redirects in bulk tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: redirects: type: array minItems: 1 maxItems: 500 items: oneOf: - type: object properties: source: $ref: "#/components/schemas/SiteRedirectSourcePath" intent: type: string enum: - publish description: | Publish a draft redirect to live and remove the draft redirect. required: - source - intent - type: object properties: source: $ref: "#/components/schemas/SiteRedirectSourcePath" intent: type: string enum: - live - draft default: live description: | Redirect operation intent. - live: upsert/delete a live redirect (draft=false) - draft: upsert/delete a draft redirect (draft=true) captureWildcard: type: boolean default: false description: Capture and append the wildcard-matched suffix to the destination URL. destination: description: If set to null, the redirect matching the source+intent target will be deleted. oneOf: - $ref: "#/components/schemas/SiteRedirectInputDestination" - type: "null" required: - source - destination required: - redirects responses: "200": description: List of results for each redirect processed. content: application/json: schema: type: object properties: results: type: array items: oneOf: - type: object properties: status: type: string enum: - created description: The redirect was created. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Whether the redirect is draft and not live. id: type: string description: The ID of the created redirect. required: - status - source - draft - id - type: object properties: status: type: string enum: - updated description: The redirect was updated. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Whether the redirect is draft and not live. id: type: string description: The ID of the updated redirect. required: - status - source - draft - id - type: object properties: status: type: string enum: - deleted description: The redirect was deleted. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Whether the deleted redirect was draft. required: - status - source - draft - type: object properties: status: type: string enum: - published description: The draft redirect was published to live and removed from draft. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Always false for published redirects. id: type: string description: The ID of the resulting live redirect. required: - status - source - draft - id - type: object properties: status: type: string enum: - error description: There was an error processing the redirect. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Whether the redirect is draft and not live. error: type: string description: The error message. required: - status - source - draft - error required: - results get: operationId: listSiteRedirects summary: List all site redirects tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - name: search in: query description: Search for a redirect by path schema: type: string - name: draft in: query description: Filter redirects by draft mode. schema: type: boolean default: false responses: "200": description: The list of redirects for the site. content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: $ref: "#/components/schemas/SiteRedirect" "/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}": patch: operationId: updateSiteRedirectById summary: Update a site redirect tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteRedirectId" requestBody: required: true content: application/json: schema: type: object properties: source: $ref: "#/components/schemas/SiteRedirectSourcePath" captureWildcard: type: boolean description: Capture and append the wildcard-matched suffix to the destination URL. draft: type: boolean description: When true, it can be used to promote a draft redirect to live. destination: $ref: "#/components/schemas/SiteRedirectDestination" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteRedirect" delete: operationId: deleteSiteRedirectById summary: Delete a site redirect tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteRedirectId" responses: "204": description: Site redirect did not exist "205": description: Site redirect deleted "/orgs/{organizationId}/sites/{siteId}/redirect": get: operationId: getSiteRedirectBySource summary: Get a site redirect by its source tags: - site-redirects security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteShareKey" - name: source in: query required: true description: The source path of the redirect. schema: $ref: "#/components/schemas/SiteRedirectSourcePath" responses: "200": description: The redirect was resolved successfully. content: application/json: schema: type: object properties: redirect: $ref: "#/components/schemas/SiteRedirect" target: type: string description: URL of the destination of the redirect. required: - redirect - target "404": $ref: "#/components/responses/NotFoundError" "/orgs/{organizationId}/sites/{siteId}/mcp-servers": get: operationId: listSiteMcpServers summary: List all MCP servers for a site tags: - site-mcp-servers security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $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/SiteMcpServer" post: operationId: createSiteMcpServer summary: Create a new MCP server tags: - site-mcp-servers security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/SiteMcpServerName" url: $ref: "#/components/schemas/URL" headers: $ref: "#/components/schemas/SiteMcpServerHeaders" condition: description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If set to null, the condition will be removed. oneOf: - $ref: "#/components/schemas/Expression" - type: "null" required: - name - url - headers responses: "201": description: MCP server created content: application/json: schema: $ref: "#/components/schemas/SiteMcpServer" "/orgs/{organizationId}/sites/{siteId}/mcp-servers/{siteMcpServerId}": get: operationId: getSiteMcpServerById summary: Get a site MCP server tags: - site-mcp-servers security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteMcpServerId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteMcpServer" patch: operationId: updateSiteMcpServerById summary: Update a site MCP server tags: - site-mcp-servers security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteMcpServerId" requestBody: required: true content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/SiteMcpServerName" url: type: string format: uri maxLength: 2048 headers: $ref: "#/components/schemas/SiteMcpServerHeaders" condition: description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed. oneOf: - $ref: "#/components/schemas/Expression" - type: "null" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteMcpServer" delete: operationId: deleteSiteMcpServerById summary: Delete a site MCP server tags: - site-mcp-servers security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteMcpServerId" responses: "204": description: MCP server did not exist "205": description: MCP server deleted "/orgs/{organizationId}/sites/{siteId}/channels": get: operationId: listSiteChannels summary: List all site channels for a site tags: - site-channels security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $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/SiteChannel" post: operationId: createSiteChannel summary: Create a site channel tags: - site-channels security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/SiteChannelSetup" - type: object properties: role: $ref: "#/components/schemas/SiteChannelRole" responses: "201": description: Site channel created content: application/json: schema: $ref: "#/components/schemas/SiteChannel" "/orgs/{organizationId}/sites/{siteId}/channels/{siteChannelId}": get: operationId: getSiteChannelById summary: Get a site channel tags: - site-channels security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteChannelId" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteChannel" patch: operationId: updateSiteChannelById summary: Update a site channel tags: - site-channels security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteChannelId" requestBody: required: true content: application/json: schema: anyOf: - $ref: "#/components/schemas/SiteChannelSetup" - type: object properties: role: $ref: "#/components/schemas/SiteChannelRole" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SiteChannel" delete: operationId: deleteSiteChannelById summary: Delete a site channel tags: - site-channels security: - user: [] parameters: - $ref: "#/components/parameters/organizationId" - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/siteChannelId" responses: "204": description: Site channel did not exist "205": description: Site channel deleted "/subdomains/{subdomain}": get: operationId: getSubdomain summary: Get a subdomain tags: - subdomains security: - user: [] parameters: - $ref: "#/components/parameters/subdomain" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Subdomain" "/custom-hostnames/{hostname}": get: operationId: getCustomHostname summary: Get a custom hostname tags: - custom-hostnames security: - user-internal-or-staff: [] parameters: - $ref: "#/components/parameters/hostname" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CustomHostname" patch: operationId: dnsRevalidateCustomHostname summary: Revalidate a custom hostname DNS description: Revalidate DNS records and status. tags: - custom-hostnames security: - user-internal: [] parameters: - $ref: "#/components/parameters/hostname" responses: "204": description: DNS validation has been retriggered "400": description: The current custom hostname is inactive and cannot be revalidated $ref: "#/components/responses/ConflictError" "409": description: The current custom hostname status does not allow DNS revalidation $ref: "#/components/responses/ConflictError" delete: operationId: removeCustomHostname summary: Remove a custom hostname description: The custom hostname will continue to point to the content or organization unless it is used for another one. tags: - custom-hostnames security: - user-internal: [] parameters: - $ref: "#/components/parameters/hostname" responses: "204": description: Custom hostname did not exist "205": description: Custom hostname has been removed "/email-domains/{emailDomain}/orgs": get: operationId: getOrganizationsForEmailDomain summary: Get all organizations by email domain tags: - organizations security: - user-internal: [] parameters: - $ref: "#/components/parameters/emailDomain" responses: "200": description: OK content: application/json: schema: type: object properties: organizations: type: array items: $ref: "#/components/schemas/Organization" required: - organizations /ads/sites: get: operationId: adsListSites summary: List all the sites with ads configured tags: - site-ads parameters: - $ref: "#/components/parameters/listPage" - $ref: "#/components/parameters/listLimit" - $ref: "#/components/parameters/xGitBookPartnerKey" - name: status in: query description: Filter sites by their ads review status required: false schema: type: string default: in-review enum: - in-review - live - rejected responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/List" - type: object required: - items properties: items: type: array items: allOf: - type: object required: - id - url - email - topic properties: id: type: string url: type: string email: type: string topic: $ref: "#/components/schemas/SiteAdsTopic" - oneOf: - type: object required: - status properties: status: type: string enum: - in-review - type: object required: - status - zoneId properties: status: type: string enum: - live zoneId: type: string description: The ad network zone ID - type: object required: - status properties: status: type: string enum: - rejected reason: type: string description: Reason for the rejection "/ads/sites/{siteId}": patch: operationId: adsUpdateSite summary: Update the Ads configuration for a site tags: - site-ads parameters: - $ref: "#/components/parameters/siteId" - $ref: "#/components/parameters/xGitBookPartnerKey" requestBody: required: true content: application/json: schema: oneOf: - type: object required: - status - zoneId - reportingId properties: status: type: string enum: - live zoneId: type: string description: ID of the zone reportingId: type: string description: ID to fetch reporting data - type: object required: - status properties: status: type: string enum: - rejected reason: type: string description: Reason for the rejection maxLength: 512 - type: object required: - status properties: status: type: string enum: - pending responses: "204": description: OK /urls/content: get: operationId: getContentByUrl summary: Resolve a URL to a content (space, collection, page) tags: - urls security: - user: [] parameters: - name: url in: query required: true description: URL to resolve schema: type: string responses: "200": description: OK content: application/json: schema: oneOf: - type: object description: URL resolved to a collection properties: collection: $ref: "#/components/schemas/Collection" required: - collection - type: object description: URL resolved to the content of a space properties: space: $ref: "#/components/schemas/Space" changeRequest: $ref: "#/components/schemas/ChangeRequest" page: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageGroup" required: - space /urls/embed: get: operationId: getEmbedByUrl summary: Resolve a URL to an embed tags: - urls parameters: - name: url in: query required: true description: URL to resolve schema: type: string responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Embed" /urls/published: get: operationId: getPublishedContentByUrl summary: Resolve a URL of a published content. deprecated: true tags: - urls parameters: - name: url in: query required: true description: URL to resolve schema: $ref: "#/components/schemas/URL" - name: visitorAuthToken in: query required: false description: JWT token generated for a authenticated access session schema: type: string - name: redirectOnError in: query required: false description: When true redirects the user to the authentication/fallback URL if the access token is invalid schema: type: boolean default: false responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/PublishedSiteContentLookup" "404": description: No content found for the URL. $ref: "#/components/responses/NotFoundError" post: operationId: resolvePublishedContentByUrl summary: Resolve a URL of a published content. tags: - urls requestBody: required: true content: application/json: schema: type: object properties: url: description: URL to resolve $ref: "#/components/schemas/URL" redirectOnError: type: boolean description: When true redirects the user to the authentication/fallback URL if the access token is invalid default: false visitor: $ref: "#/components/schemas/SiteVisitorPayload" required: - url responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/PublishedSiteContentLookup" "404": description: No content found for the URL. $ref: "#/components/responses/NotFoundError" components: securitySchemes: user: type: http scheme: bearer user-internal: type: http scheme: bearer user-staff: type: http scheme: bearer user-internal-or-staff: type: http scheme: bearer integration: type: http scheme: bearer integration-installation: type: http scheme: bearer parameters: listPage: name: page in: query description: Identifier of the page results to fetch. schema: type: string listLimit: name: limit in: query description: The number of results per page schema: type: number minimum: 0 maximum: 1000 tokenId: name: tokenId in: path required: true description: The id of the API token schema: type: string userId: name: userId in: path required: true description: The unique ID of the User schema: type: string spaceId: name: spaceId in: path required: true description: The unique id of the space schema: $ref: "#/components/schemas/EntityId" siteShareKey: name: shareKey in: query description: For sites published via share-links, the share key is useful to resolve published URLs. schema: type: string teamId: name: teamId in: path required: true description: The unique ID of the Team schema: $ref: "#/components/schemas/EntityId" revisionMetadata: name: metadata in: query description: If `false` is passed, "git" mutable metadata will not returned. Passing `false` can optimize performances of the lookup. schema: type: boolean default: true revisionComputed: name: computed in: query description: If `false` is passed, content will not be computed schema: type: boolean default: true fileId: name: fileId in: path required: true description: The unique id of the file schema: $ref: "#/components/schemas/EntityId" pageId: name: pageId in: path required: true description: The unique id of the page schema: $ref: "#/components/schemas/EntityId" documentFormat: name: format in: query description: Output format for the content. schema: type: string enum: - document - markdown documentEvaluated: name: evaluated in: query description: | Controls whether the document should be evaluated. - When set to `true`, the entire document will be evaluated. - When set to `deterministic-only`, only expressions that depend exclusively on deterministic inputs will be evaluated. schema: oneOf: - type: boolean - type: string enum: - deterministic-only default: false documentDereferenced: name: dereferenced in: query description: | Controls whether the document should be deferenced (eference to other content will be resolved and expanded). - When set to `true`, the entire document will be deferenced - When set to `reusable-contents`, only reusable contents will be deferenced. schema: oneOf: - type: boolean - type: string enum: - reusable-contents default: false pagePath: name: pagePath in: path required: true description: The path of the page in the revision. schema: type: string reusableContentId: name: reusableContentId in: path required: true description: The unique id of the reusable content schema: $ref: "#/components/schemas/EntityId" documentSchema: name: schema in: query description: Version of the schema used for the document. schema: type: string enum: - current - next changeRequestId: name: changeRequestId in: path required: true description: The unique ID of the change request or its number identifier in the space schema: $ref: "#/components/schemas/EntityId" reviewId: name: reviewId in: path required: true description: The unique ID of the change request review. schema: type: string listOrder: name: order in: query description: An order for the items in the list schema: type: string default: desc enum: - asc - desc status: name: status in: query description: When provided, only comments with the given status are returned. Defaults to "all". schema: type: string default: all enum: - all - open - resolved targetPage: name: targetPage in: query description: The target page of the comment schema: type: string authors: name: authors in: query description: User IDs to filter queried comments on required: false schema: type: array items: type: string commentId: name: commentId in: path required: true description: The unique id of the comment schema: $ref: "#/components/schemas/EntityId" commentReplyId: name: commentReplyId in: path required: true description: The unique id of the comment reply schema: $ref: "#/components/schemas/EntityId" revisionId: name: revisionId in: path required: true description: The unique id of the revision schema: $ref: "#/components/schemas/EntityId" integrationSearchQuery: name: search in: query description: | A search string to filter integrations by name schema: type: string collectionId: name: collectionId in: path required: true description: The unique id of the collection schema: $ref: "#/components/schemas/EntityId" integrationSearchCategory: name: category in: query description: Filter the integrations by category schema: $ref: "#/components/schemas/IntegrationCategory" integrationSearchBlockDomain: name: blockDomain in: query description: Filter the integrations by block's domains schema: type: string pattern: ^[a-zA-Z0-9-_.]+$ maxLength: 100 integrationSearchBlocks: name: blocks in: query description: If true, returns only integrations with blocks. If false, returns only integrations without blocks. schema: type: boolean integrationSearchContentSources: name: contentSources in: query description: If true, returns only integrations with contentSources. If false, returns only integrations without contentSources. schema: type: boolean integrationSearchOwner: name: owner in: query description: If defined, only list integrations owned by the given organization. schema: type: string integrationSearchScope: name: scope in: query description: Filter the integrations by scope schema: $ref: "#/components/schemas/IntegrationScope" integrationSearchTarget: name: target in: query description: Filter the integrations by target schema: $ref: "#/components/schemas/IntegrationTarget" integrationName: name: integrationName in: path required: true description: Name of the integration. schema: type: string pattern: ^[a-zA-Z0-9-_.]+$ maxLength: 100 integrationEventId: name: eventId in: path required: true description: ID of the integration event schema: type: string installationId: name: installationId in: path required: true description: Identifier of the installation schema: type: string siteId: name: siteId in: path required: true description: The unique id of the site schema: type: string organizationId: name: organizationId in: path required: true description: The unique id of the organization schema: $ref: "#/components/schemas/EntityId" inviteId: name: inviteId in: path required: true description: The unique id of the invite schema: $ref: "#/components/schemas/EntityId" successReturnURL: name: successReturnURL in: query description: The app screen URL to bring the user back to after a successful checkout. schema: type: string cancelReturnURL: name: cancelReturnURL in: query description: The app screen URL to bring the user back to after a canceled checkout. schema: type: string meterName: name: meterName in: path required: true description: Identifier of the billing meter schema: $ref: "#/components/schemas/BillingMeter" samlProviderId: name: samlProviderId in: path required: true description: The unique id of the SAML provider schema: type: string openapiSpecSlug: name: specSlug in: path required: true description: Slug of the OpenAPI specification schema: type: string openapiSpecVersionId: name: versionId in: path required: true description: The unique ID of the OpenAPI specification version schema: type: string translationId: name: translationId in: path required: true description: The unique id of the translation schema: type: string glossaryEntryId: name: glossaryEntryId in: path required: true description: The unique id of the glossary entry schema: type: string fontId: name: fontId in: path required: true description: The unique ID of a font schema: type: string importRunId: name: importRunId in: path required: true description: The unique id of the import run schema: type: string shareLinkId: name: shareLinkId in: path required: true description: The unique id of the share link schema: type: string siteCustomizationUnmasked: name: unmasked in: query description: (Deprecated) Use the getRawCustomizationSettingsById internal endpoint. deprecated: true schema: type: boolean default: false siteSectionGroupId: name: siteSectionGroupId in: path required: true description: The unique id of the site group schema: type: string siteSectionId: name: siteSectionId in: path required: true description: The unique id of the section within a site schema: type: string siteContextRecordId: name: siteContextRecordId in: path required: true description: The unique id of the context record schema: type: string siteScanId: name: siteScanId in: path required: true description: The unique id of the site scan schema: type: string siteFindingId: name: siteFindingId in: path required: true description: The unique id of the site finding schema: type: string siteContextConnectionId: name: siteContextConnectionId in: path required: true description: The unique id of the context connection schema: type: string siteTopicId: name: siteTopicId in: path required: true description: The unique id of the topic schema: type: string siteQuestionId: name: siteQuestionId in: path required: true description: The unique id of the site question schema: type: string siteQuestionAnswerId: name: siteQuestionAnswerId in: path required: true description: The unique id of the site question answer schema: type: string siteSpaceId: name: siteSpaceId in: path required: true description: The unique id of the site-space relationship schema: type: string siteRedirectId: name: siteRedirectId in: path required: true description: The unique id of the site redirect schema: type: string siteMcpServerId: name: siteMcpServerId in: path required: true description: The unique id of the MCP server schema: type: string siteChannelId: name: siteChannelId in: path required: true description: The unique id of the site channel schema: type: string subdomain: name: subdomain in: path required: true description: The subdomain, for example "my-company" in "my-company.gitbook.io" schema: type: string pattern: ^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$ minLength: 3 maxLength: 32 hostname: name: hostname in: path required: true description: The custom hostname, for example "docs.gitbook.com" schema: type: string emailDomain: name: emailDomain in: path required: true description: Email domain schema: type: string xGitBookPartnerKey: in: header name: X-GitBook-Partner-Key schema: type: string required: true translationLanguage: name: translationLanguage in: path required: true description: The language of the translation schema: $ref: "#/components/schemas/TranslationLanguage" pageFormat: $ref: "#/components/parameters/documentFormat" commentStatus: $ref: "#/components/parameters/status" commentTargetPage: $ref: "#/components/parameters/targetPage" schemas: ApiInformation: type: object properties: version: type: string description: Current release of GitBook build: type: string description: Date of the latest release in ISO format required: - version - build 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 APITemporaryToken: type: object properties: token: type: string description: Temporary access token to authenticate with the API required: - token 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 APITokenLabel: type: string maxLength: 50 Timestamp: type: string format: date-time UserAPIToken: type: object description: The API token details, excluding the token itself. properties: id: type: string description: The API token ID. label: $ref: "#/components/schemas/APITokenLabel" description: A descriptive label for the API token. createdAt: $ref: "#/components/schemas/Timestamp" description: The API token creation date. required: - id - label - createdAt UserAPITokenExtended: description: The API token details, including the token itself. allOf: - $ref: "#/components/schemas/UserAPIToken" - type: object properties: token: type: string description: The actual token value. required: - token URL: type: string format: uri maxLength: 2048 EntityId: type: string pattern: ^[a-zA-Z0-9_-]+$ description: A unique entity identifier SpaceTitle: type: string description: Title of the space maxLength: 50 Emoji: type: string maxLength: 50 format: emoji description: Unicode codepoint or character of the emoji example: 🎉 ContentVisibility: type: string description: | * `public`: Anyone can access the content, and the content is indexed by search engines. * `unlisted`: Anyone can access the content, and the content is not indexed by search engines * `share-link`: Anyone with a secret token in the url can access the content. * `visitor-auth`: Anyone authenticated through a JWT token can access the content. * `in-collection`: Anyone who can access the parent collection can access the content. Only available for spaces in a collection. * `private`: Authorized members can access the content. enum: - public - unlisted - share-link - visitor-auth - in-collection - private 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 MergeRulesConfigurationInherit: type: object description: The merge rules inherits from the organization configuration. properties: type: type: string enum: - inherit required: - type Expression: type: string description: Expression to evaluate minLength: 0 maxLength: 1024 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" required: - rule - expression 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 MergeRulesConfigurationNone: type: object description: The merge rules are disabled, change requests can be merged without review. properties: type: type: string enum: - none required: - type MergeRulesStandaloneConfiguration: oneOf: - $ref: "#/components/schemas/MergeRulesConfigurationRules" - $ref: "#/components/schemas/MergeRulesConfigurationNone" MergeRulesSpaceConfiguration: oneOf: - $ref: "#/components/schemas/MergeRulesConfigurationInherit" - $ref: "#/components/schemas/MergeRulesStandaloneConfiguration" TranslationLanguage: type: string enum: - en - fr - de - es - it - pt - pt-br - ru - ja - zh - 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 GitSyncProvider: type: string description: The provider of the Git Sync installation. enum: - github - gitlab - github-legacy GitSyncState: type: object properties: repoName: type: string description: Repository name. installationProvider: $ref: "#/components/schemas/GitSyncProvider" integration: type: string description: The integration name providing the Git Sync. url: type: string description: The URL to the repository tree, used when rendering public content. updatedAt: description: When the Git provider details were last updated $ref: "#/components/schemas/Timestamp" VisitorAuthCustomBackend: type: object title: Custom backend for authenticated access properties: backend: type: string description: Custom backend for authenticated access enum: - custom required: - backend VisitorAuthIntegrationBackend: type: object title: Integration backend for authenticated access properties: backend: type: string description: Integration as backend for authenticated access enum: - integration required: - backend 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 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 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 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" 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" 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 SpacePointer: type: object properties: type: type: string enum: - space space: type: string description: Unique identifier for the space required: - type - space CollectionPointer: type: object properties: type: type: string enum: - collection collection: type: string description: Unique identifier for the collection required: - type - collection ContentPosition: type: object description: Position at which to insert an item properties: before: oneOf: - $ref: "#/components/schemas/SpacePointer" - $ref: "#/components/schemas/CollectionPointer" after: oneOf: - $ref: "#/components/schemas/SpacePointer" - $ref: "#/components/schemas/CollectionPointer" IntegrationBlockMarkdown: oneOf: - type: object description: Format the custom block as a codeblock properties: codeblock: description: Code block syntax to use to identify the block. type: string body: description: Key of the property to use as body of the codeblock. type: string required: - codeblock - body IntegrationBlock: type: object properties: id: type: string description: Unique ID in the integration for the block. It also represents the UI component used. title: type: string description: Short descriptive title for the block. minLength: 2 maxLength: 40 description: type: string description: Long descriptive text for the block. minLength: 0 maxLength: 150 icon: type: string description: URL of the icon to represent this block. urlUnfurl: type: array description: URLs patterns to convert as this block. items: type: string markdown: $ref: "#/components/schemas/IntegrationBlockMarkdown" required: - id - title Embed: allOf: - type: object properties: title: type: string site: type: string icon: type: string required: - title - site - oneOf: - type: object title: Link properties: type: type: string enum: - link required: - type - type: object title: HTML properties: type: type: string enum: - rich html: type: string required: - type - html - type: object title: Integration properties: type: type: string enum: - integration integration: description: The identifier of the integration performing the rendering type: string block: $ref: "#/components/schemas/IntegrationBlock" required: - type - integration - block SearchResultScore: type: number minimum: 0 description: Relevance score for a search result. Higher is better and the score is unbounded. SearchSectionResult: type: object description: Search result representing a section in a page. properties: id: type: string title: type: string path: type: string score: $ref: "#/components/schemas/SearchResultScore" body: type: string urls: type: object description: URLs associated with the object properties: app: type: string description: URL of the section in the application format: uri required: - app required: - id - title - path - score - body - urls SearchPageResult: type: object description: Search result representing a page in a space. properties: id: type: string title: type: string path: type: string score: $ref: "#/components/schemas/SearchResultScore" sections: type: array items: $ref: "#/components/schemas/SearchSectionResult" ancestors: type: array description: Data about the ancestors of the current page, from top-level to direct parent. items: type: object properties: title: type: string required: - title urls: type: object description: URLs associated with the object properties: app: type: string description: URL of the page in the application format: uri required: - app required: - id - title - path - score - ancestors - urls UpdateSpaceGitInfo: type: object description: Update metadata about the Git provider on the space properties: provider: type: string description: The git provider enum: - github - gitlab url: type: string description: The repository's tree URL ImportGitRepository: type: object properties: url: type: string description: URL of the Git repository to import. It can contain basic auth credentials. ref: type: string description: Git ref to import in the format "refs/heads/main" repoCacheID: type: string description: Unique identifier to use to cache the Git repository across multiple operations. deprecated: true repoTreeURL: type: string description: URL to use as a prefix for external file references. repoCommitURL: type: string description: URL to use as a prefix for the commit URL. repoProjectDirectory: type: string description: Path to a root directory for the project in the repository. timestamp: description: | The timestamp of the event that triggered this import. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository. $ref: "#/components/schemas/Timestamp" force: type: boolean standalone: type: boolean description: If true, the import will generate a revision without updating the space primary content. gitInfo: description: Optional metadata to store on the space about the Git provider $ref: "#/components/schemas/UpdateSpaceGitInfo" required: - url - ref ExportToGitRepository: type: object properties: url: type: string description: URL of the Git repository to export to. It can contain basic auth credentials. ref: type: string description: Git ref to push the commit to in the format "refs/heads/main" commitMessage: type: string description: Message for the commit generated by the export repoCacheID: type: string description: Unique identifier to use to cache the Git repository across multiple operations. deprecated: true repoTreeURL: type: string description: URL to use as a prefix for external file references. repoCommitURL: type: string description: URL to use as a prefix for the commit URL. repoProjectDirectory: type: string description: Path to a root directory for the project in the repository. timestamp: description: | The timestamp of the event that triggered this export. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository. $ref: "#/components/schemas/Timestamp" force: type: boolean gitInfo: description: Optional metadata to store on the space about the Git provider $ref: "#/components/schemas/UpdateSpaceGitInfo" required: - url - ref - commitMessage InviteUsersAndTeams: type: object properties: role: description: Role to set. $ref: "#/components/schemas/MemberRoleOrGuest" anyOf: - type: object properties: teams: type: array minItems: 1 items: type: string description: The ID of the team to be invited required: - teams - type: object properties: users: type: array minItems: 1 items: type: string description: The ID of the user to be invited required: - users required: - role UserContentPermission: type: object description: Permission of a user in a content. properties: permission: $ref: "#/components/schemas/MemberRole" user: $ref: "#/components/schemas/User" required: - permission - user OrganizationTeamTitle: type: string description: Title of the team minLength: 1 maxLength: 64 OrganizationTeam: type: object properties: object: type: string description: Type of Object, always equals to "team" enum: - team id: type: string description: Unique identifier for the team. title: $ref: "#/components/schemas/OrganizationTeamTitle" members: type: integer description: Count of members in this team. spaces: type: number description: Count of spaces this team has access to. createdAt: description: Date at which the team was created. $ref: "#/components/schemas/Timestamp" permissions: type: object description: The set of permissions for the team properties: admin: type: boolean description: Can the user manage the team view: type: boolean description: Can the user view the team and list its members required: - admin - view required: - object - id - title - members - spaces - createdAt - permissions Icon: type: string maxLength: 50 format: icon description: Name of the icon example: gear RevisionPageBase: type: object properties: id: description: Unique identifier for the page in the revision type: string title: description: Title of the page type: string minLength: 1 linkTitle: description: Optional custom title for the page ToC and mention entries instead of the page title. type: string minLength: 1 maxLength: 100 emoji: description: Emoji of the page, if one has been set. $ref: "#/components/schemas/Emoji" icon: description: Icon of the page, if one has been set. $ref: "#/components/schemas/Icon" createdAt: description: When the page was first created. Only present if page has been edited at least once. $ref: "#/components/schemas/Timestamp" updatedAt: description: When the page was last edited. Only present if page has been edited at least once. $ref: "#/components/schemas/Timestamp" required: - id - title MarkdownDocument: type: object properties: markdown: type: string description: Content of the document formatted as markdown required: - markdown DocumentMarkBold: type: object properties: object: type: string enum: - mark type: type: string enum: - bold required: - object - type DocumentMarkItalic: type: object properties: object: type: string enum: - mark type: type: string enum: - italic required: - object - type DocumentMarkCode: type: object properties: object: type: string enum: - mark type: type: string enum: - code required: - object - type DocumentMarkKeyboard: type: object properties: object: type: string enum: - mark type: type: string enum: - keyboard required: - object - type DocumentMarkStrikethrough: type: object properties: object: type: string enum: - mark type: type: string enum: - strikethrough required: - object - type DocumentTextColor: type: string enum: - default - green - blue - red - orange - yellow - purple - $primary - $info - $success - $warning - $danger DocumentMarkColor: type: object properties: object: type: string enum: - mark type: type: string enum: - color data: type: object properties: text: $ref: "#/components/schemas/DocumentTextColor" background: $ref: "#/components/schemas/DocumentTextColor" required: - text - background required: - object - type - data DocumentMarkSuperscript: type: object properties: object: type: string enum: - mark type: type: string enum: - superscript required: - object - type DocumentMarkSubscript: type: object properties: object: type: string enum: - mark type: type: string enum: - subscript required: - object - type DocumentTextMark: oneOf: - $ref: "#/components/schemas/DocumentMarkBold" - $ref: "#/components/schemas/DocumentMarkItalic" - $ref: "#/components/schemas/DocumentMarkCode" - $ref: "#/components/schemas/DocumentMarkKeyboard" - $ref: "#/components/schemas/DocumentMarkStrikethrough" - $ref: "#/components/schemas/DocumentMarkColor" - $ref: "#/components/schemas/DocumentMarkSuperscript" - $ref: "#/components/schemas/DocumentMarkSubscript" DocumentTextLeaf: type: object properties: object: type: string enum: - leaf text: type: string marks: type: array items: $ref: "#/components/schemas/DocumentTextMark" required: - object - text - marks DocumentText: type: object properties: object: type: string enum: - text key: type: string leaves: type: array items: $ref: "#/components/schemas/DocumentTextLeaf" required: - object - leaves ContentRefURL: type: object properties: kind: type: string enum: - url url: type: string required: - kind - url ContentRefFile: type: object properties: kind: type: string enum: - file file: type: string space: description: ID of the space the file is in. The file is considered as in the current space if none is provided. type: string required: - kind - file DocumentInlineImage: type: object properties: object: type: string enum: - inline type: type: string enum: - inline-image key: type: string data: type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefURL" - $ref: "#/components/schemas/ContentRefFile" refDark: oneOf: - $ref: "#/components/schemas/ContentRefURL" - $ref: "#/components/schemas/ContentRefFile" caption: type: string alt: type: string size: type: string enum: - original - line required: - ref isVoid: type: boolean enum: - true required: - object - type - data - isVoid ContentRefPage: type: object properties: kind: type: string enum: - page page: type: string space: description: ID of the space the page is in. The page is considered as in the current space if none is provided. type: string required: - kind - page ContentRefAnchor: type: object properties: kind: type: string enum: - anchor anchor: type: string space: description: ID of the space the page is in. The page is considered as in the current space if none is provided. type: string page: description: ID of the page the anchor is in. The anchor is considered as in the current page if none is provided. type: string required: - kind - anchor ContentRefUser: type: object properties: kind: type: string enum: - user user: type: string required: - kind - user ContentRefCollection: type: object properties: kind: type: string enum: - collection collection: type: string required: - kind - collection ContentRefSpace: type: object properties: kind: type: string enum: - space space: type: string required: - kind - space ContentRefReusableContent: type: object properties: kind: type: string enum: - reusable-content reusableContent: type: string space: type: string description: The space in which the reusable content is defined. If undefined, the reusable content is assumed to be in the same space as the content reference. required: - kind - reusableContent ContentRefTag: type: object properties: kind: type: string enum: - tag tag: type: string description: The slug of the tag, also used as the ID, and references the tags defined on a revision. space: type: string description: The space in which the tag is defined. If undefined, the tag is assumed to be in the same space as the content reference. required: - kind - tag ContentRefOpenAPI: type: object properties: kind: type: string enum: - openapi spec: type: string description: Slug of the OpenAPI specification required: - kind - spec ContentRef: description: A relative reference to content in GitBook. oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" - $ref: "#/components/schemas/ContentRefPage" - $ref: "#/components/schemas/ContentRefAnchor" - $ref: "#/components/schemas/ContentRefUser" - $ref: "#/components/schemas/ContentRefCollection" - $ref: "#/components/schemas/ContentRefSpace" - $ref: "#/components/schemas/ContentRefReusableContent" - $ref: "#/components/schemas/ContentRefTag" - $ref: "#/components/schemas/ContentRefOpenAPI" DocumentInlineLink: type: object properties: object: type: string enum: - inline type: type: string enum: - link key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentText" - $ref: "#/components/schemas/DocumentInlineImage" data: type: object properties: ref: $ref: "#/components/schemas/ContentRef" required: - ref isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentInlineEmoji: type: object properties: object: type: string enum: - inline type: type: string enum: - emoji key: type: string data: type: object properties: code: type: string required: - code isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentInlineIcon: type: object properties: object: type: string enum: - inline type: type: string enum: - icon key: type: string data: type: object properties: icon: type: string color: $ref: "#/components/schemas/DocumentTextColor" required: - icon isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentInlineExpression: type: object properties: object: type: string enum: - inline type: type: string enum: - expression key: type: string data: type: object properties: expression: type: string required: - expression isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentInlineMath: type: object properties: object: type: string enum: - inline type: type: string enum: - inline-math key: type: string data: type: object properties: formula: type: string required: - formula isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockParagraph: type: object properties: object: type: string enum: - block type: type: string enum: - paragraph key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentInline" - $ref: "#/components/schemas/DocumentText" isVoid: type: boolean enum: - false data: type: object properties: align: $ref: "#/components/schemas/TextAlignment" additionalProperties: false required: - object - type - nodes DocumentInline: oneOf: - $ref: "#/components/schemas/DocumentInlineLink" - $ref: "#/components/schemas/DocumentInlineEmoji" - $ref: "#/components/schemas/DocumentInlineIcon" - $ref: "#/components/schemas/DocumentInlineExpression" - $ref: "#/components/schemas/DocumentInlineMath" - $ref: "#/components/schemas/DocumentInlineImage" - $ref: "#/components/schemas/DocumentInlineAnnotation" - $ref: "#/components/schemas/DocumentInlineMention" - $ref: "#/components/schemas/DocumentInlineButton" TextAlignment: type: string enum: - start - center - end DocumentBlockHeading: type: object properties: object: type: string enum: - block type: type: string enum: - heading-1 - heading-2 - heading-3 key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentInline" - $ref: "#/components/schemas/DocumentText" data: type: object properties: id: type: string pattern: ^[-a-z0-9.+_]+$ align: $ref: "#/components/schemas/TextAlignment" meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentBlocksEssentials: oneOf: - $ref: "#/components/schemas/DocumentBlockParagraph" - $ref: "#/components/schemas/DocumentBlockHeading" - $ref: "#/components/schemas/DocumentBlockListOrdered" - $ref: "#/components/schemas/DocumentBlockListUnordered" - $ref: "#/components/schemas/DocumentBlockListTasks" - $ref: "#/components/schemas/DocumentBlockDivider" DocumentInlineAnnotation: type: object properties: object: type: string enum: - inline type: type: string enum: - annotation key: type: string fragments: type: array items: allOf: - $ref: "#/components/schemas/DocumentFragment" - type: object properties: type: type: string enum: - annotation-body nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockCode" minItems: 1 required: - nodes - type isVoid: type: boolean enum: - false nodes: type: array items: $ref: "#/components/schemas/DocumentText" data: type: object properties: {} additionalProperties: false required: - object - type - fragments - isVoid - nodes DocumentBlockCodeLine: type: object properties: object: type: string enum: - block type: type: string enum: - code-line key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentText" - $ref: "#/components/schemas/DocumentInlineAnnotation" - $ref: "#/components/schemas/DocumentInlineExpression" data: type: object properties: highlighted: type: boolean isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentBlockCode: type: object properties: object: type: string enum: - block type: type: string enum: - code key: type: string data: type: object properties: syntax: type: string title: type: string overflow: type: string default: scroll enum: - scroll - wrap lineNumbers: type: boolean fullWidth: type: boolean expandable: type: boolean collapsedLineCount: type: integer description: Number of lines rendered in a code block when it is collapsed minimum: 1 default: 10 nodes: type: array items: $ref: "#/components/schemas/DocumentBlockCodeLine" isVoid: type: boolean enum: - false required: - object - type - data - nodes DocumentBlockHint: type: object properties: object: type: string enum: - block type: type: string enum: - hint key: type: string data: type: object properties: style: type: string enum: - info - warning - danger - success icon: $ref: "#/components/schemas/Icon" required: - style nodes: type: array items: $ref: "#/components/schemas/DocumentBlocksEssentials" isVoid: type: boolean enum: - false required: - object - type - data - nodes DocumentBlockQuote: type: object properties: object: type: string enum: - block type: type: string enum: - blockquote key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockQuote" isVoid: type: boolean enum: - false data: type: object properties: {} additionalProperties: false required: - object - type - nodes DocumentBlockMath: type: object properties: object: type: string enum: - block type: type: string enum: - math key: type: string data: type: object properties: formula: type: string required: - formula isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentTableViewGrid: type: object properties: type: type: string enum: - grid columns: type: array description: Ordered list of the definition IDs to display items: type: string columnWidths: type: object description: Percent width of each column additionalProperties: type: number hideHeader: type: boolean description: Should we display the header with column titles stickyHeader: type: boolean description: Should we keep the table header sticky while the page scrolls stickyFirstColumn: type: boolean description: Should we keep the first visible table column sticky while horizontally scrolling useNewSizing: type: boolean description: | Tables in GitBook originally used a scaled width approach i.e. the width defined in columnWidths would be scaled to ensure a 100% width table. We later changed this to treat the widths in columnWidths as exact values - they are never scaled. A columnWidth of 50 is rendered as 50px. In order to maintain backwards compatibility, we track whether or not we use the new system here. All new tables should have this value set to true, older tables will have it set to undefined. required: - type - columns - hideHeader DocumentTableViewCards: type: object properties: type: type: string enum: - cards cardSize: type: string description: Size of the cards. It indicates how many columns will be used enum: - medium - large columns: type: array description: Ordered list of the definition IDs to display items: type: string targetDefinition: type: string description: Definition ID to use as a target link for the card coverDefinition: type: string description: Definition ID to use as a cover image coverDefinitionDark: type: string description: Definition ID to use as a dark mode cover image hideColumnTitle: type: boolean description: Should we display the column title or not required: - type - columns - cardSize CardsImageObjectFit: type: string description: Object fit for image display in card views enum: - contain - fill - cover DocumentTableImageRecord: description: A table record value for image columns, supporting both direct ContentRefs and the additional format with record-level settings. oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" - type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" objectFit: $ref: "#/components/schemas/CardsImageObjectFit" alt: type: string description: Alternative text for the cover image required: - ref DocumentTableRecord: type: object properties: orderIndex: type: string values: type: object additionalProperties: oneOf: - type: number - type: - string - "null" - type: boolean - type: array items: type: string - $ref: "#/components/schemas/ContentRef" - $ref: "#/components/schemas/DocumentTableImageRecord" required: - orderIndex - values DocumentTableDefinitionBase: type: object properties: id: type: string title: type: string description: Title for the column required: - id - title VerticalAlignment: type: string enum: - top - middle - bottom DocumentTableDefinitionText: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - text textAlignment: type: string enum: - center - right - left verticalAlignment: $ref: "#/components/schemas/VerticalAlignment" required: - type - textAlignment DocumentTableDefinitionNumber: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - number required: - type DocumentTableDefinitionCheckbox: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - checkbox required: - type DocumentTableDefinitionFiles: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - files required: - type DocumentTableDefinitionUsers: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - users multiple: type: boolean required: - type - multiple DocumentTableDefinitionRating: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - rating max: type: number required: - type - max DocumentTableSelectOption: type: object properties: value: type: string label: type: string color: type: string required: - value - label - color DocumentTableDefinitionSelect: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - select multiple: type: boolean options: type: array items: $ref: "#/components/schemas/DocumentTableSelectOption" required: - type - multiple - options DocumentTableDefinitionContentRef: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - content-ref required: - type DocumentTableDefinitionImage: allOf: - $ref: "#/components/schemas/DocumentTableDefinitionBase" - type: object properties: type: type: string enum: - image required: - type DocumentTableDefinition: oneOf: - $ref: "#/components/schemas/DocumentTableDefinitionText" - $ref: "#/components/schemas/DocumentTableDefinitionNumber" - $ref: "#/components/schemas/DocumentTableDefinitionCheckbox" - $ref: "#/components/schemas/DocumentTableDefinitionFiles" - $ref: "#/components/schemas/DocumentTableDefinitionUsers" - $ref: "#/components/schemas/DocumentTableDefinitionRating" - $ref: "#/components/schemas/DocumentTableDefinitionSelect" - $ref: "#/components/schemas/DocumentTableDefinitionContentRef" - $ref: "#/components/schemas/DocumentTableDefinitionImage" DocumentFragment: type: object properties: object: type: string enum: - fragment key: type: string fragment: type: string type: type: string nodes: type: array items: $ref: "#/components/schemas/DocumentBlock" required: - object - nodes DocumentBlockTable: type: object properties: object: type: string enum: - block type: type: string enum: - table key: type: string isVoid: type: boolean enum: - true data: type: object properties: view: oneOf: - $ref: "#/components/schemas/DocumentTableViewGrid" - $ref: "#/components/schemas/DocumentTableViewCards" records: type: object additionalProperties: $ref: "#/components/schemas/DocumentTableRecord" definition: type: object additionalProperties: $ref: "#/components/schemas/DocumentTableDefinition" fullWidth: type: boolean description: Whether to render the block as a full width one required: - view - records - definition fragments: type: array items: $ref: "#/components/schemas/DocumentFragment" required: - object - type - data - isVoid - fragments DocumentBlockListItem: type: object properties: object: type: string enum: - block type: type: string enum: - list-item key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockTable" isVoid: type: boolean enum: - false data: type: object properties: checked: type: boolean required: - object - type - nodes DocumentBlockListOrdered: type: object properties: object: type: string enum: - block type: type: string enum: - list-ordered key: type: string data: type: object properties: start: type: number description: An integer to start counting from for the list items. nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlockListItem" isVoid: type: boolean enum: - false required: - object - type - data - nodes DocumentBlockListUnordered: type: object properties: object: type: string enum: - block type: type: string enum: - list-unordered key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlockListItem" data: type: object additionalProperties: false isVoid: type: boolean enum: - false required: - object - type - nodes DocumentBlockListTasks: type: object properties: object: type: string enum: - block type: type: string enum: - list-tasks key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlockListItem" isVoid: type: boolean enum: - false data: type: object properties: {} additionalProperties: false required: - object - type - nodes DocumentBlockDivider: type: object properties: object: type: string enum: - block type: type: string enum: - divider key: type: string isVoid: type: boolean enum: - true data: type: object properties: {} additionalProperties: false required: - object - type - isVoid - data DocumentBlocksTopLevels: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockExpandable" - $ref: "#/components/schemas/DocumentBlockTabs" - $ref: "#/components/schemas/DocumentBlockTable" - $ref: "#/components/schemas/DocumentBlockOpenAPI" - $ref: "#/components/schemas/DocumentBlockOpenAPIOperation" - $ref: "#/components/schemas/DocumentBlockOpenAPISchemas" - $ref: "#/components/schemas/DocumentBlockOpenAPIWebhook" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockIntegration" - $ref: "#/components/schemas/DocumentBlockReusableContent" - $ref: "#/components/schemas/DocumentBlockStepper" - $ref: "#/components/schemas/DocumentBlockIf" - $ref: "#/components/schemas/DocumentBlockColumns" DocumentBlockIf: type: object properties: object: type: string enum: - block type: type: string enum: - if key: type: string nodes: type: array items: $ref: "#/components/schemas/DocumentBlocksTopLevels" isVoid: type: boolean enum: - false data: type: object properties: expression: type: string required: - expression required: - object - type - nodes - data Length: oneOf: - type: number - type: object properties: unit: type: string value: type: number required: - unit - value DocumentBlockImage: type: object properties: object: type: string enum: - block type: type: string enum: - image key: type: string data: type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefURL" - $ref: "#/components/schemas/ContentRefFile" refDark: oneOf: - $ref: "#/components/schemas/ContentRefURL" - $ref: "#/components/schemas/ContentRefFile" width: $ref: "#/components/schemas/Length" height: $ref: "#/components/schemas/Length" alt: type: string required: - ref fragments: type: array items: allOf: - $ref: "#/components/schemas/DocumentFragment" - type: object properties: fragment: type: string enum: - caption nodes: type: array items: $ref: "#/components/schemas/DocumentBlockParagraph" required: - nodes - fragment isVoid: type: boolean enum: - true required: - object - type - data - fragments - isVoid DocumentBlockImages: type: object properties: object: type: string enum: - block type: type: string enum: - images key: type: string data: type: object properties: align: type: string enum: - center - left - right fullWidth: type: boolean withFrame: type: boolean nodes: type: array items: $ref: "#/components/schemas/DocumentBlockImage" isVoid: type: boolean enum: - false required: - object - type - data - nodes - isVoid DocumentBlockFile: type: object properties: object: type: string enum: - block type: type: string enum: - file key: type: string data: type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefFile" required: - ref isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockDrawing: type: object properties: object: type: string enum: - block type: type: string enum: - drawing key: type: string data: type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefFile" isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockEmbed: type: object properties: object: type: string enum: - block type: type: string enum: - embed key: type: string data: type: object properties: url: type: string fullWidth: type: boolean required: - url isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockReusableContent: type: object properties: object: type: string enum: - block type: type: string enum: - reusable-content key: type: string data: type: object properties: ref: $ref: "#/components/schemas/ContentRefReusableContent" required: - ref isVoid: type: boolean enum: - true meta: type: object properties: token: description: A content token that can be used to fetch the reusable content from the API. type: string required: - object - type - data - isVoid PlainObject: properties: {} additionalProperties: oneOf: - $ref: "#/components/schemas/PlainObject" - type: string - type: boolean - type: number - type: array items: oneOf: - type: string - type: boolean - type: number - $ref: "#/components/schemas/PlainObject" ContentKitDefaultAction: oneOf: - type: object description: Action to open an overlay modal defined by "componentId". properties: action: type: string enum: - "@ui.modal.open" componentId: type: string props: $ref: "#/components/schemas/PlainObject" required: - action - componentId - props - type: object description: Action when a modal overlay is closed, with a return value to the higher level component in the stack. This action will be triggered on the parent component instance. properties: action: type: string enum: - "@ui.modal.close" returnValue: $ref: "#/components/schemas/PlainObject" required: - action - returnValue - type: object description: Action to open an url. properties: action: type: string enum: - "@ui.url.open" url: type: string required: - action - url - type: object description: Action when a link is being unfurled into a block. properties: action: type: string enum: - "@link.unfurl" url: type: string required: - action - url - type: object description: Action to update the properties stored in the related node. properties: action: type: string enum: - "@editor.node.updateProps" props: $ref: "#/components/schemas/PlainObject" required: - action - props ContentKitAction: anyOf: - type: object description: Custom action to re-render the block. properties: action: type: string additionalProperties: true required: - action - $ref: "#/components/schemas/ContentKitDefaultAction" DocumentBlockIntegration: type: object properties: object: type: string enum: - block type: type: string enum: - integration key: type: string data: type: object properties: integration: type: string description: Name of the integration block: type: string description: ID of the block in the integration props: description: Properties passed to the block during rendering $ref: "#/components/schemas/PlainObject" action: $ref: "#/components/schemas/ContentKitAction" url: type: string description: | URL associated with the content represented by the block. This property is set when creating a block from a URL (unfurl) to ensure we can convert the block back to an embed. fullWidth: type: boolean required: - integration - block - props isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockExpandable: type: object properties: object: type: string enum: - block type: type: string enum: - expandable key: type: string isVoid: type: boolean enum: - true data: type: object properties: defaultExpanded: type: boolean additionalProperties: false fragments: type: array items: oneOf: - allOf: - $ref: "#/components/schemas/DocumentFragment" - type: object properties: fragment: type: string enum: - expandable-title type: type: string enum: - expandable-title nodes: type: array items: $ref: "#/components/schemas/DocumentBlockParagraph" minItems: 1 maxItems: 1 required: - nodes - fragment - type - allOf: - $ref: "#/components/schemas/DocumentFragment" - type: object properties: fragment: type: string enum: - expandable-body type: type: string enum: - expandable-body nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockTable" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockReusableContent" - $ref: "#/components/schemas/DocumentBlockIntegration" minItems: 1 required: - nodes - fragment - type meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id required: - object - type - isVoid - fragments - data DocumentBlockContentRef: type: object properties: object: type: string enum: - block type: type: string enum: - content-ref key: type: string data: type: object properties: ref: $ref: "#/components/schemas/ContentRef" required: - ref isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentBlockTabsItem: type: object properties: object: type: string enum: - block type: type: string enum: - tabs-item key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockIntegration" data: type: object properties: title: type: string meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentBlockTabs: type: object properties: object: type: string enum: - block type: type: string enum: - tabs key: type: string nodes: type: array items: $ref: "#/components/schemas/DocumentBlockTabsItem" isVoid: type: boolean enum: - false data: type: object properties: fullWidth: type: boolean additionalProperties: false required: - object - type - nodes OpenAPIOperationPointer: type: object description: Pointer to an operation in the OpenAPI spec. properties: path: type: string description: Path of the operation in the OpenAPI spec. method: type: string description: HTTP method of the operation in the OpenAPI spec. required: - path - method DocumentBlockOpenAPI: type: object properties: object: type: string enum: - block type: type: string enum: - swagger key: type: string data: allOf: - $ref: "#/components/schemas/OpenAPIOperationPointer" - type: object properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" expanded: type: boolean description: If true, the block is opened by default. fullWidth: type: boolean required: - ref isVoid: type: boolean enum: - true meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id required: - object - type - data - isVoid DocumentBlockOpenAPIOperation: type: object properties: object: type: string enum: - block type: type: string enum: - openapi-operation key: type: string data: allOf: - $ref: "#/components/schemas/OpenAPIOperationPointer" - type: object properties: ref: $ref: "#/components/schemas/ContentRefOpenAPI" required: - ref isVoid: type: boolean enum: - true meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id required: - object - type - data - isVoid OpenAPISchemasPointer: type: object description: Pointer to schemas in the OpenAPI spec. properties: grouped: type: boolean description: Whether the schemas are grouped or not. default: true schemas: type: array description: List of schemas name from the OpenAPI spec. items: type: string title: type: string description: Custom title for the schemas block. When not provided, defaults to "The object". required: - schemas DocumentBlockOpenAPISchemas: type: object properties: object: type: string enum: - block type: type: string enum: - openapi-schemas key: type: string data: allOf: - $ref: "#/components/schemas/OpenAPISchemasPointer" - type: object properties: ref: $ref: "#/components/schemas/ContentRefOpenAPI" required: - ref required: - ref isVoid: type: boolean enum: - true meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id required: - object - type - data - isVoid OpenAPIWebhookPointer: type: object description: Pointer to a webhook in the OpenAPI spec. properties: name: type: string description: Name of the webhook in the OpenAPI spec. method: type: string description: HTTP method of the webhook in the OpenAPI spec. required: - name - method DocumentBlockOpenAPIWebhook: type: object properties: object: type: string enum: - block type: type: string enum: - openapi-webhook key: type: string data: allOf: - $ref: "#/components/schemas/OpenAPIWebhookPointer" - type: object properties: ref: $ref: "#/components/schemas/ContentRefOpenAPI" required: - ref isVoid: type: boolean enum: - true meta: type: object properties: id: description: Unique ID to be used in an URL for the block. type: string required: - id required: - object - type - data - isVoid DocumentBlockStepperStep: type: object properties: object: type: string enum: - block type: type: string enum: - stepper-step key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockIntegration" - $ref: "#/components/schemas/DocumentBlockExpandable" data: type: object properties: icon: type: string isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentBlockStepper: type: object properties: object: type: string enum: - block type: type: string enum: - stepper key: type: string nodes: type: array items: $ref: "#/components/schemas/DocumentBlockStepperStep" isVoid: type: boolean enum: - false data: type: object properties: {} additionalProperties: false required: - object - type - nodes DocumentBlockColumn: type: object properties: object: type: string enum: - block type: type: string enum: - column key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockIntegration" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockTable" - $ref: "#/components/schemas/DocumentBlockExpandable" - $ref: "#/components/schemas/DocumentBlockStepper" isVoid: type: boolean enum: - false data: type: object properties: width: $ref: "#/components/schemas/Length" verticalAlignment: $ref: "#/components/schemas/VerticalAlignment" additionalProperties: false required: - object - type - nodes - data DocumentBlockColumns: type: object properties: object: type: string enum: - block type: type: string enum: - columns key: type: string data: type: object properties: fullWidth: type: boolean nodes: type: array items: $ref: "#/components/schemas/DocumentBlockColumn" isVoid: type: boolean enum: - false required: - object - type - data - nodes - isVoid DocumentBlockUpdate: type: object properties: object: type: string enum: - block type: type: string enum: - update key: type: string nodes: type: array items: oneOf: - $ref: "#/components/schemas/DocumentBlocksEssentials" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockIntegration" - $ref: "#/components/schemas/DocumentBlockTabs" - $ref: "#/components/schemas/DocumentBlockExpandable" data: type: object properties: date: $ref: "#/components/schemas/Timestamp" tags: type: array description: Array of tags. Each tag is id'ed by its slug. items: $ref: "#/components/schemas/ContentRefTag" required: - date isVoid: type: boolean enum: - false required: - object - type - nodes - data DocumentBlockUpdates: type: object properties: object: type: string enum: - block type: type: string enum: - updates key: type: string nodes: type: array items: $ref: "#/components/schemas/DocumentBlockUpdate" isVoid: type: boolean enum: - false data: type: object properties: format: type: string enum: - numeric - full - short default: full required: - format additionalProperties: false required: - object - type - nodes - data DocumentBlock: oneOf: - $ref: "#/components/schemas/DocumentBlockParagraph" - $ref: "#/components/schemas/DocumentBlockHeading" - $ref: "#/components/schemas/DocumentBlockListOrdered" - $ref: "#/components/schemas/DocumentBlockListUnordered" - $ref: "#/components/schemas/DocumentBlockListTasks" - $ref: "#/components/schemas/DocumentBlockListItem" - $ref: "#/components/schemas/DocumentBlockDivider" - $ref: "#/components/schemas/DocumentBlockQuote" - $ref: "#/components/schemas/DocumentBlockHint" - $ref: "#/components/schemas/DocumentBlockIf" - $ref: "#/components/schemas/DocumentBlockImages" - $ref: "#/components/schemas/DocumentBlockImage" - $ref: "#/components/schemas/DocumentBlockFile" - $ref: "#/components/schemas/DocumentBlockDrawing" - $ref: "#/components/schemas/DocumentBlockEmbed" - $ref: "#/components/schemas/DocumentBlockCode" - $ref: "#/components/schemas/DocumentBlockCodeLine" - $ref: "#/components/schemas/DocumentBlockMath" - $ref: "#/components/schemas/DocumentBlockExpandable" - $ref: "#/components/schemas/DocumentBlockTabs" - $ref: "#/components/schemas/DocumentBlockTabsItem" - $ref: "#/components/schemas/DocumentBlockTable" - $ref: "#/components/schemas/DocumentBlockOpenAPI" - $ref: "#/components/schemas/DocumentBlockOpenAPIOperation" - $ref: "#/components/schemas/DocumentBlockOpenAPISchemas" - $ref: "#/components/schemas/DocumentBlockOpenAPIWebhook" - $ref: "#/components/schemas/DocumentBlockContentRef" - $ref: "#/components/schemas/DocumentBlockIntegration" - $ref: "#/components/schemas/DocumentBlockReusableContent" - $ref: "#/components/schemas/DocumentBlockStepper" - $ref: "#/components/schemas/DocumentBlockStepperStep" - $ref: "#/components/schemas/DocumentBlockColumns" - $ref: "#/components/schemas/DocumentBlockColumn" - $ref: "#/components/schemas/DocumentBlockUpdates" - $ref: "#/components/schemas/DocumentBlockUpdate" DocumentInlineMention: type: object properties: object: type: string enum: - inline type: type: string enum: - mention key: type: string data: type: object properties: ref: $ref: "#/components/schemas/ContentRef" required: - ref isVoid: type: boolean enum: - true required: - object - type - data - isVoid DocumentAction: type: object oneOf: - type: object properties: action: type: string enum: - search query: type: string required: - action additionalProperties: false - type: object properties: action: type: string enum: - ask query: type: string required: - action additionalProperties: false DocumentInlineButton: type: object properties: object: type: string enum: - inline type: type: string enum: - button key: type: string data: allOf: - type: object properties: label: type: string kind: type: string enum: - primary - secondary icon: $ref: "#/components/schemas/Icon" required: - label - kind - oneOf: - type: object properties: ref: $ref: "#/components/schemas/ContentRef" required: - ref additionalProperties: false - type: object properties: action: $ref: "#/components/schemas/DocumentAction" required: - action additionalProperties: false isVoid: type: boolean enum: - true required: - object - type - data - isVoid JSONDocument: type: object properties: object: type: string enum: - document data: type: object properties: schemaVersion: description: The schema version of the document. If undefined, the document is considered to be of the latest schema version. type: integer additionalProperties: true nodes: type: array items: $ref: "#/components/schemas/DocumentBlocksTopLevels" meta: type: object properties: token: description: A content token that can be used to fetch the content referenced in this document from the API. type: string required: - object - data - nodes Document: oneOf: - $ref: "#/components/schemas/MarkdownDocument" title: Markdown - type: object title: JSON Document properties: document: $ref: "#/components/schemas/JSONDocument" required: - document - type: object title: Empty properties: {} additionalProperties: false RevisionPageSlug: type: string description: Page's slug in its direct parent minLength: 0 maxLength: 100 RevisionPageDocument: allOf: - $ref: "#/components/schemas/RevisionPageBase" - $ref: "#/components/schemas/Document" - type: object properties: kind: type: string deprecated: true enum: - sheet type: type: string enum: - document urls: required: - app properties: app: description: Location of the page in the app $ref: "#/components/schemas/URL" slug: $ref: "#/components/schemas/RevisionPageSlug" path: description: Complete path to access the page in the revision. type: string description: type: string pages: type: array items: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageLink" - $ref: "#/components/schemas/RevisionPageComputed" git: $ref: "#/components/schemas/GitSyncBlob" layout: $ref: "#/components/schemas/RevisionPageLayoutOptions" cover: $ref: "#/components/schemas/RevisionPageDocumentCover" variables: $ref: "#/components/schemas/Variables" hidden: type: boolean description: If true, the page is not displayed in the navigation, while still being accessible. default: false noIndex: type: boolean description: If true, the page is not indexable in the search and ask features. default: false noRobotsIndex: type: boolean description: If true, the page is not indexable by search engine robots. default: false metaLinks: description: Meta links associated with the page. $ref: "#/components/schemas/RevisionPageMetaLinks" tags: type: array description: A list of all the tags added to this page items: $ref: "#/components/schemas/RevisionPageTag" required: - kind - type - urls - slug - path - pages - layout - tags - oneOf: - type: object description: Defined when the page was generated by a computed content. properties: computed: $ref: "#/components/schemas/ComputedContentSourceDocument" computedSeed: type: string description: Seed to use for the generation of IDs. required: - computed - computedSeed - type: object properties: documentId: type: string description: ID of the document with the page body. If undefined, the page is empty. RevisionPageLink: allOf: - $ref: "#/components/schemas/RevisionPageBase" - type: object properties: kind: type: string deprecated: true enum: - link type: type: string enum: - link target: $ref: "#/components/schemas/ContentRef" href: type: string hidden: type: boolean description: If true, the page is not displayed in the navigation, while still being accessible. default: false required: - kind - type - target OpenAPISpecVisibility: type: string description: | The visibility setting of the OpenAPI spec. * `private`: The spec is not publicly available. * `public`: The spec is available to anyone with a public link. enum: - private - public ComputedContentDependencyOpenAPI: type: object properties: ref: $ref: "#/components/schemas/ContentRefOpenAPI" value: type: - object - "null" description: See `OpenAPI` schema component. properties: object: type: string enum: - openapi-spec id: type: string slug: type: string lastVersion: type: string visibility: $ref: "#/components/schemas/OpenAPISpecVisibility" required: - object - id - slug required: - ref - value ComputedContentSourceOpenAPIBase: type: object description: Generic parameters from an OpenAPI computed content source properties: type: type: string enum: - builtin:openapi dependencies: type: object required: - spec properties: spec: oneOf: - type: object additionalProperties: false required: - ref properties: ref: $ref: "#/components/schemas/ContentRefOpenAPI" - $ref: "#/components/schemas/ComputedContentDependencyOpenAPI" required: - type - dependencies ComputedContentSourceRevisionOpenAPI: allOf: - $ref: "#/components/schemas/ComputedContentSourceOpenAPIBase" - type: object description: Parameters for an OpenAPI computed revision required: - props properties: props: type: object properties: models: type: boolean downloadLink: type: boolean description: Whether to show a link to download the OpenAPI spec. required: - models TranslationRef: type: object properties: kind: type: string enum: - translation translation: type: string description: ID of the translation sync required: - kind - translation TranslationResult: type: object description: Result of a translation. properties: space: type: string description: ID of the space containing the result of the translation revision: type: string description: ID of the revision generated by the translation required: - space - revision ComputedContentDependencyTranslation: type: object properties: ref: $ref: "#/components/schemas/TranslationRef" value: oneOf: - $ref: "#/components/schemas/TranslationResult" - type: "null" description: Translation has not been run yet required: - ref - value ComputedContentSourceRevisionTranslation: type: object description: Parameters for a translation computed content source properties: type: type: string enum: - builtin:translation props: type: object additionalProperties: false properties: {} dependencies: type: object required: - translation properties: translation: oneOf: - type: object additionalProperties: false required: - ref properties: ref: $ref: "#/components/schemas/TranslationRef" - $ref: "#/components/schemas/ComputedContentDependencyTranslation" required: - type - props - dependencies ComputedContentDependency: type: object description: Dependency for a computation, before its resolution. additionalProperties: false properties: ref: oneOf: - $ref: "#/components/schemas/ContentRefSpace" - $ref: "#/components/schemas/ContentRefOpenAPI" - $ref: "#/components/schemas/TranslationRef" required: - ref ComputedContentDependencySpace: type: object properties: ref: $ref: "#/components/schemas/ContentRefSpace" value: type: - object - "null" description: See `Space` schema component. properties: object: type: string enum: - space id: type: string revision: type: string required: - object - id - revision required: - ref - value ComputedContentDependencyResolved: description: Dependency for a computation, with its resolved value. oneOf: - $ref: "#/components/schemas/ComputedContentDependencySpace" - $ref: "#/components/schemas/ComputedContentDependencyOpenAPI" - $ref: "#/components/schemas/ComputedContentDependencyTranslation" ComputedContentSourceIntegration: type: object description: Parameters for a computed content managed by an integration properties: type: type: string description: Type of the computed source pattern: ^integration:[^:]+:[^:]+$ x-typescript: "`integration:${string}:${string}`" props: description: Properties to be passed to the computation $ref: "#/components/schemas/PlainObject" dependencies: type: object description: | Dependencies the computation depends on. The state of the dependencies will be passed to the computation. When the dependency's targets are updated, the computation will be updated. additionalProperties: anyOf: - $ref: "#/components/schemas/ComputedContentDependency" - $ref: "#/components/schemas/ComputedContentDependencyResolved" required: - type - props ComputedContentSourceRevision: oneOf: - $ref: "#/components/schemas/ComputedContentSourceRevisionOpenAPI" - $ref: "#/components/schemas/ComputedContentSourceRevisionTranslation" - $ref: "#/components/schemas/ComputedContentSourceIntegration" RevisionPageComputed: allOf: - $ref: "#/components/schemas/RevisionPageBase" - type: object properties: type: type: string enum: - computed computed: $ref: "#/components/schemas/ComputedContentSourceRevision" required: - type - computed GitSyncBlob: type: object properties: oid: type: string description: SHA for the blob path: type: string description: Path of the blob in the Git tree required: - oid - path RevisionPageLayoutOptionsWidth: type: string description: Width of the page. enum: - default - wide RevisionPageLayoutOptionsCoverSize: type: string description: Size of the cover image. enum: - hero - full RevisionPageLayoutOptions: type: object properties: width: $ref: "#/components/schemas/RevisionPageLayoutOptionsWidth" cover: type: boolean description: Should the cover be visible? coverSize: $ref: "#/components/schemas/RevisionPageLayoutOptionsCoverSize" title: type: boolean description: Should the title be visible? description: type: boolean description: Should the description be visible? tableOfContents: type: boolean description: Should the table of contents be visible? outline: type: boolean description: Should the outline be visible? pagination: type: boolean description: Should the pagination be visible? metadata: type: boolean description: Should the page metadata (last modified, author, etc.) be visible? tags: type: boolean description: Should the tags be visible on the page? required: - width - cover - coverSize - title - description - tableOfContents - outline - pagination - metadata - tags RevisionPageDocumentCover: type: object properties: ref: description: Content reference pointing to the source image. oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" refDark: description: Content reference pointing to the source image for dark mode. oneOf: - $ref: "#/components/schemas/ContentRefFile" - $ref: "#/components/schemas/ContentRefURL" yPos: description: Vertical position of the cover image. type: number default: 0 height: description: Height of the cover image in pixels. type: number minimum: 10 maximum: 700 default: 240 required: - yPos VariableValue: oneOf: - type: string maxLength: 256 - type: number - type: boolean Variables: type: object additionalProperties: $ref: "#/components/schemas/VariableValue" RevisionPageMetaLinkTarget: oneOf: - $ref: "#/components/schemas/ContentRefPage" - $ref: "#/components/schemas/ContentRefURL" RevisionPageMetaLinks: type: object properties: canonical: $ref: "#/components/schemas/RevisionPageMetaLinkTarget" alternates: type: array items: $ref: "#/components/schemas/RevisionPageMetaLinkTarget" RevisionPageTag: type: object description: A reference to a tag with optional primary flag for page-level tags. properties: tag: $ref: "#/components/schemas/ContentRefTag" primary: type: boolean description: Whether this is the primary tag for display in table of contents. required: - tag ComputedContentSourceDocumentOpenAPI: allOf: - $ref: "#/components/schemas/ComputedContentSourceOpenAPIBase" - type: object description: Parameters for an OpenAPI computed document required: - props properties: props: oneOf: - type: object required: - doc properties: doc: type: string enum: - models - type: object required: - doc - page properties: doc: type: string enum: - operations - info page: type: string minLength: 1 ComputedContentSourceDocumentTranslation: type: object description: Parameters for a document translation computed content source required: - type - props properties: type: type: string enum: - builtin:translation props: type: object required: - space - document properties: space: type: string document: type: string ComputedContentSourceDocument: oneOf: - $ref: "#/components/schemas/ComputedContentSourceDocumentOpenAPI" - $ref: "#/components/schemas/ComputedContentSourceDocumentTranslation" - $ref: "#/components/schemas/ComputedContentSourceIntegration" RevisionPageGroup: allOf: - $ref: "#/components/schemas/RevisionPageBase" - type: object properties: kind: type: string deprecated: true enum: - group type: type: string enum: - group slug: description: Page's slug in its direct parent type: string path: description: Complete path to access the page in the revision. type: string hidden: type: boolean description: If true, the page is not displayed in the navigation, while still being accessible. default: false noIndex: type: boolean description: If true, the page is not indexable in the search and ask features. default: false noRobotsIndex: type: boolean description: If true, the page is not indexable by search engine robots. default: false pages: type: array items: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageLink" - $ref: "#/components/schemas/RevisionPageComputed" required: - kind - type - slug - path - pages RevisionPage: oneOf: - $ref: "#/components/schemas/RevisionPageDocument" - $ref: "#/components/schemas/RevisionPageGroup" - $ref: "#/components/schemas/RevisionPageLink" - $ref: "#/components/schemas/RevisionPageComputed" discriminator: propertyName: type RevisionFile: type: object properties: id: type: string name: type: string contentType: type: string downloadURL: type: string size: type: number dimensions: type: object description: For images, it contains the dimensions of it. properties: width: type: number height: type: number required: - width - height git: $ref: "#/components/schemas/GitSyncBlob" required: - id - name - contentType - downloadURL - size RevisionReusableContent: allOf: - type: object properties: id: type: string title: type: string git: $ref: "#/components/schemas/GitSyncBlob" required: - id - title - oneOf: - type: object description: Defined when the reusable content was generated by a computed content. properties: computed: $ref: "#/components/schemas/ComputedContentSourceDocument" computedSeed: type: string description: Seed to use for the generation of IDs. required: - computed - computedSeed - type: object properties: document: type: string description: ID of the document with the content body. If undefined, the reusable content is empty. RevisionTag: allOf: - type: object description: A reusable tag that different types of content can be associated to (e.g. pages, update entries) properties: slug: type: string description: The slug identifier for the tag, immutable after creation. label: type: string description: Display label for the tag. Can be renamed and differ from the slug. color: $ref: "#/components/schemas/DocumentTextColor" required: - slug - label - color - oneOf: - type: object properties: emoji: $ref: "#/components/schemas/Emoji" required: - emoji - type: object properties: icon: $ref: "#/components/schemas/Icon" GitSyncCommit: type: object properties: oid: type: string description: SHA for the commit message: type: string description: Message describing the purpose of the commit createdByGitBook: type: boolean description: If true, the Git commit was generated by an export from GitBook url: type: string description: URL of the commit in the GitSync provider ref: type: string description: Original name of the ref where the commit originated from required: - oid - message - createdByGitBook RevisionBase: type: object properties: object: type: string description: Type of Object, always equals to "revision" enum: - revision id: description: Unique identifier for the revision type: string parents: description: IDs of the parent revisions type: array items: type: string pages: type: array items: $ref: "#/components/schemas/RevisionPage" files: type: array items: $ref: "#/components/schemas/RevisionFile" reusableContents: type: array items: $ref: "#/components/schemas/RevisionReusableContent" tags: type: array description: List of available tags within this revision items: $ref: "#/components/schemas/RevisionTag" variables: $ref: "#/components/schemas/Variables" createdAt: description: When the revision was created. $ref: "#/components/schemas/Timestamp" git: description: Metadata about a potential associated git commit. $ref: "#/components/schemas/GitSyncCommit" urls: type: object properties: app: type: string format: uri description: URL in the application for the revision published: type: string description: URL of the published version of the revision. Only defined when the space visibility is not "private." format: uri public: type: string description: URL of the public version of the revision. Only defined when the space visibility is "public". format: uri required: - app required: - object - id - parents - pages - files - reusableContents - tags - urls - createdAt RevisionTypeEdits: allOf: - $ref: "#/components/schemas/RevisionBase" - type: object properties: type: type: string description: Revision created by editing the content. enum: - edits required: - type ChangeRequestStatus: type: string enum: - draft - open - archived - merged ChangeRequestSubject: type: string description: Subject of the change request minLength: 0 maxLength: 100 ChangeRequestLinkTitle: type: string description: Optional title to display for the link. maxLength: 128 ChangeRequestLink: type: object properties: ref: $ref: "#/components/schemas/ContentRefURL" title: $ref: "#/components/schemas/ChangeRequestLinkTitle" required: - ref ChangeRequestLinks: type: array description: External links associated with the change request. items: $ref: "#/components/schemas/ChangeRequestLink" maxItems: 10 ChangeRequest: type: object properties: object: type: string description: Type of Object, always equals to "change-request" enum: - change-request id: type: string description: Unique identifier for the change request number: type: number description: Incremental identifier of the change request status: $ref: "#/components/schemas/ChangeRequestStatus" subject: $ref: "#/components/schemas/ChangeRequestSubject" description: $ref: "#/components/schemas/JSONDocument" createdBy: $ref: "#/components/schemas/User" createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" space: type: string description: ID of the space in which the change request was created. revision: type: string description: ID of the active revision in the change request. revisionInitial: type: string description: ID of the initial revision in the space from which the change request was created. revisionMergedAncestor: type: string description: ID of the latest revision when updating from main space content. revisionMerged: type: string description: When merged, ID of the revision resulting from the merge. comments: type: number description: Count of opened comments on the change request. siteTopic: type: object description: Site context associated with the change request when it was created from a site topic or finding. properties: site: type: string description: ID of the site associated with the change request. topic: type: string description: ID of the site topic associated with the change request. finding: type: string description: ID of the site finding associated with the change request, when applicable. required: - site - topic outdated: type: boolean description: If true, the change request is not up-to-date with latest changes in the main content. links: $ref: "#/components/schemas/ChangeRequestLinks" urls: type: object description: URLs associated with the object properties: app: type: string description: URL of the space in the application format: uri location: type: string description: URL of the user in the API format: uri required: - app - location required: - object - id - number - status - subject - createdBy - createdAt - updatedAt - space - revision - revisionInitial - comments - outdated - urls RevisionTypeMerge: allOf: - $ref: "#/components/schemas/RevisionBase" - type: object properties: type: type: string description: Revision created when merging a change request with primary. enum: - merge mergedFrom: $ref: "#/components/schemas/ChangeRequest" required: - type - mergedFrom RevisionTypeRollback: allOf: - $ref: "#/components/schemas/RevisionBase" - type: object properties: type: type: string description: Revision created as a rollback of a previous revision. enum: - rollback required: - type RevisionTypeUpdate: allOf: - $ref: "#/components/schemas/RevisionBase" - type: object properties: type: type: string description: Revision created when updating a change request with changes from primary. enum: - update required: - type RevisionTypeComputed: allOf: - $ref: "#/components/schemas/RevisionBase" - type: object properties: type: type: string description: Virtual revision, computed from a source revision enum: - computed required: - type Revision: oneOf: - $ref: "#/components/schemas/RevisionTypeEdits" - $ref: "#/components/schemas/RevisionTypeMerge" - $ref: "#/components/schemas/RevisionTypeRollback" - $ref: "#/components/schemas/RevisionTypeUpdate" - $ref: "#/components/schemas/RevisionTypeComputed" discriminator: propertyName: type SpaceTemplateParams: type: object description: Parameters for a space template properties: contentRefs: type: object additionalProperties: type: object $ref: "#/components/schemas/ContentRef" ApplySpaceTemplate: type: object properties: id: type: string description: The ID of the template to use for the space params: $ref: "#/components/schemas/SpaceTemplateParams" required: - id OrganizationTitle: type: string description: Name of the organization minLength: 2 maxLength: 255 pattern: \S.*\S OrganizationEmailDomains: type: array items: type: string OrganizationHostname: type: string description: Default hostname for the organization's public content, e.g. .gitbook.io minLength: 3 maxLength: 32 OrganizationType: type: string enum: - business - community OrganizationUseCase: type: string enum: - internalDocs - docsSite - audienceControlledSite - productDocs - teamKnowledgeBase - designSystem - openSourceDocs - notes - other OrganizationCommunityType: type: string enum: - nonProfit - openSource - education SitePointer: type: object properties: type: type: string enum: - site site: type: string description: Unique identifier for the site required: - type - site OrganizationDefaultContent: description: The default content for the organization oneOf: - $ref: "#/components/schemas/SitePointer" BillingProduct: type: string description: Name of the product enum: - free_2024 - plus_2024 - pro_2024 - enterprise_2024 - community_2024 - free - plus - pro - internal BillingInterval: type: string description: Interval for a billing subscription enum: - monthly - yearly OrganizationPricePair: type: object description: Pricing pair for monthly and yearly intervals properties: monthly: type: number description: Monthly price in USD minimum: 0 yearly: type: number description: Yearly price in USD (per month) minimum: 0 required: - monthly - yearly OrganizationPricing: type: object description: Pricing information for an organization properties: members: type: object description: Pricing for members (organization plan) properties: plus_2024: $ref: "#/components/schemas/OrganizationPricePair" pro_2024: $ref: "#/components/schemas/OrganizationPricePair" required: - plus_2024 - pro_2024 additionalProperties: false sites: type: object description: Pricing for site types (site plans) properties: premium: $ref: "#/components/schemas/OrganizationPricePair" ultimate: $ref: "#/components/schemas/OrganizationPricePair" required: - premium - ultimate additionalProperties: false required: - members - sites BillingMeterAddon: type: object properties: enabled: type: boolean required: - enabled OrganizationBilling: type: object properties: interval: $ref: "#/components/schemas/BillingInterval" endDate: oneOf: - $ref: "#/components/schemas/Timestamp" - type: "null" hasPaymentFailed: description: If true, we were unable to collect the last payment type: boolean canCheckout: description: | If true, organization can create a checkout session to subscribe/update billing. If false, organization must resolve other billing issues before a checkout can be done. type: boolean isScheduledToCancel: description: If true, the billing is set to cancel at the end of its current period type: boolean pricing: description: Pricing information for the organization $ref: "#/components/schemas/OrganizationPricing" usageAddons: description: Configuration for the usage-based addons type: object additionalProperties: $ref: "#/components/schemas/BillingMeterAddon" minUsers: description: The minimum number of members allowed for this organization. type: number maxUsers: description: The maximum number of members allowed for this organization type: number minPremiumSites: description: The minimum number of premium sites allowed for this organization. type: number maxPremiumSites: description: The maximum number of premium sites allowed for this organization. type: number minUltimateSites: description: The minimum number of ultimate sites allowed for this organization. type: number maxUltimateSites: description: The maximum number of ultimate sites allowed for this organization. type: number paidMembers: description: The number of paid members on the current subscription. type: number paidPremiumSites: description: The number of paid premium sites on the current subscription. type: number paidUltimateSites: description: The number of paid ultimate sites on the current subscription. type: number required: - interval - endDate - hasPaymentFailed - canCheckout - isScheduledToCancel - pricing - usageAddons BillingTrialStatus: type: string description: | - notapplicable, no trial can be started for this organization. - none, no trial has been started yet. - active, trial is active. - ended, the trial has ended and the user has choosen to stay on the free plan or has upgraded to a paid plan. - expired, the trial has ended but the user hasn't deciced yet what to do. enum: - notapplicable - none - active - ended - expired BlockSource: type: string description: Source for an organization block enum: - backoffice - external - internal BlockReason: type: string description: A short description giving context on the reason for the block. minLength: 1 maxLength: 255 Organization: type: object properties: object: type: string description: Type of Object, always equals to "organization" enum: - organization id: type: string description: Unique identifier for the organization title: $ref: "#/components/schemas/OrganizationTitle" createdAt: $ref: "#/components/schemas/Timestamp" emailDomains: $ref: "#/components/schemas/OrganizationEmailDomains" hostname: $ref: "#/components/schemas/OrganizationHostname" type: $ref: "#/components/schemas/OrganizationType" useCase: $ref: "#/components/schemas/OrganizationUseCase" communityType: $ref: "#/components/schemas/OrganizationCommunityType" defaultRole: $ref: "#/components/schemas/MemberRoleOrGuest" defaultContent: $ref: "#/components/schemas/OrganizationDefaultContent" sso: description: Whether SSO is enforced organization-wide type: boolean ai: description: If true, the organization is configured to use all our AI features. type: boolean inviteLinks: description: If true, invite links are enabled for this organization. type: boolean plan: $ref: "#/components/schemas/BillingProduct" billing: description: Billing details, only available for org members. $ref: "#/components/schemas/OrganizationBilling" mergeRules: $ref: "#/components/schemas/MergeRulesStandaloneConfiguration" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the organization in the API format: uri app: type: string description: URL of the organization in the application format: uri logo: description: URL of the logo of this organization, if defined. $ref: "#/components/schemas/URL" required: - app - location trial: type: object properties: status: $ref: "#/components/schemas/BillingTrialStatus" count: type: integer description: Number of trials the organization has consumed. endDate: description: The trial's end date, if the organization has or had a trial. $ref: "#/components/schemas/Timestamp" decision: type: string description: The decision taken by the user at the end of the trial enum: - downgrade required: - status - count customHostname: description: Custom hostname linked to this organization type: string blocked: type: object description: If the organization is blocked, information about the block will appear here properties: source: $ref: "#/components/schemas/BlockSource" reason: $ref: "#/components/schemas/BlockReason" required: - reason internal_billingMigration: type: object properties: deadline: description: When we will upgrade the organization onto new pricing, if they haven't already. $ref: "#/components/schemas/Timestamp" discountPercent: description: A discount the organization may have received thanks to migrating early. type: number discountEndDate: description: The expiration date of the discount, after wich regular pricing resumes. $ref: "#/components/schemas/Timestamp" permissions: type: object description: The set of permissions for the organization properties: view: type: boolean description: Can the user view the organization. access: type: boolean description: Can the user view the organization in the application. admin: type: boolean description: Can the user manage the title, members, etc. ownTeam: type: boolean description: Is the user a team owner. createContent: type: boolean description: Can the user create new spaces/collections in the organization. createOpenAPISpec: type: boolean description: Can the user create new OpenAPI specifications. viewBilling: type: boolean description: Can the user view the billing details of the organization. listMembers: type: boolean description: Can the user list the members of the organization. listTeams: type: boolean description: Can the user list the teams in the organization. listIntegrations: type: boolean description: Can the user list the integrations in the organization. listInstallations: type: boolean description: Can the user list the integration installations in the organization. installIntegration: type: boolean description: Can the user install integrations in the organization. required: - view - access - admin - ownTeam - createContent - createOpenAPISpec - viewBilling - listMembers - listTeams - listIntegrations - listInstallations - installIntegration required: - object - id - plan - title - createdAt - inviteLinks - type - emailDomains - mergeRules - urls - trial - permissions ContentLocationRevisionContext: type: object required: - type - revision properties: type: type: string enum: - revision revision: $ref: "#/components/schemas/Revision" ContentLocationChangeRequestContext: type: object required: - type - changeRequest properties: type: type: string enum: - changeRequest changeRequest: $ref: "#/components/schemas/ChangeRequest" ContentLocationFile: type: object properties: kind: type: string enum: - file organization: $ref: "#/components/schemas/Organization" space: $ref: "#/components/schemas/Space" versionContext: oneOf: - $ref: "#/components/schemas/ContentLocationRevisionContext" - $ref: "#/components/schemas/ContentLocationChangeRequestContext" file: $ref: "#/components/schemas/RevisionFile" required: - kind - organization - space - file ContentLocationURL: type: object properties: kind: type: string enum: - url url: type: string required: - kind - url ContentLocationPageAnchor: type: object properties: type: type: string enum: - anchor anchor: description: The anchor within the page. type: string required: - type - anchor ContentLocationPageNode: type: object properties: type: type: string enum: - node node: description: The node id within the page. type: string required: - type - node ContentLocationPage: type: object properties: kind: type: string enum: - page organization: $ref: "#/components/schemas/Organization" page: $ref: "#/components/schemas/RevisionPage" space: $ref: "#/components/schemas/Space" versionContext: oneOf: - $ref: "#/components/schemas/ContentLocationRevisionContext" - $ref: "#/components/schemas/ContentLocationChangeRequestContext" internalLocation: oneOf: - $ref: "#/components/schemas/ContentLocationPageAnchor" - $ref: "#/components/schemas/ContentLocationPageNode" required: - kind - organization - space - page ContentLocationUser: type: object properties: kind: type: string enum: - user user: $ref: "#/components/schemas/User" required: - kind - user CollectionTitle: type: string description: Title of the collection maxLength: 50 CollectionDescription: type: string description: Description of the collection minLength: 0 maxLength: 100 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 ContentLocationCollection: type: object properties: kind: type: string enum: - collection organization: $ref: "#/components/schemas/Organization" collection: $ref: "#/components/schemas/Collection" required: - kind - organization - collection ContentLocationSpace: type: object properties: kind: type: string enum: - space organization: $ref: "#/components/schemas/Organization" space: $ref: "#/components/schemas/Space" required: - kind - organization - space ContentLocationReusableContent: type: object properties: kind: type: string enum: - reusable-content organization: $ref: "#/components/schemas/Organization" space: $ref: "#/components/schemas/Space" versionContext: oneOf: - $ref: "#/components/schemas/ContentLocationRevisionContext" - $ref: "#/components/schemas/ContentLocationChangeRequestContext" reusableContent: $ref: "#/components/schemas/RevisionReusableContent" required: - kind - organization - space - reusableContent OpenAPISpecSlug: description: Slug used as reference type: string minLength: 1 maxLength: 100 pattern: ^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$ OpenAPISpecProcessingState: description: Processing state enum: - pending - progress - complete OpenAPISpecProcessingErrorCode: description: OpenAPI processing error code enum: - FETCH_TIMEOUT - FETCH_ERROR - PARSE_ERROR OpenAPIErrorObject: type: object description: OpenAPI error object. properties: message: type: string description: Description of the error. code: type: string description: Unique code of the error. required: - message OpenAPISpec: type: object properties: object: description: The object type, which is always "openapi-spec" type: string enum: - openapi-spec id: description: Unique identifier type: string createdAt: description: Date of creation $ref: "#/components/schemas/Timestamp" updatedAt: description: Date of the last update $ref: "#/components/schemas/Timestamp" slug: $ref: "#/components/schemas/OpenAPISpecSlug" sourceURL: $ref: "#/components/schemas/URL" processingState: $ref: "#/components/schemas/OpenAPISpecProcessingState" visibility: $ref: "#/components/schemas/OpenAPISpecVisibility" lastVersion: type: string description: ID of the latest version of the OpenAPI specification lastProcessedAt: description: Date of the last processing $ref: "#/components/schemas/Timestamp" lastProcessErrorCode: $ref: "#/components/schemas/OpenAPISpecProcessingErrorCode" lastProcessedErrors: type: array items: $ref: "#/components/schemas/OpenAPIErrorObject" lastProcessedErrorCount: type: integer minimum: 0 description: Total number of processing errors before truncation of lastProcessedErrors. permissions: type: object description: The set of permissions for the OpenAPI specification. required: - view - edit properties: view: type: boolean description: Can the user view the specification. edit: type: boolean description: Can the user edit the specification. urls: type: object description: URLs associated with the object properties: location: description: URL of the OpenAPI specification in the API $ref: "#/components/schemas/URL" app: description: URL of the OpenAPI specification in the application $ref: "#/components/schemas/URL" published: type: string description: URL of the published spec. Only defined when visibility is "published." format: uri required: - app - location required: - object - id - createdAt - updatedAt - slug - processingState - lastProcessedErrorCount - permissions - urls ContentLocationOpenAPI: type: object properties: kind: type: string enum: - openapi organization: $ref: "#/components/schemas/Organization" openAPISpec: $ref: "#/components/schemas/OpenAPISpec" required: - kind - organization - openAPISpec ContentLocation: description: An absolute reference to content in GitBook. oneOf: - $ref: "#/components/schemas/ContentLocationFile" - $ref: "#/components/schemas/ContentLocationURL" - $ref: "#/components/schemas/ContentLocationPage" - $ref: "#/components/schemas/ContentLocationUser" - $ref: "#/components/schemas/ContentLocationCollection" - $ref: "#/components/schemas/ContentLocationSpace" - $ref: "#/components/schemas/ContentLocationReusableContent" - $ref: "#/components/schemas/ContentLocationOpenAPI" discriminator: propertyName: kind ContentReferenceStatus: type: string enum: - ok - broken - in-app description: | Text to display to represent the reference. Possible values include: - `ok` - No problems detected for this content reference. - `broken` - The target does not exist in the revision. - `in-app` - The target is a URL link pointing to an internal location in the app. ContentReferencesStats: type: object properties: total: description: Total count of links type: number broken: type: object properties: total: description: Count of broken links type: number changeRequest: description: Count of broken links that were broken in current change request, if applicable. type: number required: - total required: - total - broken ContentReferenceRelation: type: string enum: - reference - dependsOn description: | Indicator of the relationship with the content ref target. - `reference` - The content soft-references the ref target - `dependsOn` - The content depends on the ref target ContentReferenceUsage: type: object properties: status: $ref: "#/components/schemas/ContentReferenceStatus" relation: $ref: "#/components/schemas/ContentReferenceRelation" targetReference: description: The reference target where a list of pages are pointing at $ref: "#/components/schemas/ContentLocation" locationReferences: description: Pages locations where a link to the target is found. type: array items: $ref: "#/components/schemas/ContentLocation" required: - relation - status - locationReferences ChangeRequestOrderBy: type: string enum: - updatedAt - createdAt default: updatedAt description: The field to sort change requests by. Defaults to 'updatedAt'. ChangeRequestReviewStatus: type: string description: Status of a change request review. enum: - changes-requested - approved EmojiReaction: type: object description: An emoji reaction by one or many users properties: emoji: type: string description: The Emoji of the reaction count: type: number description: The number of users who reacted with this emoji users: type: array description: The users who reacted with this emoji items: type: object properties: user: $ref: "#/components/schemas/User" reactedAt: $ref: "#/components/schemas/Timestamp" required: - user - reactedAt required: - emoji - count - users EmojiReactions: type: array items: $ref: "#/components/schemas/EmojiReaction" UserContributor: type: object description: Contributor towards content. properties: updatedAt: $ref: "#/components/schemas/Timestamp" count: type: integer user: $ref: "#/components/schemas/User" required: - updatedAt - count - user TableCellTarget: type: object description: Details about the table cell this comment is attached to, if any. properties: record: type: string definition: type: string required: - record - definition Comment: allOf: - type: object properties: object: type: string description: Type of Object, always equals to "comment" enum: - comment id: description: Unique identifier for the comment. type: string postedBy: description: The user who posted the comment. $ref: "#/components/schemas/User" postedAt: description: When the comment was posted. $ref: "#/components/schemas/Timestamp" editedAt: description: Date when the comment was edited, if it has been edited. $ref: "#/components/schemas/Timestamp" reactions: description: Any emoji reactions to the comment. $ref: "#/components/schemas/EmojiReactions" replies: description: The number of replies to this comment. type: number repliers: description: The users who replied to this comment. type: array items: $ref: "#/components/schemas/UserContributor" body: description: The content of the comment. $ref: "#/components/schemas/Document" target: description: Information about the target of the comment. type: object properties: node: description: The node this comment is attached to. type: object properties: id: type: string required: - id tableCell: $ref: "#/components/schemas/TableCellTarget" changeRequest: description: The change request containing this comment, if the comment was made inside a change request. type: string review: description: The review containing this comment, if this comment was made as part of a review. type: string page: description: Information about the page, if this comment refers to a specific page. type: object properties: id: type: string description: The ID of the page required: - id space: description: The space containing this comment. type: string revision: description: The revision in which the target can be found in. type: string required: - space - revision urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the comment in the API format: uri required: - location permissions: type: object description: The set of permissions for the comment properties: view: type: boolean description: Can the user view the comment. edit: type: boolean description: Can the user edit the comment. reply: type: boolean description: Can the user react or send a reply to the comment. delete: type: boolean description: Can the user delete the comment. required: - view - edit - delete required: - object - id - replies - repliers - body - postedBy - postedAt - reactions - target - urls - permissions - oneOf: - type: object title: Resolved properties: status: description: Status of the comment. type: string enum: - resolved resolvedAt: description: If the comment has been resolved, the date at which it was resolved. If this field is not defined, the comment is not resolved. $ref: "#/components/schemas/Timestamp" resolvedBy: description: If the comment has been resolved, the user who resolved it. If this field is not defined, the comment is not resolved. $ref: "#/components/schemas/User" required: - status - resolvedAt - resolvedBy - type: object title: Open properties: status: description: Status of the comment. type: string enum: - open required: - status ChangeRequestReview: type: object properties: object: type: string description: Type of Object, always equals to "change-request-review" enum: - change-request-review id: type: string description: Unique identifier for the review. revision: type: string description: The revision this review was made against. reviewer: description: The user who performed the review. $ref: "#/components/schemas/User" requestedBy: description: The user who requested the review. If undefined, the review was left without a request. $ref: "#/components/schemas/User" status: description: The status of the review. $ref: "#/components/schemas/ChangeRequestReviewStatus" outdated: type: boolean description: Whether this review has been superseded by a newer review request or submission. comment: $ref: "#/components/schemas/Comment" createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the review in the API format: uri required: - location required: - object - id - revision - reviewer - status - outdated - createdAt - updatedAt - urls Team: type: object properties: object: type: string description: Type of Object, always equals to "team" enum: - team id: type: string description: Unique identifier for the team required: - object - id ChangeRequestRequestedReviewer: type: object allOf: - type: object properties: object: type: string description: Type of Object, always equals to "change-request-requested-reviewer" enum: - change-request-requested-reviewer revision: type: string description: The revision of the content when the request was made. requestedBy: description: The user who made the request. $ref: "#/components/schemas/User" createdAt: $ref: "#/components/schemas/Timestamp" required: - object - revision - requestedBy - createdAt - type: object oneOf: - type: object properties: kind: type: string enum: - user user: description: The user who was requested to review. $ref: "#/components/schemas/User" required: - kind - user - type: object properties: kind: type: string enum: - team team: description: The team who was requested to review. $ref: "#/components/schemas/Team" required: - kind - team PostCommentSchema: type: object properties: node: description: The node to which the comment is posted, if any. type: string page: description: The page to which the comment is posted, if any. type: string body: description: The content of the comment. $ref: "#/components/schemas/Document" tableCell: $ref: "#/components/schemas/TableCellTarget" required: - body UpdateCommentSchema: type: object properties: resolved: type: boolean description: Whether the comment is resolved or not. body: description: Content of the comment. $ref: "#/components/schemas/Document" addedReactions: type: array description: Reactions to add to the comment. items: type: string removedReactions: type: array description: Reactions to remove from the comment. items: type: string CommentReply: type: object properties: object: type: string description: Type of Object, always equals to "comment-reply" enum: - comment-reply id: type: string description: Unique identifier for the reply. postedBy: $ref: "#/components/schemas/User" postedAt: $ref: "#/components/schemas/Timestamp" editedAt: description: Date when the reply was edited, if it has been edited. $ref: "#/components/schemas/Timestamp" reactions: $ref: "#/components/schemas/EmojiReactions" body: $ref: "#/components/schemas/Document" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the comment reply in the API format: uri required: - location permissions: type: object description: The set of permissions for the comment reply properties: view: type: boolean description: Can the user view the comment reply. edit: type: boolean description: Can the user edit the comment reply. reply: type: boolean description: Can the user react or reply to the comment reply. delete: type: boolean description: Can the user delete the comment reply. required: - view - edit - delete required: - object - id - body - postedBy - postedAt - reactions - urls - permissions PostCommentReplySchema: type: object properties: body: description: The content of the comment. $ref: "#/components/schemas/Document" required: - body ChangeRequestUserContributor: allOf: - $ref: "#/components/schemas/UserContributor" - type: object properties: actionType: type: string enum: - edit - comment required: - actionType RevisionPageType: type: string enum: - document - group - link - computed ChangedRevisionPage: type: object properties: id: type: string type: $ref: "#/components/schemas/RevisionPageType" title: type: string path: type: string required: - id - type - title RevisionSemanticChangePageCreated: type: object properties: type: type: string enum: - page_created page: $ref: "#/components/schemas/ChangedRevisionPage" required: - type - page ChangeAttributeString: type: object properties: before: type: string after: type: string ChangeAttributeRevisionPageDocumentCover: type: object properties: before: $ref: "#/components/schemas/RevisionPageDocumentCover" after: $ref: "#/components/schemas/RevisionPageDocumentCover" RevisionPageLayoutPreset: type: string description: The core layout presets for a page. enum: - docs - editorial - landing RevisionPageLayout: oneOf: - $ref: "#/components/schemas/RevisionPageLayoutPreset" - $ref: "#/components/schemas/RevisionPageLayoutOptions" ChangeAttributeRevisionPageLayout: type: object properties: before: $ref: "#/components/schemas/RevisionPageLayout" after: $ref: "#/components/schemas/RevisionPageLayout" ChangeAttributeVariables: type: object properties: before: $ref: "#/components/schemas/Variables" after: $ref: "#/components/schemas/Variables" RevisionPageDocumentChangeAttributes: type: object minProperties: 1 properties: title: $ref: "#/components/schemas/ChangeAttributeString" description: $ref: "#/components/schemas/ChangeAttributeString" slug: $ref: "#/components/schemas/ChangeAttributeString" document: $ref: "#/components/schemas/ChangeAttributeString" cover: $ref: "#/components/schemas/ChangeAttributeRevisionPageDocumentCover" emoji: $ref: "#/components/schemas/ChangeAttributeString" layout: $ref: "#/components/schemas/ChangeAttributeRevisionPageLayout" variables: $ref: "#/components/schemas/ChangeAttributeVariables" RevisionPageGroupChangeAttributes: type: object minProperties: 1 properties: title: $ref: "#/components/schemas/ChangeAttributeString" emoji: $ref: "#/components/schemas/ChangeAttributeString" slug: $ref: "#/components/schemas/ChangeAttributeString" ChangeAttributeContentReference: type: object properties: before: $ref: "#/components/schemas/ContentRef" after: $ref: "#/components/schemas/ContentRef" RevisionPageLinkChangeAttributes: type: object minProperties: 1 properties: title: $ref: "#/components/schemas/ChangeAttributeString" emoji: $ref: "#/components/schemas/ChangeAttributeString" target: $ref: "#/components/schemas/ChangeAttributeContentReference" RevisionSemanticChangePageEdited: type: object properties: type: type: string enum: - page_edited page: $ref: "#/components/schemas/ChangedRevisionPage" attributes: oneOf: - $ref: "#/components/schemas/RevisionPageDocumentChangeAttributes" - $ref: "#/components/schemas/RevisionPageGroupChangeAttributes" - $ref: "#/components/schemas/RevisionPageLinkChangeAttributes" required: - type - page - attributes RevisionSemanticChangePageDeleted: type: object properties: type: type: string enum: - page_deleted page: $ref: "#/components/schemas/ChangedRevisionPage" required: - type - page RevisionSemanticChangePageMoved: type: object properties: type: type: string enum: - page_moved page: $ref: "#/components/schemas/ChangedRevisionPage" parent: type: object properties: before: $ref: "#/components/schemas/ChangedRevisionPage" after: $ref: "#/components/schemas/ChangedRevisionPage" required: - type - page - parent ChangedRevisionFile: type: object properties: id: type: string name: type: string contentType: type: string downloadURL: type: string required: - id - name - contentType - downloadURL RevisionSemanticChangeFileCreated: type: object properties: type: type: string enum: - file_created file: $ref: "#/components/schemas/ChangedRevisionFile" required: - type - file ChangeAttributeNumber: type: object properties: before: type: number after: type: number RevisionFileImageDimensions: type: object properties: height: type: number width: type: number required: - height - width ChangeAttributeRevisionFileImageDimensions: type: object properties: before: $ref: "#/components/schemas/RevisionFileImageDimensions" after: $ref: "#/components/schemas/RevisionFileImageDimensions" RevisionFileChangeAttributes: type: object minProperties: 1 properties: name: $ref: "#/components/schemas/ChangeAttributeString" downloadURL: $ref: "#/components/schemas/ChangeAttributeString" size: $ref: "#/components/schemas/ChangeAttributeNumber" contentType: $ref: "#/components/schemas/ChangeAttributeString" dimensions: $ref: "#/components/schemas/ChangeAttributeRevisionFileImageDimensions" RevisionSemanticChangeFileEdited: type: object properties: type: type: string enum: - file_edited file: $ref: "#/components/schemas/ChangedRevisionFile" attributes: $ref: "#/components/schemas/RevisionFileChangeAttributes" required: - type - file - attributes RevisionSemanticChangeFileDeleted: type: object properties: type: type: string enum: - file_deleted file: $ref: "#/components/schemas/ChangedRevisionFile" required: - type - file ChangeAttributeVariable: type: object properties: before: $ref: "#/components/schemas/VariableValue" after: $ref: "#/components/schemas/VariableValue" RevisionSemanticChangeVariablesEdited: type: object properties: type: type: string enum: - variables_edited variables: type: object additionalProperties: $ref: "#/components/schemas/ChangeAttributeVariable" required: - type - variables ChangedRevisionReusableContent: type: object properties: id: type: string title: type: string document: type: string required: - id - title RevisionSemanticChangeReusableContentCreated: type: object properties: type: type: string enum: - reusable_content_created reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" required: - type - reusableContent RevisionSemanticChangeReusableContentDeleted: type: object properties: type: type: string enum: - reusable_content_deleted reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" required: - type - reusableContent RevisionReusableContentChangeAttributes: type: object minProperties: 1 properties: title: $ref: "#/components/schemas/ChangeAttributeString" document: $ref: "#/components/schemas/ChangeAttributeString" RevisionSemanticChangeReusableContentEdited: type: object properties: type: type: string enum: - reusable_content_edited reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" attributes: $ref: "#/components/schemas/RevisionReusableContentChangeAttributes" required: - type - reusableContent - attributes ChangedRevisionTag: type: object properties: slug: type: string label: type: string required: - slug - label RevisionSemanticChangeTagCreated: type: object properties: type: type: string enum: - tag_created tag: $ref: "#/components/schemas/ChangedRevisionTag" required: - type - tag RevisionSemanticChangeTagDeleted: type: object properties: type: type: string enum: - tag_deleted tag: $ref: "#/components/schemas/ChangedRevisionTag" required: - type - tag RevisionTagChangeAttributes: type: object minProperties: 1 properties: label: $ref: "#/components/schemas/ChangeAttributeString" RevisionSemanticChangeTagEdited: type: object properties: type: type: string enum: - tag_edited tag: $ref: "#/components/schemas/ChangedRevisionTag" attributes: $ref: "#/components/schemas/RevisionTagChangeAttributes" required: - type - tag - attributes RevisionSemanticChange: oneOf: - $ref: "#/components/schemas/RevisionSemanticChangePageCreated" - $ref: "#/components/schemas/RevisionSemanticChangePageEdited" - $ref: "#/components/schemas/RevisionSemanticChangePageDeleted" - $ref: "#/components/schemas/RevisionSemanticChangePageMoved" - $ref: "#/components/schemas/RevisionSemanticChangeFileCreated" - $ref: "#/components/schemas/RevisionSemanticChangeFileEdited" - $ref: "#/components/schemas/RevisionSemanticChangeFileDeleted" - $ref: "#/components/schemas/RevisionSemanticChangeVariablesEdited" - $ref: "#/components/schemas/RevisionSemanticChangeReusableContentCreated" - $ref: "#/components/schemas/RevisionSemanticChangeReusableContentDeleted" - $ref: "#/components/schemas/RevisionSemanticChangeReusableContentEdited" - $ref: "#/components/schemas/RevisionSemanticChangeTagCreated" - $ref: "#/components/schemas/RevisionSemanticChangeTagDeleted" - $ref: "#/components/schemas/RevisionSemanticChangeTagEdited" RevisionSemanticChanges: type: object properties: mergedFrom: description: The change request object that initiated the changes in the case of a merge revision. $ref: "#/components/schemas/ChangeRequest" changes: type: array items: $ref: "#/components/schemas/RevisionSemanticChange" more: type: number description: How many changes were omitted because above the result limit required: - changes UpdateCommentReplySchema: type: object properties: body: description: Content of the comment. $ref: "#/components/schemas/Document" addedReactions: type: array description: Reactions to add to the comment. items: type: string removedReactions: type: array description: Reactions to remove from the comment. items: type: string 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 required: - object - id - role - user - disabled - joinedAt - sso - spaces - teams IntegrationTitle: type: string description: Title of the integration minLength: 2 maxLength: 30 IntegrationDescription: type: string description: Description of the integration maxLength: 100 IntegrationSummary: type: string description: Long form markdown summary of the integration maxLength: 2048 IntegrationTarget: type: string description: The target on which the integration can operate and needs to be configured for enum: - all - site - space - organization IntegrationVisibility: type: string enum: - public - private - unlisted IntegrationScope: type: string enum: - space:content:read - space:content:write - space:metadata:read - space:metadata:write - space:git:sync - page:feedback:read - site:metadata:read - site:views:read - site:script:inject - site:script:cookies - site:visitor:auth - site:adaptive:read - site:adaptive:write - conversations:ingest - openapi:read - openapi:write IntegrationScopes: type: array description: Permissions that should be granted to the integration items: $ref: "#/components/schemas/IntegrationScope" IntegrationCategory: type: string enum: - analytics - collaboration - content - gitsync - marketing - visitor-auth - other IntegrationCategories: type: array description: Categories for which the integration is listed in the marketplace items: $ref: "#/components/schemas/IntegrationCategory" IntegrationBlocks: type: array description: Custom blocks defined by this integration. items: $ref: "#/components/schemas/IntegrationBlock" IntegrationConfigurationComponent: type: object description: ContentKit component for configuration properties: componentId: type: string description: ID of the ContentKit component defined in the integration required: - componentId IntegrationContentSource: type: object description: Definition of a content source provided by the integration. properties: id: type: string description: Unique ID in the integration for the source. title: type: string description: Short descriptive title for the source. minLength: 2 maxLength: 40 description: type: string description: Long descriptive text for the source. minLength: 0 maxLength: 150 icon: type: string description: URL of the icon to represent this source. configuration: $ref: "#/components/schemas/IntegrationConfigurationComponent" required: - id - title - configuration IntegrationPropertyTitle: type: string description: Property title for an integration configuration property minLength: 2 maxLength: 50 IntegrationConfigurationSchema: type: object description: Schema for a configuration properties: properties: type: object additionalProperties: allOf: - type: object properties: title: $ref: "#/components/schemas/IntegrationPropertyTitle" description: type: string maxLength: 100 - oneOf: - type: object properties: type: type: string enum: - string default: type: string completion_url: description: If specified, this URL will be called to fetch suggestions for auto-completing the property. type: string enum: type: array description: If specified, only values from this array are allowed as inputs. items: type: string required: - type - type: object properties: type: type: string enum: - number default: type: number required: - type - type: object properties: type: type: string enum: - boolean default: type: boolean required: - type - type: object properties: type: type: string enum: - button callback_url: type: string button_text: type: string required: - type - callback_url - button_text required: type: array uniqueItems: true items: type: string required: - properties IntegrationConfiguration: oneOf: - $ref: "#/components/schemas/IntegrationConfigurationSchema" - $ref: "#/components/schemas/IntegrationConfigurationComponent" IntegrationConfigurations: type: object properties: account: $ref: "#/components/schemas/IntegrationConfiguration" space: $ref: "#/components/schemas/IntegrationConfiguration" site: $ref: "#/components/schemas/IntegrationConfiguration" IntegrationExternalLinks: type: array description: External urls configured by the developer of the integration maxItems: 5 items: type: object properties: url: $ref: "#/components/schemas/URL" label: type: string required: - url - label IntegrationContentSecurityPolicy: description: | Security policy to validate the content of the integrations scripts and Contentkit. Will be sent as headers when processing the script fetch event and the blocks fetch events. oneOf: - type: string - type: object properties: base-uri: type: string block-all-mixed-content: type: string child-src: type: string connect-src: type: string default-src: type: string font-src: type: string form-action: type: string frame-ancestors: type: string frame-src: type: string img-src: type: string manifest-src: type: string media-src: type: string navigate-to: type: string object-src: type: string plugin-types: type: string prefetch-src: type: string referrer: type: string report-to: type: string report-uri: type: string require-sri-for: type: string require-trusted-types-for: type: string sandbox: type: string script-src: type: string script-src-attr: type: string script-src-elem: type: string style-src: type: string style-src-attr: type: string style-src-elem: type: string trusted-types: type: string upgrade-insecure-requests: type: string worker-src: type: string Integration: type: object properties: object: type: string enum: - integration name: type: string description: Unique named identifier for the integration version: type: number description: Version of the integration title: $ref: "#/components/schemas/IntegrationTitle" description: $ref: "#/components/schemas/IntegrationDescription" summary: $ref: "#/components/schemas/IntegrationSummary" previewImages: type: array description: URLs of images to showcase the integration maxItems: 3 items: type: string target: $ref: "#/components/schemas/IntegrationTarget" verified: type: boolean description: If true, the integration has been verified by the GitBook team visibility: $ref: "#/components/schemas/IntegrationVisibility" scopes: $ref: "#/components/schemas/IntegrationScopes" categories: $ref: "#/components/schemas/IntegrationCategories" blocks: $ref: "#/components/schemas/IntegrationBlocks" contentSources: type: array items: $ref: "#/components/schemas/IntegrationContentSource" configurations: $ref: "#/components/schemas/IntegrationConfigurations" externalLinks: $ref: "#/components/schemas/IntegrationExternalLinks" owner: $ref: "#/components/schemas/Organization" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the integration in the API format: uri icon: type: string description: URL of the icon associated to the integration format: uri app: type: string description: URL of the integration in the application format: uri assets: type: string description: URL of the integration's assets. format: uri publicEndpoint: type: string description: Public HTTP endpoint for the integration format: uri required: - location - app - assets - publicEndpoint permissions: type: object description: The set of permissions for the integration properties: admin: type: boolean required: - admin contentSecurityPolicy: $ref: "#/components/schemas/IntegrationContentSecurityPolicy" required: - object - name - version - title - scopes - categories - visibility - target - verified - previewImages - externalLinks - owner - permissions - urls SpaceIntegrationBlocks: type: array items: type: object required: - name - blocks properties: name: type: string description: Unique named identifier for the integration blocks: type: array items: $ref: "#/components/schemas/IntegrationBlock" IntegrationSecrets: type: object description: Secrets stored on the integration and passed at runtime. properties: {} maxProperties: 20 additionalProperties: type: string PublishIntegration: type: object properties: runtime: type: string description: The runtime version to use for the integration. If not specified, the integration will use the default runtime. default: v1 enum: - v1 - v2 icon: type: string format: byte description: Base64 content of the icon title: $ref: "#/components/schemas/IntegrationTitle" description: $ref: "#/components/schemas/IntegrationDescription" summary: $ref: "#/components/schemas/IntegrationSummary" previewImages: type: array maxItems: 3 items: type: string format: byte description: Base64 content of the image visibility: $ref: "#/components/schemas/IntegrationVisibility" target: description: Allowed installation target for the integration. If not specified, the integration can be installed at `all` targets (org, spaces etc) $ref: "#/components/schemas/IntegrationTarget" scopes: $ref: "#/components/schemas/IntegrationScopes" categories: $ref: "#/components/schemas/IntegrationCategories" blocks: $ref: "#/components/schemas/IntegrationBlocks" contentSources: type: array items: $ref: "#/components/schemas/IntegrationContentSource" externalLinks: $ref: "#/components/schemas/IntegrationExternalLinks" configurations: $ref: "#/components/schemas/IntegrationConfigurations" script: type: string description: Content of the script to use organization: type: string description: The ID or subdomain of the organization under which the integration should be published secrets: $ref: "#/components/schemas/IntegrationSecrets" contentSecurityPolicy: $ref: "#/components/schemas/IntegrationContentSecurityPolicy" required: - organization - title - description - script - scopes IntegrationInstallationStatus: type: string enum: - active - pending - paused IntegrationInstallationSpaceSelection: type: string description: Describe whether all spaces have been selected or there's a selection involved enum: - all - selected IntegrationInstallationSiteSelection: type: string description: Describe whether all sites have been selected or there's a selection involved enum: - all - selected IntegrationInstallationConfiguration: type: object description: Configuration of the integration at the account level additionalProperties: true IntegrationInstallationExternalIds: type: array description: External IDs assigned by the integration. maxItems: 5 items: type: string OrganizationTarget: type: object required: - organization properties: organization: type: string IntegrationInstallationTarget: oneOf: - $ref: "#/components/schemas/OrganizationTarget" IntegrationNetwork: type: object description: Network configuration for the installation properties: proxy: type: boolean description: Whether the installation is proxied through the backend IntegrationInstallation: type: object description: Installation of an integration on an account properties: id: type: string status: $ref: "#/components/schemas/IntegrationInstallationStatus" space_selection: $ref: "#/components/schemas/IntegrationInstallationSpaceSelection" site_selection: $ref: "#/components/schemas/IntegrationInstallationSiteSelection" spaces: type: number description: Count of spaces, the installation is managing configuration: $ref: "#/components/schemas/IntegrationInstallationConfiguration" createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the installation in the API format: uri app: type: string description: URL of the integration's installation in the application format: uri publicEndpoint: type: string description: Public HTTP endpoint for the integration's installation format: uri required: - location - app - publicEndpoint externalIds: $ref: "#/components/schemas/IntegrationInstallationExternalIds" target: $ref: "#/components/schemas/IntegrationInstallationTarget" description: Target of the integration installation network: $ref: "#/components/schemas/IntegrationNetwork" description: Network configuration for the installation required: - id - status - space_selection - site_selection - spaces - configuration - urls - externalIds - target - createdAt - updatedAt BaseEvent: description: Common properties for all events. type: object properties: eventId: description: Unique identifier for the event. type: string type: description: Type of the event. type: string required: - eventId - type InstallationEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object description: Common properties for all events related to an installation properties: installationId: type: string description: ID of the integration installation required: - installationId InstallationSetupEvent: allOf: - $ref: "#/components/schemas/InstallationEvent" - type: object description: Event received when integration has been installed or updated. properties: type: type: string enum: - installation_setup status: $ref: "#/components/schemas/IntegrationInstallationStatus" previous: type: object description: The state of the installation at the account level before it was updated. properties: status: $ref: "#/components/schemas/IntegrationInstallationStatus" configuration: type: object description: The previous configuration of the installation at the account level. required: - status required: - type - status InstallationDeletedEvent: allOf: - $ref: "#/components/schemas/InstallationEvent" - type: object description: Event received when integration has been uninstalled from an organization. properties: type: type: string enum: - installation_deleted previous: type: object description: The state of the installation before it was deleted. properties: configuration: type: object description: The previous configuration of the installation. required: - type - previous SpaceEvent: allOf: - $ref: "#/components/schemas/InstallationEvent" - type: object description: Common properties for all events related to a specific space. properties: spaceId: type: string description: ID of the space required: - spaceId SpaceInstallationSetupEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event received when integration has been installed or updated on a space. properties: type: type: string enum: - space_installation_setup status: $ref: "#/components/schemas/IntegrationInstallationStatus" previous: type: object description: The state of the Space installation before it was updated. properties: status: $ref: "#/components/schemas/IntegrationInstallationStatus" configuration: type: object description: The previous configuration of the Space installation. required: - status required: - type - status SpaceInstallationDeletedEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event received when integration has been uninstalled from a space. properties: type: type: string enum: - space_installation_deleted previous: type: object description: The state of the Space installation before it was deleted. properties: configuration: type: object description: The previous configuration of the Space installation. required: - type - previous SiteEvent: allOf: - $ref: "#/components/schemas/InstallationEvent" - type: object description: Common properties for all events related to a specific site. properties: siteId: type: string description: ID of the site required: - siteId SiteInstallationSetupEvent: allOf: - $ref: "#/components/schemas/SiteEvent" - type: object description: Event received when integration has been installed or updated on a site. properties: type: type: string enum: - site_installation_setup status: $ref: "#/components/schemas/IntegrationInstallationStatus" previous: type: object description: The state of the site installation before it was updated. properties: status: $ref: "#/components/schemas/IntegrationInstallationStatus" configuration: type: object description: The previous configuration of the site installation. required: - status required: - type - status SiteInstallationDeletedEvent: allOf: - $ref: "#/components/schemas/SiteEvent" - type: object description: Event received when integration has been uninstalled from a site. properties: type: type: string enum: - site_installation_deleted previous: type: object description: The state of the site installation before it was deleted. properties: configuration: type: object description: The previous configuration of the site installation. required: - type - previous EventVisitor: type: object description: Analytics info on the GitBook's content visitor. properties: anonymousId: type: string description: GitBook's unique identifier of the visitor. cookies: type: object description: The visitors cookies. additionalProperties: type: string userAgent: type: string description: User-agent of the visitor. ip: type: string description: IP address of the visitor. language: type: string description: Language of the visitor. required: - anonymousId - cookies - userAgent - ip SiteViewEvent: allOf: - $ref: "#/components/schemas/SiteEvent" - type: object description: Event received when a page has been visited on a site. properties: type: type: string enum: - site_view spaceId: type: string description: Unique identifier of the visited space in the site. deprecated: true siteSpaceId: description: The site-space that was viewed type: string pageId: type: string description: Unique identifier of the visited page. visitor: $ref: "#/components/schemas/EventVisitor" url: type: string description: The GitBook content's URL visited (including URL params). referrer: type: string description: The URL of referrer that linked to the page. required: - type - visitor - url - referrer SpaceContentUpdatedEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event when the primary content of a space has been updated. properties: type: type: string enum: - space_content_updated revisionId: type: string description: Unique identifier of the new content revision required: - type - revisionId SpaceGitSyncCompletedEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event when a GitSync operation has been completed. properties: type: type: string enum: - space_gitsync_completed state: type: string enum: - success - failure revisionId: type: string description: Unique identifier of the new content revision commitId: type: string description: Unique identifier for the commit (sha) required: - type - state - revisionId - commitId SpaceGitSyncStartedEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event when a GitSync operation has been started. properties: type: type: string enum: - space_gitsync_started revisionId: type: string description: Unique identifier of the new content revision commitId: type: string description: Unique identifier for the commit (sha) required: - type - revisionId - commitId SpaceVisibilityUpdatedEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Event when the visibility of the space has been changed. properties: type: type: string enum: - space_visibility_updated previousVisibility: $ref: "#/components/schemas/ContentVisibility" visibility: $ref: "#/components/schemas/ContentVisibility" required: - type - previousVisibility - visibility TaskEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object description: Event representing a background task trigger for an integration. properties: type: type: string enum: - task task: type: object description: Payload associated with the integration task. required: - type - task FetchRequest: type: object properties: method: type: string enum: - post - get - put - delete url: type: string headers: type: object additionalProperties: type: string required: - method - url - headers FetchEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object description: Event representing an incoming HTTP request. properties: spaceId: type: string description: The space ID, if requests are specific to a single space siteId: type: string description: The site ID, if requests are specific to a single site installationId: type: string description: The installation ID, if requests are specific to a single installation auth: type: object properties: userId: type: string description: The user's ID. required: - userId type: type: string enum: - fetch request: $ref: "#/components/schemas/FetchRequest" required: - type - request FetchPublishedScriptEvent: allOf: - $ref: "#/components/schemas/SiteEvent" - type: object description: Common properties for all events related to fetching a published script from an installation properties: type: type: string enum: - fetch_published_script required: - type FetchVisitorAuthenticationEvent: allOf: - $ref: "#/components/schemas/SiteEvent" - type: object description: Common properties for all events related to authenticated access from an installation properties: type: type: string enum: - fetch_visitor_authentication location: type: string required: - type ContentKitContextBase: type: object description: Common properties for ContentKit context. properties: theme: type: string enum: - dark - light required: - theme ContentKitContextConfigurationAccount: allOf: - $ref: "#/components/schemas/ContentKitContextBase" - type: object description: Context while rendering in an account installation's configuration. properties: type: type: string enum: - configuration_account organizationId: type: string description: ID of the organization the account installation configuration is in. required: - type - organizationId ContentKitContextConfigurationSpace: allOf: - $ref: "#/components/schemas/ContentKitContextBase" - type: object description: Context while rendering in a space-installation's configuration. properties: type: type: string enum: - configuration_space spaceId: type: string description: ID of the space the space-installation configuration is in. required: - type - spaceId ContentKitContextConfigurationSite: allOf: - $ref: "#/components/schemas/ContentKitContextBase" - type: object description: Context while rendering in a site-installation's configuration. properties: type: type: string enum: - configuration_site siteId: type: string description: ID of the site the site-installation configuration is in. required: - type - siteId ContentKitContextConfigurationContentSource: allOf: - $ref: "#/components/schemas/ContentKitContextBase" - type: object description: Context while rendering the configuration flow of a content source. properties: type: type: string enum: - configuration_contentsource organizationId: type: string description: ID of the organization the content source installation configuration is in. spaceId: type: string description: Optional ID of the space the content source installation configuration is in. required: - type - organizationId ContentKitContextDocument: allOf: - $ref: "#/components/schemas/ContentKitContextBase" - type: object description: Context while rendering in a document. properties: type: type: string enum: - document spaceId: type: string description: ID of the space content the document is in. editable: type: boolean required: - type - spaceId - editable ContentKitContext: description: Object representing the context in which a ContentKit component is rendered. oneOf: - $ref: "#/components/schemas/ContentKitContextConfigurationAccount" - $ref: "#/components/schemas/ContentKitContextConfigurationSpace" - $ref: "#/components/schemas/ContentKitContextConfigurationSite" - $ref: "#/components/schemas/ContentKitContextConfigurationContentSource" - $ref: "#/components/schemas/ContentKitContextDocument" UIRenderEvent: allOf: - oneOf: - $ref: "#/components/schemas/SpaceEvent" - $ref: "#/components/schemas/SiteEvent" - $ref: "#/components/schemas/InstallationEvent" - type: object description: Event generated when rendering a UI properties: auth: type: object properties: userId: type: string description: The user's ID. required: - userId type: type: string enum: - ui_render componentId: type: string props: description: Properties to render the UI. type: object state: description: State of the UI. type: object context: $ref: "#/components/schemas/ContentKitContext" action: type: object required: - type - componentId - props - context ContentComputeEvent: allOf: - $ref: "#/components/schemas/SpaceEvent" - type: object description: Generic event when computing the content of a space properties: sourceId: type: string props: description: Properties passed to the rendering. $ref: "#/components/schemas/PlainObject" dependencies: description: Dependencies of the computation. type: object additionalProperties: $ref: "#/components/schemas/ComputedContentDependencyResolved" required: - sourceId - props - dependencies ContentComputeDocumentEvent: allOf: - $ref: "#/components/schemas/ContentComputeEvent" - type: object description: | Event generated when computing the document of a pages. The integration should respond with a `Document`. properties: type: type: string enum: - content_compute_document required: - type ContentComputeRevisionEvent: allOf: - $ref: "#/components/schemas/ContentComputeEvent" - type: object description: | Event generated when computing revision in a content. The integration should respond with an array of pages and files. properties: type: type: string enum: - content_compute_revision required: - type PageFeedbackRating: type: string enum: - bad - ok - good PageFeedbackEvent: allOf: - $ref: "#/components/schemas/BaseEvent" - type: object description: Event received when feedback has been submitted on a page. properties: type: type: string enum: - page_feedback installationId: type: string description: ID of the integration installation spaceId: type: string description: Unique identifier of the space in the site. deprecated: true siteId: type: string description: Unique identifier of the site. pageId: type: string description: Unique identifier of the page where feedback was submitted. feedback: type: object description: The feedback data submitted by the visitor. properties: rating: $ref: "#/components/schemas/PageFeedbackRating" comment: type: string description: Optional comment provided with the feedback. minLength: 1 maxLength: 512 required: - rating visitor: $ref: "#/components/schemas/EventVisitor" url: type: string description: The GitBook content's URL where feedback was submitted. referrer: type: string description: The URL of referrer that linked to the page. required: - type - installationId - siteId - feedback - visitor - url - referrer Event: description: Any event that can be received from GitBook. oneOf: - $ref: "#/components/schemas/InstallationSetupEvent" - $ref: "#/components/schemas/InstallationDeletedEvent" - $ref: "#/components/schemas/SpaceInstallationSetupEvent" - $ref: "#/components/schemas/SpaceInstallationDeletedEvent" - $ref: "#/components/schemas/SiteInstallationSetupEvent" - $ref: "#/components/schemas/SiteInstallationDeletedEvent" - $ref: "#/components/schemas/SiteViewEvent" - $ref: "#/components/schemas/SpaceContentUpdatedEvent" - $ref: "#/components/schemas/SpaceGitSyncCompletedEvent" - $ref: "#/components/schemas/SpaceGitSyncStartedEvent" - $ref: "#/components/schemas/SpaceVisibilityUpdatedEvent" - $ref: "#/components/schemas/TaskEvent" - $ref: "#/components/schemas/FetchEvent" - $ref: "#/components/schemas/FetchPublishedScriptEvent" - $ref: "#/components/schemas/FetchVisitorAuthenticationEvent" - $ref: "#/components/schemas/UIRenderEvent" - $ref: "#/components/schemas/ContentComputeDocumentEvent" - $ref: "#/components/schemas/ContentComputeRevisionEvent" - $ref: "#/components/schemas/PageFeedbackEvent" discriminator: propertyName: type IntegrationEvent: type: object properties: id: type: string description: Unique ID of the event. integrationId: type: string description: Unique ID of the integration. installationId: type: string description: Unique ID of the integration installation. createdAt: $ref: "#/components/schemas/Timestamp" payload: $ref: "#/components/schemas/Event" status: type: string description: Status of the event. enum: - success - failed required: - id - integrationId - createdAt - payload - status IntegrationEventLog: type: object properties: message: description: The message of the log entry. type: string timestamp: $ref: "#/components/schemas/Timestamp" level: description: The level of the log entry. type: string enum: - debug - info - warn - error IntegrationEventTrace: type: object required: - logs properties: logs: type: array items: $ref: "#/components/schemas/IntegrationEventLog" IntegrationContentInstallationBase: type: object description: Base properties of an installation of an integration on a site or space. properties: integration: description: Unique name identifier of the integration type: string installation: description: ID of the integration installation type: string status: $ref: "#/components/schemas/IntegrationInstallationStatus" configuration: description: Configuration of the integration for this site type: object externalIds: $ref: "#/components/schemas/IntegrationInstallationExternalIds" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the integration's installation in the API format: uri publicEndpoint: type: string description: Public HTTP endpoint for the integration's installation format: uri required: - location - publicEndpoint required: - integration - installation - status - configuration - externalIds - urls IntegrationSpaceInstallation: allOf: - $ref: "#/components/schemas/IntegrationContentInstallationBase" - type: object properties: space: description: The space the integration is installed on. Using the string value is deprecated in favor of space.id oneOf: - type: string - $ref: "#/components/schemas/Space" required: - space SiteType: type: string description: The type of the site enum: - basic - premium - ultimate - sponsored - legacy-basic - legacy-premium SiteTitle: type: string description: Title of the site minLength: 2 maxLength: 128 CustomizationThemedURL: type: object properties: light: $ref: "#/components/schemas/URL" dark: $ref: "#/components/schemas/URL" required: - light - dark CustomizationFavicon: oneOf: - type: object properties: icon: $ref: "#/components/schemas/CustomizationThemedURL" required: - icon - type: object properties: emoji: $ref: "#/components/schemas/Emoji" required: - emoji - type: object properties: {} additionalProperties: false SiteHostname: type: string description: Custom hostname for the site, for e.g. docs.mycompany.com pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?[.]){2,}[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$ maxLength: 512 SiteBasename: type: string description: Basename for the site. For e.g. api minLength: 1 maxLength: 100 SiteProxyOrigin: type: string description: Proxy URL for the site, for e.g. company.com/docs or www.company.com/developer/docs etc. pattern: ^([\w-]+\.)*[\w-]+\.[a-zA-Z]{2,}(\/[\w-]+)+$ maxLength: 512 SiteProxy: type: object properties: origin: $ref: "#/components/schemas/SiteProxyOrigin" target: type: string description: The target URL to which the requests at the origin URL should be proxied to. required: - origin - target SiteVisibility: type: string description: | The visibility setting of the site determines the audience of the site. * `public`: Anyone can access the site, and the site is indexed by search engines. * `unlisted`: Anyone can access the site, and the site is not indexed by search engines * `share-link`: Anyone with a secret token in the url can access the site. * `visitor-auth`: Anyone authenticated through a JWT token can access the site. enum: - public - unlisted - share-link - visitor-auth SitePermissionsModel: type: string description: Permissions resolution mode for the site. enum: - legacy - site SiteAdaptiveContent: type: object properties: enabled: type: boolean description: Whether adaptive content should be enabled on the site. required: - enabled SiteAdsTopic: type: string description: Topic of the content enum: - webdev - crypto SiteAds: oneOf: - type: object required: - status - submittable properties: status: type: string enum: - pending submittable: type: boolean description: True if the user can submit the site for review. - type: object required: - status - topic properties: status: type: string enum: - in-review topic: $ref: "#/components/schemas/SiteAdsTopic" - type: object required: - status properties: status: type: string enum: - rejected reason: type: string description: Reason for the rejection - type: object required: - status - topic - zoneId properties: status: type: string enum: - live - disabled topic: $ref: "#/components/schemas/SiteAdsTopic" zoneId: type: string description: The ad network zone ID SiteFeatureKey: type: string description: The site feature identifier enum: - sites-adaptive-content - sites-advanced-customization - sites-advanced-insights - sites-ads - sites-ai-search - sites-ai-assistant - sites-connections - sites-channels - sites-embed - sites-api-playground - sites-basic-customization - sites-custom-domain - sites-custom-fonts - sites-custom-subdirectory - sites-full-text-search - sites-multivariant-site - sites-no-custom-domain - sites-page-feedback - sites-page-traffic-insights - sites-pdf-export - sites-preview-deployments - sites-public-visibility - sites-redirects - sites-search-insights - sites-sections - sites-seo - sites-share-links - sites-unlisted-visibility - sites-user-contribution - sites-visitor-authentication - sites-visitors SiteCustomizationFeature: type: string description: A list of all premium customizations. enum: - header-logo - header-primary-link - theme-preset - premium-fonts - custom-icons - footer-logo - footer-links - footer-copyright - semantic-colors SiteFeature: type: object description: A site feature and the plan it is available on. properties: id: $ref: "#/components/schemas/SiteFeatureKey" plan: $ref: "#/components/schemas/SiteType" frozen: description: A frozen feature is still enabled but cannot be changed or modified. type: boolean customizations: description: A list of the actual advanced customizations used (only applicable for sites-advanced-customization) type: array items: $ref: "#/components/schemas/SiteCustomizationFeature" required: - id - plan - frozen Site: type: object properties: object: type: string enum: - site id: type: string description: Unique identifier of the site type: $ref: "#/components/schemas/SiteType" appliedType: $ref: "#/components/schemas/SiteType" description: The currently applied type of the site. For example, frozen sites will have this set to Basic. title: $ref: "#/components/schemas/SiteTitle" icon: oneOf: - $ref: "#/components/schemas/CustomizationFavicon" - type: "null" hostname: $ref: "#/components/schemas/SiteHostname" basename: $ref: "#/components/schemas/SiteBasename" proxy: $ref: "#/components/schemas/SiteProxy" visibility: $ref: "#/components/schemas/SiteVisibility" permissionsModel: $ref: "#/components/schemas/SitePermissionsModel" defaultLevel: $ref: "#/components/schemas/DefaultLevel" published: type: boolean description: Whether the site is live or not. If true, the site is accessible to the audience defined by the visibility setting. siteSpaces: type: number createdAt: type: string format: date-time adaptiveContent: $ref: "#/components/schemas/SiteAdaptiveContent" ads: $ref: "#/components/schemas/SiteAds" features: description: | A list of all premium features enabled on this site. For each feature we list the plan they belong to and whether the feature is frozen. A frozen feature is still enabled but cannot be changed or modified. type: array items: $ref: "#/components/schemas/SiteFeature" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the site in the API format: uri app: type: string description: URL of the site in the application format: uri published: type: string description: URL of the published version of the site. Only defined when site is published. format: uri preview: type: string description: URL of the preview version of the site. format: uri login: type: string description: | URL of the login endpoint for visitors to authenticate with the site auth backend. format: uri required: - app - location - preview required: - object - id - type - appliedType - title - visibility - permissionsModel - defaultLevel - published - createdAt - siteSpaces - features - urls IntegrationSiteInstallation: allOf: - $ref: "#/components/schemas/IntegrationContentInstallationBase" - type: object properties: site: description: The site the integration is installed on. Using the string value is deprecated in favor of site.id oneOf: - type: string - $ref: "#/components/schemas/Site" required: - site ContentKitIcon: type: string enum: - close - edit - github - gitlab - maximize - email - settings - search - delete - star - warning - link - link-external - eye - eye-off - lock - check - check-circle ContentKitConfirm: type: object description: A confirm object that defines an optional confirmation dialog after the input is clicked. properties: title: type: string description: A text value that defines the dialog's title. maxLength: 100 text: type: string description: A text value that defines the explanatory text that appears in the confirm dialog. maxLength: 300 confirm: type: string description: A text value to define the text of the button that confirms the action. maxLength: 30 style: type: string enum: - primary - danger required: - title - text - confirm ContentKitButton: type: object description: Pressable button triggering an action. properties: type: type: string enum: - button style: type: string enum: - primary - secondary - danger onPress: $ref: "#/components/schemas/ContentKitAction" icon: $ref: "#/components/schemas/ContentKitIcon" trailingIcon: $ref: "#/components/schemas/ContentKitIcon" label: type: string tooltip: type: string confirm: $ref: "#/components/schemas/ContentKitConfirm" disabled: type: boolean required: - type - onPress ContentKitTextInput: type: object description: Text input to prompt the user. properties: type: type: string enum: - textinput disabled: type: boolean state: description: State binding. The value of the input will be stored as a property in the state named after this ID. type: string initialValue: description: Text value to initialize the input with. type: string placeholder: description: Text that appears in the form control when it has no value set type: string multiline: type: boolean inputType: type: string enum: - text - password - email default: text required: - type - state ContentKitDescendantElement: description: Any element that can be used as children. oneOf: - $ref: "#/components/schemas/ContentKitButton" - $ref: "#/components/schemas/ContentKitTextInput" - $ref: "#/components/schemas/ContentKitHStack" - $ref: "#/components/schemas/ContentKitVStack" - $ref: "#/components/schemas/ContentKitBox" - $ref: "#/components/schemas/ContentKitDivider" - $ref: "#/components/schemas/ContentKitWebFrame" - $ref: "#/components/schemas/ContentKitCodeBlock" - $ref: "#/components/schemas/ContentKitMarkdown" - $ref: "#/components/schemas/ContentKitCard" - $ref: "#/components/schemas/ContentKitImage" - $ref: "#/components/schemas/ContentKitInput" - $ref: "#/components/schemas/ContentKitSelect" - $ref: "#/components/schemas/ContentKitSwitch" - $ref: "#/components/schemas/ContentKitCheckbox" - $ref: "#/components/schemas/ContentKitRadio" - $ref: "#/components/schemas/ContentKitText" - $ref: "#/components/schemas/ContentKitHint" - $ref: "#/components/schemas/ContentKitLink" - $ref: "#/components/schemas/ContentKitStepperStep" discriminator: propertyName: type ContentKitHStack: type: object description: Horizontal stack of boxes. properties: type: type: string enum: - hstack align: type: string default: start enum: - start - center - end children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" required: - type - children ContentKitVStack: type: object description: Vertical stack of boxes. properties: type: type: string enum: - vstack align: type: string default: start enum: - start - center - end children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" required: - type - children ContentKitBox: type: object properties: type: type: string enum: - box grow: description: specifies how much of the remaining space in the container should be assigned to the element type: number children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" required: - type - children ContentKitDivider: type: object description: Divider between 2 boxes in a stack. properties: type: type: string enum: - divider size: type: string enum: - small - medium - large required: - type ContentKitDynamicBinding: type: object description: Binding between a property and a state value. properties: $state: type: string description: Key in the state required: - $state ContentKitWebFrame: type: object description: Frame for a webpage properties: type: type: string enum: - webframe aspectRatio: type: number description: Ratio between width and height. Used to size the webframe. source: type: object description: Content to load in the frame. properties: url: type: string required: - url buttons: type: array description: Controls button shown as an overlay in a corner of the frame. items: $ref: "#/components/schemas/ContentKitButton" data: type: object description: Data to communicated to the webframe's content. Each state update will cause the webframe to receive a message. additionalProperties: oneOf: - type: string - $ref: "#/components/schemas/ContentKitDynamicBinding" required: - type - source ContentKitCodeBlock: type: object description: Code block with syntax highlighting properties: type: type: string enum: - codeblock content: oneOf: - $ref: "#/components/schemas/ContentKitDynamicBinding" - type: string description: Code content to display syntax: description: "Syntax to use for highlighting (ex: javascript, python)" type: string lineNumbers: oneOf: - type: boolean - type: number description: Line number to start at. buttons: type: array description: Controls button shown as an overlay in a corner of the code block. items: $ref: "#/components/schemas/ContentKitButton" state: description: State binding when editable. The value of the input will be stored as a property in the state named after this ID. type: string onContentChange: $ref: "#/components/schemas/ContentKitAction" header: type: array description: Header displayed before the code lines items: $ref: "#/components/schemas/ContentKitDescendantElement" footer: type: array description: Footer displayed after the code lines items: $ref: "#/components/schemas/ContentKitDescendantElement" required: - type - content ContentKitMarkdown: type: object description: Block with rich text formatting of a markdown content. properties: type: type: string enum: - markdown content: oneOf: - $ref: "#/components/schemas/ContentKitDynamicBinding" - type: string description: Markdown content to display required: - type - content ContentKitText: type: object description: Low level text element. properties: type: type: string enum: - text style: type: string enum: - bold - italic - code - strikethrough children: oneOf: - type: string - type: array items: oneOf: - type: string - $ref: "#/components/schemas/ContentKitText" - $ref: "#/components/schemas/ContentKitLink" required: - type - children ContentKitURL: type: object description: Specification for an URL in ContentKit. properties: host: type: string description: Hostname of the URL along with the port number if required. example: api.example.com pathname: type: string description: Path of the URL prefixed with a `/`. example: /v1/options query: type: object additionalProperties: oneOf: - type: string - $ref: "#/components/schemas/ContentKitDynamicBinding" required: - host - pathname ContentKitLink: type: object properties: type: type: string enum: - link target: type: object properties: url: oneOf: - type: string - $ref: "#/components/schemas/ContentKitURL" required: - url children: oneOf: - type: string - type: array items: type: string required: - type - target - children ContentKitImage: type: object properties: type: type: string enum: - image source: type: object properties: url: type: string format: uri required: - url aspectRatio: type: number required: - type - source - aspectRatio ContentKitInlineElement: description: Any element that is inline. oneOf: - $ref: "#/components/schemas/ContentKitText" - $ref: "#/components/schemas/ContentKitImage" - $ref: "#/components/schemas/ContentKitLink" discriminator: propertyName: type ContentKitCard: type: object properties: type: type: string enum: - card title: type: string hint: oneOf: - type: string - type: array items: $ref: "#/components/schemas/ContentKitInlineElement" icon: oneOf: - $ref: "#/components/schemas/ContentKitIcon" - $ref: "#/components/schemas/ContentKitImage" onPress: $ref: "#/components/schemas/ContentKitAction" children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" buttons: type: array description: Buttons displayed in the top right corner of the card. items: $ref: "#/components/schemas/ContentKitButton" required: - type ContentKitBuiltInSource: type: object description: Built-in sources that can be used to provide a ContentKitSelect. properties: source: type: string enum: - openapi required: - source ContentKitSelectOption: type: object description: An individual option in a select element properties: id: type: string label: type: string icon: oneOf: - $ref: "#/components/schemas/ContentKitIcon" - $ref: "#/components/schemas/ContentKitImage" required: - id - label ContentKitSelect: type: object description: Creates a drop down menu with a list of options for a user to choose. properties: type: type: string enum: - select disabled: type: boolean state: description: State binding. The value of the input will be stored as a property in the state named after this ID. type: string initialValue: description: Value to initialize the select with. oneOf: - type: string - type: array items: type: string onValueChange: $ref: "#/components/schemas/ContentKitAction" placeholder: description: Text that appears in the form control when it has no value set type: string multiple: description: Should the select accept the selection of multiple options. If true, the state will be an array. type: boolean acceptInput: description: Should the filter input be allowed to be selected as an option. type: boolean options: description: Options to be displayed in the select. oneOf: - $ref: "#/components/schemas/ContentKitBuiltInSource" - type: array description: Static list of options items: $ref: "#/components/schemas/ContentKitSelectOption" - type: object properties: url: oneOf: - type: string description: External source of options. The URL should respond with an array of options. - $ref: "#/components/schemas/ContentKitURL" required: - url required: - type - state - options ContentKitSwitch: type: object description: Renders a boolean input. properties: type: type: string enum: - switch disabled: type: boolean state: description: State binding. The value of the input will be stored as a property in the state named after this ID. type: string initialValue: description: Value to initialize the switch with. type: boolean onValueChange: $ref: "#/components/schemas/ContentKitAction" confirm: $ref: "#/components/schemas/ContentKitConfirm" required: - type - state ContentKitRadio: type: object properties: type: type: string enum: - radio disabled: type: boolean state: description: State binding. The value of the input will be stored as a property in the state named after this ID. type: string value: description: Value to store in th state when the checkbox is selected. oneOf: - type: string - type: number confirm: $ref: "#/components/schemas/ContentKitConfirm" required: - type - state - value ContentKitCheckbox: type: object properties: type: type: string enum: - checkbox state: description: State binding. The value of the input will be stored as a property in the state named after this ID. type: string value: description: Value to store in a state array when the checkbox is selected. oneOf: - type: string - type: number confirm: $ref: "#/components/schemas/ContentKitConfirm" required: - type - state - value ContentKitInput: type: object description: Field for an input. properties: type: type: string enum: - input label: type: string description: Text label displayed next to the input. hint: oneOf: - type: string - $ref: "#/components/schemas/ContentKitInlineElement" element: oneOf: - $ref: "#/components/schemas/ContentKitTextInput" - $ref: "#/components/schemas/ContentKitSelect" - $ref: "#/components/schemas/ContentKitSwitch" - $ref: "#/components/schemas/ContentKitRadio" - $ref: "#/components/schemas/ContentKitCheckbox" - $ref: "#/components/schemas/ContentKitButton" - $ref: "#/components/schemas/ContentKitCodeBlock" required: - type - label - element ContentKitHint: type: object description: Element used to contextualize other elements or info. properties: type: type: string enum: - hint children: type: array items: $ref: "#/components/schemas/ContentKitInlineElement" required: - type - children ContentKitStepperStep: type: object properties: type: type: string enum: - step id: description: unique identifier for the step type: string title: description: title of the step type: string maxLength: 50 next: description: indicates if the user can progress to the next step based on some internal validation or condition type: boolean default: false children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" minItems: 1 required: - type - id - children ContentKitBlockControl: type: object description: Control menu item displayed for the block. properties: icon: $ref: "#/components/schemas/ContentKitIcon" label: type: string onPress: $ref: "#/components/schemas/ContentKitAction" confirm: $ref: "#/components/schemas/ContentKitConfirm" required: - label - onPress ContentKitBlock: type: object description: Higher level element to represent a custom block. properties: type: type: string enum: - block children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" controls: type: array items: oneOf: - $ref: "#/components/schemas/ContentKitBlockControl" - type: array items: $ref: "#/components/schemas/ContentKitBlockControl" required: - type - children ContentKitModal: type: object description: Overlay modal. properties: type: type: string enum: - modal title: type: string subtitle: type: array items: $ref: "#/components/schemas/ContentKitInlineElement" size: type: string enum: - medium - xlarge - fullscreen returnValue: description: Data passed back to the parent view when the modal is closed. These data are accessible in the "@ui.modal.close" type: object children: type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" submit: $ref: "#/components/schemas/ContentKitButton" required: - type - children ContentKitStepper: type: object properties: type: type: string enum: - stepper activeStep: type: string description: id of the currently active step onStepChange: $ref: "#/components/schemas/ContentKitAction" onComplete: $ref: "#/components/schemas/ContentKitAction" children: type: array items: $ref: "#/components/schemas/ContentKitStepperStep" minItems: 1 required: - type - activeStep - onStepChange - onComplete - children ContentKitConfiguration: type: object description: Higher level element to define a configuration block. Does not add any UI elements or wrappers. Must be used as a top level element for any configuration component. properties: type: type: string enum: - configuration children: oneOf: - type: array items: $ref: "#/components/schemas/ContentKitStepper" minItems: 1 maxItems: 1 - type: array items: $ref: "#/components/schemas/ContentKitDescendantElement" minItems: 1 required: - type - children ContentKitRootElement: description: Element used as root oneOf: - $ref: "#/components/schemas/ContentKitBlock" - $ref: "#/components/schemas/ContentKitModal" - $ref: "#/components/schemas/ContentKitConfiguration" discriminator: propertyName: type ContentKitRenderOutputElement: type: object description: Output of type element in the lifecycle of the component. properties: type: type: string enum: - element element: $ref: "#/components/schemas/ContentKitRootElement" state: type: object props: $ref: "#/components/schemas/PlainObject" required: - element - state - props ContentKitRenderOutputComplete: type: object description: Output of completed lifecycle of the component. properties: type: type: string enum: - complete returnValue: type: object required: - type ContentKitRenderOutput: type: object description: Output of the integration when rendering a UI. oneOf: - $ref: "#/components/schemas/ContentKitRenderOutputElement" - $ref: "#/components/schemas/ContentKitRenderOutputComplete" RenderIntegrationUI: type: object properties: componentId: type: string description: ID of the component to render in the integration. props: description: Current properties of the UI. $ref: "#/components/schemas/PlainObject" state: type: object description: Current local state of the UI. context: $ref: "#/components/schemas/ContentKitContext" action: $ref: "#/components/schemas/ContentKitAction" required: - componentId - props - context UpdateIntegrationInstallation: type: object properties: externalIds: $ref: "#/components/schemas/IntegrationInstallationExternalIds" configuration: $ref: "#/components/schemas/IntegrationInstallationConfiguration" space_selection: $ref: "#/components/schemas/IntegrationInstallationSpaceSelection" site_selection: $ref: "#/components/schemas/IntegrationInstallationSiteSelection" UpdateIntegrationSpaceInstallation: type: object properties: externalIds: $ref: "#/components/schemas/IntegrationInstallationExternalIds" configuration: $ref: "#/components/schemas/IntegrationInstallationConfiguration" UpdateIntegrationSiteInstallation: type: object properties: externalIds: $ref: "#/components/schemas/IntegrationInstallationExternalIds" configuration: $ref: "#/components/schemas/IntegrationInstallationConfiguration" CreateOrganization: type: object properties: title: $ref: "#/components/schemas/OrganizationTitle" emailDomains: $ref: "#/components/schemas/OrganizationEmailDomains" type: $ref: "#/components/schemas/OrganizationType" useCase: $ref: "#/components/schemas/OrganizationUseCase" required: - title SiteSectionTitle: type: string description: Title of the site section minLength: 2 maxLength: 128 LocalizedString128: type: object description: Localized string value with a 128 character limit, keyed by locale. Contains overrides for non-default languages only. additionalProperties: type: string maxLength: 128 propertyNames: $ref: "#/components/schemas/TranslationLanguage" SiteSectionDescription: type: string description: Description of the site section minLength: 0 maxLength: 256 LocalizedString256: type: object description: Localized string value with a 256 character limit, keyed by locale. Contains overrides for non-default languages only. additionalProperties: type: string maxLength: 256 propertyNames: $ref: "#/components/schemas/TranslationLanguage" SiteSectionPath: type: string description: Path to the section on the site minLength: 1 maxLength: 100 SiteSpacePath: type: string description: Path to the space on the site minLength: 1 maxLength: 100 SiteSpace: type: object properties: object: type: string description: The object type, which is always "site-space" enum: - site-space id: type: string description: Unique identifier of the site-space path: $ref: "#/components/schemas/SiteSpacePath" section: type: string description: ID of the section the space belongs to in the site space: $ref: "#/components/schemas/Space" title: type: string localizedTitle: $ref: "#/components/schemas/LocalizedString128" default: type: boolean description: Whether this is the default space for the site condition: description: Conditional expression used to evaluate whether the site space should be shown to the site's visitor. $ref: "#/components/schemas/Expression" draft: type: boolean description: Whether the site space is draft and not live. hasAdvancedCustomizationFeature: type: boolean description: Whether the space has advanced customization feature enabled urls: type: object description: URLs associated with the object properties: published: type: string description: URL of the published version of the site-space. Only defined when site is published. format: uri hidden: type: boolean description: Whether the site space is hidden. If true, the site space will not be shown in the site's navigation. required: - object - id - space - title - path - draft - urls SiteSection: type: object properties: object: type: string description: The object type, which is always "site-section" enum: - site-section id: type: string description: Unique identifier of the site section title: $ref: "#/components/schemas/SiteSectionTitle" localizedTitle: $ref: "#/components/schemas/LocalizedString128" description: $ref: "#/components/schemas/SiteSectionDescription" localizedDescription: $ref: "#/components/schemas/LocalizedString256" default: type: boolean description: Whether this is the default section for the site draft: type: boolean description: Whether the site section is draft and not live. path: $ref: "#/components/schemas/SiteSectionPath" condition: description: Conditional expression used to evaluate whether the site section should be shown to the site's visitor. $ref: "#/components/schemas/Expression" sectionGroup: type: string description: ID of the section group the section belongs to in the site siteSpaces: type: array items: $ref: "#/components/schemas/SiteSpace" urls: type: object description: URLs associated with the object properties: published: type: string description: URL of the published version of the site section. Only defined when site is published. format: uri icon: $ref: "#/components/schemas/Icon" required: - object - id - title - path - draft - siteSpaces - urls SiteSectionGroupTitle: type: string description: Title of the site section group minLength: 1 maxLength: 100 SiteSectionGroup: type: object properties: object: type: string description: The object type, which is always "site-section-group" enum: - site-section-group id: type: string description: Unique identifier of the site section group title: $ref: "#/components/schemas/SiteSectionGroupTitle" localizedTitle: $ref: "#/components/schemas/LocalizedString128" sections: type: array deprecated: true description: List of site section ids that are members of the group. Use `children` instead. items: $ref: "#/components/schemas/SiteSection" sectionGroup: type: string description: ID of the parent section group this group belongs to draft: type: boolean description: Whether the site section group is draft and not live. children: type: array description: List of all child sections and groups nested under this group items: oneOf: - $ref: "#/components/schemas/SiteSection" - $ref: "#/components/schemas/SiteSectionGroup" icon: $ref: "#/components/schemas/Icon" required: - object - id - title - draft - sections - children SiteStructure: oneOf: - type: object properties: type: type: string enum: - sections structure: type: array items: oneOf: - $ref: "#/components/schemas/SiteSection" - $ref: "#/components/schemas/SiteSectionGroup" required: - type - structure - type: object properties: type: type: string enum: - siteSpaces structure: type: array items: $ref: "#/components/schemas/SiteSpace" required: - type - structure OrganizationAllSite: type: object properties: site: $ref: "#/components/schemas/Site" structure: $ref: "#/components/schemas/SiteStructure" required: - site - structure OrganizationAllCollection: type: object properties: collection: $ref: "#/components/schemas/Collection" content: type: array items: oneOf: - $ref: "#/components/schemas/OrganizationAllCollection" - $ref: "#/components/schemas/OrganizationAllSpace" required: - collection - content OrganizationAllSpace: type: object properties: space: $ref: "#/components/schemas/Space" required: - space OrganizationAllContent: type: object properties: sites: type: array items: $ref: "#/components/schemas/OrganizationAllSite" spaces: type: array items: oneOf: - $ref: "#/components/schemas/OrganizationAllCollection" - $ref: "#/components/schemas/OrganizationAllSpace" deletedSpaces: description: List of soft-deleted spaces. type: array items: $ref: "#/components/schemas/OrganizationAllSpace" required: - sites - spaces - deletedSpaces MemberContentPermission: type: object description: Permission of a member in a content. properties: permission: $ref: "#/components/schemas/MemberRole" space: $ref: "#/components/schemas/Space" required: - permission - space 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 TeamMember: type: object properties: role: $ref: "#/components/schemas/TeamMemberRole" required: - role 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 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. Email: type: string format: email description: User email example: contact@gitbook.com 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 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 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 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 CreateInviteToOrganization: type: object properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" description: The role of the member in the organization required: - role 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 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 CreateOrganizationInvite: oneOf: - $ref: "#/components/schemas/CreateInviteToOrganization" - $ref: "#/components/schemas/CreateInviteToSpace" - $ref: "#/components/schemas/CreateInviteToCollection" OrganizationInviteLink: type: object description: An invite link created in an organization oneOf: - $ref: "#/components/schemas/InviteLinkToOrganization" - $ref: "#/components/schemas/InviteLinkToSpace" - $ref: "#/components/schemas/InviteLinkToCollection" SubscriptionChanges: type: object description: Changes to apply during a subscription upgrade or downgrade properties: removeMembers: description: A list of member identifiers to be removed type: array items: type: string updateSites: description: | A list of site updates to be applied before upgrading. If a site is not present in this list, it'll be upgraded to whichever type matches its features and its published status will be unchanged. When downgrading to a lower type all relevant paid features will be disabled before applying the new type. type: array items: oneOf: - type: object properties: id: description: The site identifier type: string type: description: The site type to migrate to $ref: "#/components/schemas/SiteType" additionalProperties: false required: - id - type - type: object properties: id: description: The site identifier type: string isPublished: description: Can be set to `false` or `true` to either unpublish or publish a site type: boolean additionalProperties: false required: - id - isPublished - type: object properties: id: description: The site identifier type: string type: description: The site type to migrate to $ref: "#/components/schemas/SiteType" isPublished: description: Can be set to `false` or `true` to either unpublish or publish a site type: boolean additionalProperties: false required: - id - type - isPublished required: - removeMembers - updateSites BillingCoupon: type: string description: Coupon or promotion code to apply to billing operations. minLength: 1 maxLength: 500 BillingMeter: type: string description: Identifier of a billing meter enum: - ai_responses - ai_agent_responses - translation_words UpgradeOrganizationBilling: type: object properties: product: $ref: "#/components/schemas/BillingProduct" interval: $ref: "#/components/schemas/BillingInterval" changes: $ref: "#/components/schemas/SubscriptionChanges" reason: type: string description: Reason that triggered the billing upgrade coupon: $ref: "#/components/schemas/BillingCoupon" description: Coupon or promotion code to apply to the subscription addons: type: array description: | Optional usage addons to apply when upgrading: - if set, apply provided billable addons (non-billable meters are ignored) - if omitted, keep current subscription addons (or billing addons for new subs) - if omitted during interval switch, keep addon selection and switch addon price interval - if empty, or all provided meters are ignored, remove all existing billable addons items: $ref: "#/components/schemas/BillingMeter" mode: type: string description: | Mode to use for the upgrade (default value is `commit`): - `commit`: a checkout session is returned or the upgrade is applied directly - `preview`: a preview invoice is always returned enum: - commit - preview required: - product - interval BillingInvoicePreview: type: object properties: amount: description: Final total owed for this invoice after discounts and credits. type: number subtotal: description: Sum of invoice line items before discounts and credits are applied. type: number amountDueToday: description: Remaining unpaid amount on this invoice, what would be charged now. type: number customerBalance: description: Current balance, if any, being stored on the customer. If positive, the customer has credit to apply to their next invoice. type: number remainingCustomerBalance: description: Current balance after potential upgrade. type: number lines: type: array description: Details of the change happening on the subscription. items: type: object properties: description: type: string amount: type: number periodStart: $ref: "#/components/schemas/Timestamp" periodEnd: $ref: "#/components/schemas/Timestamp" required: - amount - description - periodStart - periodEnd discounts: type: array description: Discounts applied to the subscription. items: type: object properties: description: description: The description of the applied discount. type: string amount: description: The amount of the applied discount. type: number required: - amount - description required: - subtotal - amount - amountDueToday - customerBalance - remainingCustomerBalance - lines BillingUpgrade: oneOf: - type: object properties: result: type: string enum: - checkout sessionId: type: string description: Stripe payment session ID required: - result - sessionId - type: object properties: result: type: string enum: - preview invoice: $ref: "#/components/schemas/BillingInvoicePreview" required: - result - invoice - type: object properties: result: type: string enum: - upgraded required: - result - type: object properties: result: type: string enum: - downgraded required: - result - type: object properties: result: type: string enum: - interval_changed required: - result MigrateOrganizationParameters: type: object properties: interval: description: The desired billing interval $ref: "#/components/schemas/BillingInterval" product: type: string description: The new product to upgrade to enum: - free_2024 - plus_2024 - pro_2024 changes: $ref: "#/components/schemas/SubscriptionChanges" required: - product - interval - changes Error: type: object required: - error properties: error: type: object properties: code: type: integer format: int32 message: type: string required: - code - message BillingDiscount: type: object properties: duration: description: How many months the discount will last type: number percentOff: description: Percent that will be deducted from the subtotal of the invoice type: number required: - duration - percentOff SitePageviews: type: object properties: object: type: string enum: - site-pageviews siteId: type: string description: The identifier of the site pageviews: description: Number of pageviews in the past 30 days type: number required: - object - siteId - pageviews BillingPortal: type: object properties: url: type: string description: URL to the billing portal for an organization required: - url BillingSwitchAction: type: string enum: - trial - upgrade - upgrade_passive - downgrade - switch_interval BillingMeterUsage: type: object description: Usage metrics for a billing meter properties: total: description: Total usage for the current billing period type: number entries: description: Usage entries for the period type: array items: type: object properties: date: $ref: "#/components/schemas/Timestamp" value: type: number description: Usage value for the date required: - date - value required: - total - entries SearchSpaceResult: type: object description: Search result representing a space. properties: type: type: string enum: - space id: type: string title: type: string score: $ref: "#/components/schemas/SearchResultScore" pages: type: array items: $ref: "#/components/schemas/SearchPageResult" required: - type - id - title - score - pages CreateSpace: allOf: - type: object properties: title: type: string maxLength: 50 emoji: $ref: "#/components/schemas/Emoji" parent: type: string description: ID of a parent collection language: $ref: "#/components/schemas/TranslationLanguage" editMode: $ref: "#/components/schemas/SpaceEditMode" description: The edit mode of the space - anyOf: - type: object properties: {} additionalProperties: true - oneOf: - type: object description: Create a space from a template required: - template properties: template: $ref: "#/components/schemas/ApplySpaceTemplate" - type: object description: Create a space from a computed content source required: - computedSource properties: computedSource: $ref: "#/components/schemas/ComputedContentSourceRevision" - type: object description: Create a completely empty space (no page in it) required: - empty properties: empty: type: boolean enum: - true InstalledIntegration: type: object description: An installed integration with its current status required: - status - integration properties: status: $ref: "#/components/schemas/IntegrationInstallationStatus" integration: $ref: "#/components/schemas/Integration" SAMLProviderLabel: type: string minLength: 1 maxLength: 30 SAMLProviderEntityID: type: string maxLength: 1024 SAMLProviderCertificate: type: string maxLength: 10000 SAMLProviderStatus: type: string description: | Status of the provider. - `active`: The provider is active and can be used to authenticate users. - `pending`: The provider is pending and is not yet fully configured. enum: - active - pending OrganizationSAMLProvider: type: object properties: object: type: string description: Type of Object, always equals to "saml-provider" enum: - saml-provider id: type: string description: Unique identifier for the provider. label: $ref: "#/components/schemas/SAMLProviderLabel" ssoURL: $ref: "#/components/schemas/URL" entityID: $ref: "#/components/schemas/SAMLProviderEntityID" certificate: $ref: "#/components/schemas/SAMLProviderCertificate" defaultTeam: $ref: "#/components/schemas/OrganizationTeam" defaultRole: $ref: "#/components/schemas/MemberRoleOrGuest" createdAt: description: Date at which the provider was created. $ref: "#/components/schemas/Timestamp" status: $ref: "#/components/schemas/SAMLProviderStatus" service: description: Metadata about the service provider. properties: acsURL: type: string description: Assertion Consumer Service (ACS) URL format: uri startURL: type: string description: Start URL for the Identity Provider format: uri entityID: $ref: "#/components/schemas/SAMLProviderEntityID" required: - acsURL - startURL - entityID urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the SAML Provider in the API format: uri required: - location required: - object - id - label - ssoURL - entityID - certificate - defaultRole - createdAt - status - service - urls OrganizationSSOProviderLogin: type: object properties: id: type: string description: Unique identifier for the provider. label: $ref: "#/components/schemas/SAMLProviderLabel" startURL: type: string description: The starting login URL for the Identity Provider format: uri required: - id - label - startURL OrganizationUsageSpaces: type: object description: Spaces usage metrics of an organization properties: total: description: Count of all spaces type: number required: - total OrganizationUsageCollections: type: object description: Collections usage metrics of an organization properties: total: description: Count of all collections type: number required: - total OrganizationUsageSites: type: object description: Sites usage metrics of an organization oneOf: - properties: total: description: Count of all sites type: number legacyBasic: description: Count of all legacy basic sites type: number legacyPremium: description: Count of all legacy premium sites type: number required: - total - legacyBasic - legacyPremium - properties: total: description: Count of all sites type: number basic: description: Count of all basic sites type: number premium: description: Count of all premium sites type: number ultimate: description: Count of all ultimate sites type: number sponsored: description: Count of all sponsored sites type: number required: - total - basic - premium - ultimate - sponsored OrganizationUsageTeams: type: object description: Team members usage metrics of an organization properties: total: description: Count of all teams type: number required: - total OrganizationUsageMembers: type: object description: Members usage metrics of an organization properties: total: description: Count of all members type: number seats: description: Count of all paid seats type: number admin: description: Count of all admins type: number create: description: Count of all creators type: number edit: description: Count of all editors type: number review: description: Count of all reviewers type: number comment: description: Count of all commenters type: number read: description: Count of all readers type: number guest: description: Count of all guests type: number required: - total - seats - admin - create - edit - review - comment - read - guest OrganizationUsageTeamMembers: type: object description: Team members usage metrics of an organization properties: total: description: Count of all organization members in a team type: number owner: description: Count of all team owners type: number member: description: Count of all team members type: number required: - total - owner - member OrganizationUsage: type: object description: All usage metrics of an organization properties: spaces: $ref: "#/components/schemas/OrganizationUsageSpaces" collections: $ref: "#/components/schemas/OrganizationUsageCollections" sites: $ref: "#/components/schemas/OrganizationUsageSites" teams: $ref: "#/components/schemas/OrganizationUsageTeams" members: $ref: "#/components/schemas/OrganizationUsageMembers" teamMembers: $ref: "#/components/schemas/OrganizationUsageTeamMembers" permissions: type: object description: The set of permissions for the organization's usage. required: - view properties: view: type: boolean description: Can the user view the organization's usage. required: - spaces - collections - sites - teams - members - teamMembers - permissions SearchAIQuery: type: object properties: query: type: string previousQueries: type: array deprecated: true maxItems: 10 items: type: string required: - query SearchAIAnswerSourcePage: type: object title: Page source description: The source points to a page in a space. properties: type: type: string enum: - page reason: type: string description: Short explanation of how the source was used to answer. page: type: string description: The page ID of the source. revision: type: string description: The revision ID where the page was extracted from. space: type: string description: The space ID owning the page. sections: type: array items: type: string description: The IDs of the sections of the page that were used to answer the question. required: - type - page - revision - space - sections SearchAIAnswerSourceRecord: type: object title: Site context record source description: The source points to an ingested site context record. properties: type: type: string enum: - record reason: type: string description: Short explanation of how the source was used to answer. record: type: string description: The context record ID of the source. site: type: string description: The site ID owning the source record. title: type: string description: The title of the source record. url: type: string format: uri description: The source URL of the context record. required: - type - record - site - title - url SearchAIAnswerSource: oneOf: - $ref: "#/components/schemas/SearchAIAnswerSourcePage" - $ref: "#/components/schemas/SearchAIAnswerSourceRecord" discriminator: propertyName: type SearchAIAnswer: type: object description: Answer from AI for a question asked on a content. properties: answer: $ref: "#/components/schemas/Document" followupQuestions: type: array items: type: string sources: type: array description: The sources used to generate the answer. items: $ref: "#/components/schemas/SearchAIAnswerSource" required: - sources - followupQuestions SearchAIRecommendedQuestions: type: object description: Questions recommended by the AI for the given content. properties: questions: type: array items: type: string required: - questions SearchAIRecommendedQuestionStream: type: object properties: question: type: string required: - question SearchAIAnswerStream: type: object properties: type: type: string enum: - answer answer: $ref: "#/components/schemas/SearchAIAnswer" required: - type - answer OpenAPISpecSource: oneOf: - description: Create a specification from an URL type: object properties: url: $ref: "#/components/schemas/URL" required: - url - description: Create a specification from a text string type: object properties: text: description: OpenAPI specification as text type: string minLength: 1 required: - text OpenAPISpecVersion: type: object properties: object: description: The object type, which is always "openapi-spec-version" type: string enum: - openapi-spec-version id: description: Unique identifier type: string createdAt: description: Date of creation $ref: "#/components/schemas/Timestamp" url: description: URL where the specification is accessible. $ref: "#/components/schemas/URL" urls: type: object description: URLs associated with the object properties: location: description: URL of the OpenAPI specification version in the API $ref: "#/components/schemas/URL" required: - location required: - object - id - url - urls OpenAPISpecContent: description: Content of the specification available through filesystem or public URL. type: object properties: filesystem: description: Filesystem containing all specifications. type: object urls: description: URLs associated with the specification content. type: object properties: source: $ref: "#/components/schemas/URL" public: description: Publicly accessible URL for the specification. Available for public specs (proxy URL for stored specs, source URL for external specs). Null for private specs. Can be used for the "Try it" feature. oneOf: - type: "null" - $ref: "#/components/schemas/URL" required: - source - public required: - filesystem - urls OrganizationAgentInstructions: type: object properties: object: type: string enum: - agent-instructions instructions: $ref: "#/components/schemas/JSONDocument" description: Document containing the Docs agent instructions. updatedAt: $ref: "#/components/schemas/Timestamp" updatedBy: type: string description: Identifier of the member who last updated the instructions. urls: type: object description: URLs related to the custom instructions. properties: location: type: string description: Relative URL to the resource in the API. required: - location required: - object - instructions - updatedAt - updatedBy - urls TranslationStatus: type: string enum: - pending - running - completed TranslationSource: type: object required: - space - language properties: space: type: string description: ID of the source space language: $ref: "#/components/schemas/TranslationLanguage" Translation: type: object properties: object: type: string enum: - translation id: type: string description: Unique identifier of the translation sync status: $ref: "#/components/schemas/TranslationStatus" source: $ref: "#/components/schemas/TranslationSource" language: $ref: "#/components/schemas/TranslationLanguage" instructions: $ref: "#/components/schemas/JSONDocument" result: $ref: "#/components/schemas/TranslationResult" createdAt: type: string format: date-time updatedAt: type: string format: date-time stats: type: object properties: runs: type: integer description: Total number of times the translation has been run totalWords: type: integer description: Total number of words translated totalPages: type: integer description: Total number of unique pages translated totalDuration: type: integer description: Total duration of all runs (in seconds) latestRunDuration: type: integer description: Duration of the latest run (in seconds) latestPages: type: integer description: Number of unique pages translated in the latest run latestWords: type: integer description: Number of words translated in the latest run required: - runs - totalWords - totalPages - totalDuration - latestRunDuration - latestPages - latestWords permissions: type: object properties: view: type: boolean description: Whether the user can view the object edit: type: boolean description: Whether the user can edit the object required: - view - edit urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the translation settings in the API format: uri required: - location required: - object - id - status - source - language - instructions - createdAt - updatedAt - stats - permissions - urls GlossaryTranslations: type: object additionalProperties: type: string minLength: 1 maxLength: 255 pattern: ^[^\n\r]*$ description: Mapping of language codes to translated terms GlossaryEntry: type: object properties: object: type: string enum: - glossary-entry id: type: string description: Unique identifier of the glossary entry translations: $ref: "#/components/schemas/GlossaryTranslations" createdAt: type: string format: date-time updatedAt: type: string format: date-time urls: type: object properties: location: type: string format: uri description: URL of the glossary entry in the API required: - location required: - object - id - translations - createdAt - updatedAt - urls GlossaryBatchOperation: oneOf: - type: object properties: type: type: string enum: - insert translations: $ref: "#/components/schemas/GlossaryTranslations" required: - type - translations - type: object properties: type: type: string enum: - update id: type: string translations: $ref: "#/components/schemas/GlossaryTranslations" required: - type - id - translations - type: object properties: type: type: string enum: - delete id: type: string required: - type - id StorageFileMetadata: type: object properties: name: type: string description: Original filename type: type: string description: MIME type of the file size: type: number description: Size of the file in bytes required: - name - type - size StorageUploadKind: type: string enum: - customization_font - import_file StorageUploadURL: type: object properties: object: type: string description: The kind of file to upload enum: - storage-signed-url url: $ref: "#/components/schemas/URL" description: Presigned URL for uploading the file key: type: string description: The bucket object key for the file required: - object - url - key FontFamily: type: string description: The human-readable font-family name used in CSS (e.g., "Open Sans", "Playfair Display"). minLength: 1 maxLength: 50 FontWeight: type: integer description: Numeric representation of the font weight (400=regular, 500=medium, 700=bold, 900=black). minimum: 1 maximum: 1000 FontSource: type: object description: A font file referenced within a font-face declaration, specifying the file's location and format. properties: url: description: The absolute or relative URL pointing to the font file. $ref: "#/components/schemas/URL" format: type: string description: The format of the font file. Prefer 'woff2' for modern browsers. enum: - woff2 - woff required: - url FontFace: type: object description: A single font-face declaration specifying the weight and source files for a particular variation of the font. properties: weight: $ref: "#/components/schemas/FontWeight" sources: type: array description: Font source files provided in supported formats (e.g., woff2, woff). items: $ref: "#/components/schemas/FontSource" minItems: 1 required: - weight - sources CustomizationFontDefinitionInput: type: object description: Defines a font family along with its various font-face declarations for use in CSS '@font-face' rules. properties: id: type: string description: A globally unique identifier for the font definition. custom: type: boolean description: Whether the font is a custom font. If false, this font is provided by GitBook. fontFamily: $ref: "#/components/schemas/FontFamily" fontFaces: type: array description: A list of font-face definitions, specifying variations such as weight and style. items: $ref: "#/components/schemas/FontFace" minItems: 1 required: - id - custom - fontFamily - fontFaces CustomizationFontDefinition: allOf: - $ref: "#/components/schemas/CustomizationFontDefinitionInput" - type: object properties: permissions: type: object description: The set of permissions for the font definition properties: edit: type: boolean description: Can the user edit the font definition required: - edit required: - permissions StorageFileKey: type: string description: The path of the file in the storage bucket minLength: 1 maxLength: 512 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 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 ContentImportRun: type: object properties: 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" status: description: Status of the import type: string enum: - pending - in-progress - completed - failed - cancelled 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 SitePublishOperationPreviewResponse: description: | A response to a request to preview the publishing of a site. It indicates whether the operation can proceed immediately, requires checkout, if a trial is available or if a trial extension is available. oneOf: - type: object properties: type: description: User can go ahead with the operation without any additional steps. Their subscription will be updated to reflect the new changes. type: string enum: - go-ahead required: - type - type: object properties: type: description: By going ahead with this operation, the user will be starting a trial in GitBook. type: string enum: - trial-available required: - type - type: object properties: type: description: The organization is eligible for an additional trial when publishing the site. type: string enum: - extended-trial-available required: - type - type: object properties: type: description: User must checkout to complete the operation. type: string enum: - checkout invoice: $ref: "#/components/schemas/BillingInvoicePreview" required: - type SiteAdaptiveDeterministicJSONSchemaPrimitives: oneOf: - type: object properties: type: type: string enum: - boolean description: type: string required: - type - description additionalProperties: false - type: object properties: type: type: string enum: - string enum: type: array items: type: string description: type: string required: - type - enum - description additionalProperties: false SiteAdaptiveJSONSchemaPrimitives: oneOf: - $ref: "#/components/schemas/SiteAdaptiveDeterministicJSONSchemaPrimitives" - type: object properties: type: type: string enum: - string description: type: string required: - type - description additionalProperties: false - type: object properties: type: type: string enum: - number description: type: string required: - type - description additionalProperties: false SiteAdaptiveJSONSchemaClaimsProperties: oneOf: - $ref: "#/components/schemas/SiteAdaptiveJSONSchemaPrimitives" - type: object properties: type: type: string enum: - array description: type: string items: $ref: "#/components/schemas/SiteAdaptiveJSONSchemaPrimitives" required: - type - description - items additionalProperties: false - type: object properties: type: type: string enum: - object description: type: string properties: type: object additionalProperties: $ref: "#/components/schemas/SiteAdaptiveJSONSchemaClaimsProperties" additionalProperties: type: boolean enum: - false required: - type - description - properties - additionalProperties additionalProperties: false SiteAdaptiveJSONSchema: type: object description: JSON schema describing the expected attributes of an Adaptive site schema. properties: $schema: type: string enum: - http://json-schema.org/draft-07/schema# type: type: string enum: - object properties: type: object properties: unsigned: type: object description: Unsigned claims of the site visitor. properties: type: type: string enum: - object description: type: string enum: - Unsigned claims of the site visitor. properties: type: object additionalProperties: $ref: "#/components/schemas/SiteAdaptiveJSONSchemaClaimsProperties" additionalProperties: type: boolean enum: - false required: - type - description - properties - additionalProperties additionalProperties: $ref: "#/components/schemas/SiteAdaptiveJSONSchemaClaimsProperties" additionalProperties: type: boolean enum: - false required: - type - properties - additionalProperties additionalProperties: false SiteAdaptiveSchema: type: object properties: object: type: string enum: - site-adaptive-schema jsonSchema: $ref: "#/components/schemas/SiteAdaptiveJSONSchema" updatedAt: description: When the adaptive schema was updated. $ref: "#/components/schemas/Timestamp" required: - object - jsonSchema - updatedAt SiteAdaptiveTemplateCondition: type: object description: A template condition based on the site visitor schema. properties: description: type: string description: A short description of the suggested condition. condition: type: string description: The suggested condition. required: - description - condition CustomizationTheme: type: string description: | The theme to apply to the site. Supercedes the old header preset themes. - `clean`: Modern theme featuring translucency and minimally-styled elements. - `muted`: Sophisticated theme with decreased contrast between elements. - `bold`: High-impact theme with prominent colors and strong contrasts. - `gradient`: Trendy theme featuring colorful gradients and splashes of color. enum: - clean - muted - bold - gradient Color: type: string pattern: ^#(?:[0-9a-fA-F]{3}){1,2}$ CustomizationThemedColor: type: object properties: light: $ref: "#/components/schemas/Color" dark: $ref: "#/components/schemas/Color" required: - light - dark CustomizationTint: type: object properties: color: $ref: "#/components/schemas/CustomizationThemedColor" required: - color CustomizationCorners: type: string enum: - straight - rounded - circular CustomizationDepth: type: string description: | The degree of visual depth (through shadows, gradients and elevation effects) of elements on the site. - `subtle`: Subtle shadows and minimal elevation. - `flat`: Flat elements, no shadows and no elevation. enum: - subtle - flat CustomizationLinksStyle: type: string description: | The style used for regular links in the main content, header and footer. Sidebar items are styled separately. - `default`: Links are colored in the primary color and feature an underline in the same color. - `accent`: Links are colored the same as body text and feature an underline in the primary color. enum: - default - accent CustomizationDefaultFont: type: string enum: - ABCFavorit - Inter - Roboto - RobotoSlab - OpenSans - SourceSansPro - Lato - Ubuntu - Raleway - Merriweather - Overpass - NotoSans - IBMPlexSerif - Poppins - FiraSans CustomizationFont: oneOf: - $ref: "#/components/schemas/CustomizationDefaultFont" - $ref: "#/components/schemas/CustomizationFontDefinitionInput" CustomizationDefaultMonospaceFont: type: string enum: - FiraCode - IBMPlexMono - JetBrainsMono - SourceCodePro - RobotoMono - SpaceMono - DMMono - Inconsolata CustomizationMonospaceFont: oneOf: - $ref: "#/components/schemas/CustomizationDefaultMonospaceFont" - $ref: "#/components/schemas/CustomizationFontDefinitionInput" CustomizationBackground: type: string enum: - plain - match deprecated: true description: The background style has been deprecated and will be removed in a future release. Use the `tint` settings instead. CustomizationIconsStyle: type: string enum: - regular - solid - duotone - light - thin CustomizationCodeTheme: type: string enum: - default-light - default-dark - monochrome-light - monochrome-dark - andromeeda - aurora-x - ayu-dark - catppuccin-frappe - catppuccin-latte - catppuccin-macchiato - catppuccin-mocha - dark-plus - dracula - dracula-soft - everforest-dark - everforest-light - github-dark - github-dark-default - github-dark-dimmed - github-dark-high-contrast - github-light - github-light-default - github-light-high-contrast - gruvbox-dark-hard - gruvbox-dark-medium - gruvbox-dark-soft - gruvbox-light-hard - gruvbox-light-medium - gruvbox-light-soft - houston - kanagawa-dragon - kanagawa-lotus - kanagawa-wave - laserwave - light-plus - material-theme - material-theme-darker - material-theme-lighter - material-theme-ocean - material-theme-palenight - min-dark - min-light - monokai - night-owl - nord - one-dark-pro - one-light - plastic - poimandres - red - rose-pine - rose-pine-dawn - rose-pine-moon - slack-dark - slack-ochin - snazzy-light - solarized-dark - solarized-light - synthwave-84 - tokyo-night - vesper - vitesse-black - vitesse-dark - vitesse-light CustomizationThemedCodeTheme: type: object properties: light: $ref: "#/components/schemas/CustomizationCodeTheme" dark: $ref: "#/components/schemas/CustomizationCodeTheme" required: - light - dark CustomizationSidebarBackgroundStyle: type: string description: | - `default`: No background, content sits directly against sidebar edge. - `filled`: Muted background color that extends to sidebar edges. enum: - default - filled CustomizationSidebarListStyle: type: string description: | - `default`: Simple list items without special styling, groups are inset with a line. - `pill`: Rounded capsule shape around selected/active items. - `line`: Continuous line next to all items, with colored line part for selected/active items. enum: - default - pill - line CustomizationSearchStyle: type: string description: | The style of the search button. - `prominent`: large search bar in the middle of the header, with less room for other header items, - `subtle`: small search bar in the corner of the header, with more room for other header items. enum: - prominent - subtle CustomizationLocale: type: string description: Language for the UI element deprecated: true enum: - en - fr - es - zh - ja - de - nl - no - pt-br - ru CustomizationHeaderPreset: type: string deprecated: true description: The header preset to use for the site. This is a legacy setting and the site styling theme should be used instead. enum: - default - bold - contrast - custom - none LocalizedString: type: object description: Localized string value, keyed by locale. Contains overrides for non-default languages only. propertyNames: $ref: "#/components/schemas/TranslationLanguage" additionalProperties: type: string CustomizationContentLinkTitle: type: string maxLength: 64 LocalizedString64: type: object description: Localized string value with a 128 character limit, keyed by locale. Contains overrides for non-default languages only. additionalProperties: type: string maxLength: 64 propertyNames: $ref: "#/components/schemas/TranslationLanguage" CustomizationContentLink: type: object properties: title: $ref: "#/components/schemas/CustomizationContentLinkTitle" localizedTitle: description: Localized overrides for the link title, keyed by locale. $ref: "#/components/schemas/LocalizedString64" to: $ref: "#/components/schemas/ContentRef" required: - title - to CustomizationHeaderItem: type: object properties: title: type: string localizedTitle: description: Localized overrides for the header item title, keyed by locale. $ref: "#/components/schemas/LocalizedString" style: type: string enum: - link - button-primary - button-secondary to: oneOf: - $ref: "#/components/schemas/ContentRef" - type: "null" links: type: array items: $ref: "#/components/schemas/CustomizationContentLink" condition: description: Conditional expression used to evaluate whether the header item should be shown to the site's visitor. $ref: "#/components/schemas/Expression" required: - title - links - to CustomizationFooterGroup: type: object properties: title: type: string localizedTitle: description: Localized overrides for the footer group title, keyed by locale. $ref: "#/components/schemas/LocalizedString" links: type: array items: $ref: "#/components/schemas/CustomizationContentLink" required: - title - links CustomizationAnnouncementMessage: description: The text content of the announcement. type: string minLength: 2 maxLength: 128 CustomizationAnnouncement: type: object properties: enabled: description: Whether to show the site's announcement. type: boolean message: $ref: "#/components/schemas/CustomizationAnnouncementMessage" localizedMessage: description: Localized overrides for the announcement message, keyed by locale. $ref: "#/components/schemas/LocalizedString128" link: description: The content or URL the announcement links to when clicked. $ref: "#/components/schemas/CustomizationContentLink" style: description: The style of the announcement. Used to style the banner with the right semantic color and enable/disable features like hiding the banner. type: string enum: - info - warning - danger - success required: - enabled - message - style CustomizationDefaultThemeMode: type: string enum: - light - dark - system CustomizationAIMode: type: string enum: - none - search - assistant CustomizationSuggestedQuestion: type: string minLength: 3 maxLength: 64 CustomizationSuggestedQuestions: type: array description: Suggested questions to display at the start of the chosen AI mode. items: $ref: "#/components/schemas/CustomizationSuggestedQuestion" maxItems: 5 SiteExternalLinksTarget: type: string description: | How external links should open when clicked. - `self`: External links open in the current tab. - `blank`: External links open in a new browser tab. enum: - self - blank SiteSocialAccountPlatform: description: The platform of the social handle. type: string enum: - twitter - instagram - facebook - linkedin - github - discord - slack - youtube - tiktok - reddit - bluesky - mastodon - threads - medium SiteSocialAccountHandle: description: A handle on a social platform, without prefixes like the @ symbol. type: string minLength: 1 maxLength: 128 SiteSocialAccount: type: object properties: platform: $ref: "#/components/schemas/SiteSocialAccountPlatform" handle: $ref: "#/components/schemas/SiteSocialAccountHandle" display: type: object properties: footer: type: boolean default: true header: type: boolean default: false required: - footer - header required: - platform - handle - display SiteSocialAccounts: type: array description: The social accounts of the site. items: $ref: "#/components/schemas/SiteSocialAccount" maxItems: 10 SiteCustomizationSettingsBase: type: object properties: title: description: Title to use for the published site. If not defined, it'll fallback to the default content title. $ref: "#/components/schemas/SiteTitle" localizedTitle: description: Localized titles for the site, keyed by locale. If not defined, the localized title will not be changed. $ref: "#/components/schemas/LocalizedString128" styling: type: object properties: theme: $ref: "#/components/schemas/CustomizationTheme" primaryColor: $ref: "#/components/schemas/CustomizationThemedColor" tint: $ref: "#/components/schemas/CustomizationTint" infoColor: $ref: "#/components/schemas/CustomizationThemedColor" successColor: $ref: "#/components/schemas/CustomizationThemedColor" warningColor: $ref: "#/components/schemas/CustomizationThemedColor" dangerColor: $ref: "#/components/schemas/CustomizationThemedColor" corners: $ref: "#/components/schemas/CustomizationCorners" depth: $ref: "#/components/schemas/CustomizationDepth" links: $ref: "#/components/schemas/CustomizationLinksStyle" font: $ref: "#/components/schemas/CustomizationFont" monospaceFont: $ref: "#/components/schemas/CustomizationMonospaceFont" background: deprecated: true $ref: "#/components/schemas/CustomizationBackground" icons: $ref: "#/components/schemas/CustomizationIconsStyle" codeTheme: type: object properties: default: $ref: "#/components/schemas/CustomizationThemedCodeTheme" openapi: $ref: "#/components/schemas/CustomizationThemedCodeTheme" required: - default - openapi sidebar: type: object properties: background: $ref: "#/components/schemas/CustomizationSidebarBackgroundStyle" list: $ref: "#/components/schemas/CustomizationSidebarListStyle" required: - background - list search: $ref: "#/components/schemas/CustomizationSearchStyle" required: - theme - primaryColor - infoColor - successColor - warningColor - dangerColor - corners - depth - links - font - monospaceFont - codeTheme - background - icons - sidebar - search internationalization: type: object deprecated: true properties: locale: $ref: "#/components/schemas/CustomizationLocale" required: - locale favicon: $ref: "#/components/schemas/CustomizationFavicon" header: type: object properties: preset: $ref: "#/components/schemas/CustomizationHeaderPreset" logo: $ref: "#/components/schemas/CustomizationThemedURL" primaryLink: description: Destination to open when visitors click the site title/logo in the header. $ref: "#/components/schemas/ContentRef" backgroundColor: deprecated: true description: Color of the background in the header. This value is now deprecated in favour of the new theming colors. $ref: "#/components/schemas/CustomizationThemedColor" linkColor: deprecated: true description: Color of the links in the header. This value is now deprecated and will be phased out in favour of the new theming colors. $ref: "#/components/schemas/CustomizationThemedColor" links: type: array items: $ref: "#/components/schemas/CustomizationHeaderItem" required: - preset - links footer: type: object properties: logo: $ref: "#/components/schemas/CustomizationThemedURL" groups: type: array items: $ref: "#/components/schemas/CustomizationFooterGroup" copyright: type: string maxLength: 300 required: - groups announcement: $ref: "#/components/schemas/CustomizationAnnouncement" themes: description: | Customization options for the dark/light theme modes. type: object properties: default: $ref: "#/components/schemas/CustomizationDefaultThemeMode" toggeable: description: Should the reader be able to switch between dark and light mode type: boolean required: - default - toggeable pdf: type: object properties: enabled: type: boolean description: If true, PDF export is enabled for the published site. required: - enabled feedback: type: object properties: enabled: type: boolean description: If true, feedback gathering is enabled required: - enabled ai: type: object properties: mode: $ref: "#/components/schemas/CustomizationAIMode" suggestions: $ref: "#/components/schemas/CustomizationSuggestedQuestions" required: - mode advancedCustomization: type: object properties: enabled: type: boolean description: If true, Advanced customization is enabled required: - enabled git: type: object properties: showEditLink: type: boolean description: Whether the published site should show a link to edit the content on the git provider set up in the Git Sync required: - showEditLink pageActions: type: object properties: externalAI: type: boolean description: Whether actions to open ChatGPT, Anthropic, etc. should be available in the page menu. markdown: type: boolean description: Whether the copy and open the markdown version of the page should be available in the page menu. mcp: type: boolean description: Whether an action to connect to the docs using the MCP server should be available in the page menu. required: - externalAI - markdown - mcp externalLinks: type: object properties: target: $ref: "#/components/schemas/SiteExternalLinksTarget" required: - target pagination: type: object properties: enabled: type: boolean description: Whether the pagination navigation should be displayed on pages. required: - enabled trademark: type: object properties: enabled: type: boolean description: Whether the GitBook trademark ("Powered by GitBook") should be visible required: - enabled privacyPolicy: type: object properties: url: $ref: "#/components/schemas/URL" socialPreview: type: object properties: url: $ref: "#/components/schemas/URL" socialAccounts: $ref: "#/components/schemas/SiteSocialAccounts" insights: type: object properties: trackingCookie: type: boolean description: Whether GitBook identifies the visitor on the site using a cookie. default: true required: - trackingCookie required: - styling - internationalization - favicon - header - footer - themes - pdf - feedback - ai - advancedCustomization - trademark - externalLinks - pagination - pageActions - git - privacyPolicy - socialPreview - socialAccounts - insights SiteCustomizationSettings: allOf: - $ref: "#/components/schemas/SiteCustomizationSettingsBase" - type: object properties: updatedAt: description: When the customization settings were updated. If missing, customization was not updated. $ref: "#/components/schemas/Timestamp" SiteIntegrationScript: type: object properties: script: description: Script URL to load. $ref: "#/components/schemas/URL" contentSecurityPolicy: description: Content Security Policy to secure the loading of this script. type: string cookies: type: boolean description: If true, the script will potentially load use cookies and visitors should be aware. required: - script - cookies PublishedContentSite: type: object properties: object: type: string enum: - published-content-site site: $ref: "#/components/schemas/Site" structure: $ref: "#/components/schemas/SiteStructure" customizations: type: object properties: site: $ref: "#/components/schemas/SiteCustomizationSettings" siteSpaces: type: object additionalProperties: $ref: "#/components/schemas/SiteCustomizationSettings" required: - site - siteSpaces scripts: type: array items: $ref: "#/components/schemas/SiteIntegrationScript" required: - object - site - structure - customizations - scripts ShareLinkName: type: string description: Name of the share link minLength: 0 maxLength: 50 ShareLink: type: object properties: object: type: string description: Type of Object, always equals to "share-link" enum: - share-link id: type: string description: Unique identifier for the share-link createdAt: $ref: "#/components/schemas/Timestamp" name: $ref: "#/components/schemas/ShareLinkName" active: type: boolean urls: type: object description: URLs associated with the object properties: published: type: string description: URL of the published version of the share-link. format: uri required: - object - id - createdAt - urls SiteStructureItemPointer: type: object properties: type: type: string enum: - site-space - site-section - site-section-group id: type: string description: Unique identifier for the site structure item (site space, site section or site section group). required: - type - id SiteStructureItemMovePosition: type: object description: Position at which to move the site structure item (site space, site section or site section group). properties: before: $ref: "#/components/schemas/SiteStructureItemPointer" after: $ref: "#/components/schemas/SiteStructureItemPointer" SiteStructureItem: title: Site Structure Item type: object description: | A site structure item can be a site space, a site section or a site section group. It is used to represent the structure of a site. oneOf: - $ref: "#/components/schemas/SiteSpace" - $ref: "#/components/schemas/SiteSection" - $ref: "#/components/schemas/SiteSectionGroup" BillingOperationPreviewResponse: description: | A response to a request to preview a paid operation or action. A user might preview an operation before executing it to see which billing steps would be required (if any). This schema defines the response of that preview request. oneOf: - type: object properties: type: description: User can go ahead with the operation without any additional steps. Their subscription will be updated to reflect the new changes. type: string enum: - go-ahead required: - type - type: object properties: type: description: By going ahead with this operation, the user will be starting a trial in GitBook. type: string enum: - trial-available required: - type - type: object properties: type: description: User must checkout to complete the operation. type: string enum: - checkout invoice: $ref: "#/components/schemas/BillingInvoicePreview" required: - type SiteUpgradeReason: type: string description: The reason or feature that triggered the site upgrade oneOf: - $ref: "#/components/schemas/SiteFeatureKey" - $ref: "#/components/schemas/BillingMeter" - type: string enum: - settings - billing-page - end-of-trial SitePublishingAuth: allOf: - oneOf: - $ref: "#/components/schemas/VisitorAuthCustomBackend" - $ref: "#/components/schemas/VisitorAuthIntegrationBackend" - type: object properties: object: type: string description: Type of Object, always equals to "publishing-auth" enum: - publishing-auth privateKey: type: string description: Private key used to sign JWT tokens. fallbackURL: type: string format: uri description: URL to redirect to when the authenticated access secret is invalid. integration: type: string description: | Name of the authenticated access integration installed on the site (if any). It is also the one being used as VA backend when the published auth settings are configured to use "integration" as backend. required: - object - privateKey SitePublishingAuthUpdate: allOf: - oneOf: - $ref: "#/components/schemas/VisitorAuthCustomBackend" - $ref: "#/components/schemas/VisitorAuthIntegrationBackend" - type: object properties: fallbackURL: type: - string - "null" format: uri description: A fallback URL that will be used if authentication fails. If not provided, the fallback URL will not be changed. If set to null, the fallback URL will be unset. SiteCustomizationSettingsInput: allOf: - $ref: "#/components/schemas/SiteCustomizationSettingsBase" SiteSearchScope: oneOf: - type: object required: - mode properties: mode: description: | Search across all sections of a site, only including the default content of each section. This scope is wide and shallow. You may optionally specify a list of additional site spaces to search in alongside the default content. type: string enum: - default currentSiteSpace: type: string description: | The ID of the site space that must always be included in the search results. The language of this site space will be used to match other site spaces with the same language, if applicable. - type: object required: - mode - siteSpaceIds properties: mode: description: Only search in the provided site spaces. type: string enum: - specific siteSpaceIds: type: array minLength: 1 items: type: string - type: object required: - mode properties: mode: description: Search in all sections and site spaces. This scope is wide and deep. type: string enum: - all SearchRecordResult: type: object description: Search result representing a site context record. properties: type: type: string enum: - record id: type: string description: The ID of the context record. title: type: string description: The title of the record. score: $ref: "#/components/schemas/SearchResultScore" description: type: string description: The description of the record. url: type: string format: uri description: URL of the record in the source system. required: - type - id - title - score - url ContextRecordType: type: string enum: - ticket - document ContextConnector: oneOf: - type: string description: Integration source pattern: ^integration:[^:]+$ x-typescript: "`integration:${string}`" - type: string description: Builtin sources enum: - builtin:email - builtin:api - builtin:website - builtin:youtube - builtin:github-discussions - builtin:github-issues - builtin:intercom ContextRecordTitle: type: string description: Title for the context record minLength: 1 maxLength: 256 ContextRecordDescription: type: string description: Optional short description of the context record maxLength: 512 ContextRecord: type: object properties: object: type: string enum: - context-record id: type: string description: The ID of the record title: $ref: "#/components/schemas/ContextRecordTitle" description: $ref: "#/components/schemas/ContextRecordDescription" type: $ref: "#/components/schemas/ContextRecordType" createdAt: $ref: "#/components/schemas/Timestamp" processedAt: $ref: "#/components/schemas/Timestamp" connection: type: string description: The connection ID associated with the record connector: description: The connector type associated with the record $ref: "#/components/schemas/ContextConnector" topics: type: array description: The associated topics of the record items: type: string urls: type: object description: URLs associated with the record properties: location: type: string description: URL of the record in the API format: uri source: type: string description: URL of the record in the source format: uri required: - location required: - object - id - title - type - createdAt - connection - connector - urls ContextRecordInput: type: object description: Input to ingest a new context record properties: id: type: string description: Unique local identifier for the record type: $ref: "#/components/schemas/ContextRecordType" title: $ref: "#/components/schemas/ContextRecordTitle" description: $ref: "#/components/schemas/ContextRecordDescription" body: type: string description: Body content of the record as markdown url: type: string description: URL of the record format: uri createdAt: $ref: "#/components/schemas/Timestamp" description: Date of the record creation in the original source metadata: type: object additionalProperties: oneOf: - type: string - type: number required: - id - title - body - type SiteScanStatus: type: string description: Status of a persisted site scan. enum: - pending - running - done - failed SiteScanFindings: type: object description: Number of findings created by the scan, grouped by severity. properties: low: type: number medium: type: number high: type: number required: - low - medium - high SiteScan: type: object properties: object: type: string enum: - site-scan id: type: string description: The ID of the scan status: $ref: "#/components/schemas/SiteScanStatus" topic: type: string description: The site topic ID associated with the scan createdAt: $ref: "#/components/schemas/Timestamp" startedAt: $ref: "#/components/schemas/Timestamp" finishedAt: $ref: "#/components/schemas/Timestamp" findings: $ref: "#/components/schemas/SiteScanFindings" failureMessage: type: string description: Failure message for failed scans urls: type: object description: URLs associated with the scan properties: location: type: string description: URL of the scan endpoint in the API format: uri required: - location required: - object - id - status - topic - createdAt - findings - urls SiteFindingStatus: type: string description: Status of a site finding. enum: - open - done - canceled SiteFindingType: type: string description: |- Classification of a site finding: - Outdated content: The content is no longer up to date with external context and may be misleading or incorrect. - Incoherent content: The content contains information that is inconsistent or contradictory. - Content gap: The content is missing important information that should be present to answer user questions effectively. - Other: Any other type of finding not covered by the above categories. enum: - content-outdated - incoherence - content-gap - other SiteFindingSeverity: type: string description: Estimated end-user severity of a site finding. enum: - low - medium - high SiteFindingTitle: type: string description: Short finding title maxLength: 256 SiteFinding: type: object properties: object: type: string enum: - site-finding id: type: string description: The ID of the finding scan: type: string description: The site scan ID associated with the finding topic: type: string description: The site topic ID associated with the finding title: $ref: "#/components/schemas/SiteFindingTitle" changeRequests: type: number description: Number of change requests linked to the finding pages: type: number description: Number of pages linked to the finding records: type: number description: Number of records linked to the finding questions: type: number description: Number of questions linked to the finding status: $ref: "#/components/schemas/SiteFindingStatus" type: $ref: "#/components/schemas/SiteFindingType" severity: $ref: "#/components/schemas/SiteFindingSeverity" description: $ref: "#/components/schemas/JSONDocument" autoFixable: type: boolean description: Whether an AI agent should be able to fix this finding directly createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" urls: type: object description: URLs associated with the finding properties: location: type: string description: URL of the finding list endpoint in the API format: uri required: - location required: - object - id - scan - topic - title - changeRequests - pages - records - questions - status - type - severity - description - autoFixable - createdAt - updatedAt - urls SiteFindingPage: type: object properties: object: type: string enum: - site-finding-page spaceId: type: string description: The space ID containing the linked page. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - object - spaceId - page SiteQuestionType: type: string description: Type classification of the user question. enum: - exploring - how-to - troubleshooting - reference - unknown SiteQuestionStatsFeedback: type: object description: Aggregated feedback for answers linked to a site question. properties: positive: type: number description: Count of answers with positive feedback. negative: type: number description: Count of answers with negative feedback. unrated: type: number description: Count of answers without feedback. required: - positive - negative - unrated SiteQuestionStatsAnswered: type: object description: Aggregated answered assessment for answers linked to a site question. properties: yes: type: number description: Count of answers assessed as fully answered. partially: type: number description: Count of answers assessed as partially answered. no: type: number description: Count of answers assessed as not answered. required: - yes - partially - no SiteQuestionStatsRelevance: type: object properties: relevant: type: number spam: type: number off-topic: type: number unclear: type: number required: - relevant - spam - off-topic - unclear SiteQuestionStatsTypes: type: object properties: exploring: type: number how-to: type: number troubleshooting: type: number reference: type: number unknown: type: number required: - exploring - how-to - troubleshooting - reference - unknown SiteQuestionStatsChannelTypes: type: object description: Count of answers by site channel type, including core channels. additionalProperties: type: number SiteQuestionStatsChannels: type: object description: Count of answers by site channel ID. additionalProperties: type: number SiteQuestionStats: type: object description: Aggregated stats for questions and linked answers. properties: total: type: number description: Total count of questions included in the aggregation. answers: type: number description: Total count of answers linked to the questions. feedback: $ref: "#/components/schemas/SiteQuestionStatsFeedback" answered: $ref: "#/components/schemas/SiteQuestionStatsAnswered" relevance: $ref: "#/components/schemas/SiteQuestionStatsRelevance" types: $ref: "#/components/schemas/SiteQuestionStatsTypes" channelTypes: $ref: "#/components/schemas/SiteQuestionStatsChannelTypes" channels: $ref: "#/components/schemas/SiteQuestionStatsChannels" weeklyPulse: type: array minItems: 13 maxItems: 13 description: Weekly count of related question answers for the past 3 months. items: type: number required: - total - answers - feedback - answered - relevance - types - channelTypes - channels - weeklyPulse SiteQuestion: type: object properties: object: type: string enum: - site-question id: type: string description: The ID of the site question. question: type: string description: Canonical text for the unique site question. type: $ref: "#/components/schemas/SiteQuestionType" createdAt: $ref: "#/components/schemas/Timestamp" askedAt: $ref: "#/components/schemas/Timestamp" stats: $ref: "#/components/schemas/SiteQuestionStats" urls: type: object description: URLs associated with the site question. properties: location: type: string format: uri description: URL of the site question in the API. required: - location required: - object - id - question - type - createdAt - askedAt - stats - urls ContextConnectionLabel: type: string description: Optional label for the connection minLength: 0 maxLength: 128 ContextConnectionStatus: type: string enum: - pending - syncing - succeeded - failed ContextSearchBoost: type: string description: Relative score adjustment applied to records from a connection when searching. enum: - x0.8 - x1.0 - x1.2 ContextUsageSettings: type: object properties: changeRequests: type: boolean description: Whether to use context to propose change requests search: type: boolean description: Whether to expose records in search results searchBoost: $ref: "#/components/schemas/ContextSearchBoost" required: - changeRequests - search - searchBoost YoutubeChannelId: type: string description: A YouTube channel ID starting with "UC". pattern: ^UC[A-Za-z0-9_-]{22}$ YoutubeChannelName: type: string description: A YouTube channel handle starting with "@". pattern: ^@[A-Za-z0-9._-]{3,100}$ YoutubeChannelPattern: description: A YouTube channel identifier, either a channel ID or a channel handle. oneOf: - $ref: "#/components/schemas/YoutubeChannelId" - $ref: "#/components/schemas/YoutubeChannelName" ContextConnectorSetup: oneOf: - type: object properties: connector: type: string enum: - builtin:email required: - connector - type: object properties: connector: type: string enum: - builtin:api required: - connector - type: object properties: connector: type: string pattern: ^integration:[^:]+$ x-typescript: "`integration:${string}`" required: - connector - type: object properties: connector: type: string enum: - builtin:website setupSettings: type: object properties: url: type: string format: uri required: - url required: - connector - setupSettings - type: object properties: connector: type: string enum: - builtin:youtube setupSettings: type: object properties: channelId: $ref: "#/components/schemas/YoutubeChannelPattern" required: - channelId required: - connector - setupSettings - type: object properties: connector: type: string enum: - builtin:github-discussions setupSettings: type: object properties: repository: type: string pattern: ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ token: type: string minLength: 1 required: - repository - token required: - connector - setupSettings - type: object properties: connector: type: string enum: - builtin:github-issues setupSettings: type: object properties: repository: type: string pattern: ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ token: type: string minLength: 1 required: - repository - token required: - connector - setupSettings - type: object properties: connector: type: string enum: - builtin:intercom setupSettings: type: object properties: token: type: string minLength: 1 required: - token required: - connector - setupSettings ContextConnection: allOf: - type: object properties: object: type: string enum: - context-connection id: type: string description: The ID of the connection createdAt: $ref: "#/components/schemas/Timestamp" syncedAt: $ref: "#/components/schemas/Timestamp" label: $ref: "#/components/schemas/ContextConnectionLabel" status: $ref: "#/components/schemas/ContextConnectionStatus" records: type: integer description: Number of records ingested from this connection failureMessage: type: string description: Failure message when synchronization fails email: type: object description: Parameters associated with the connection when it is an email connection properties: ingestionAddress: type: string description: Inbound email address for the connection format: email usageSettings: $ref: "#/components/schemas/ContextUsageSettings" urls: type: object description: URLs associated with the connection properties: location: type: string description: URL of the connection in the API format: uri required: - location required: - object - id - createdAt - status - records - usageSettings - urls - $ref: "#/components/schemas/ContextConnectorSetup" SiteTopicUsageSettings: type: object properties: changeRequests: type: boolean description: Whether to use context to propose change requests required: - changeRequests SiteTopic: type: object properties: object: type: string enum: - context-topic id: type: string description: The ID of the topic label: type: string description: The label of the topic parent: type: object description: The parent topic when this topic is nested under another one properties: id: type: string description: The ID of the parent topic label: type: string description: The label of the parent topic required: - id - label createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" icon: $ref: "#/components/schemas/Icon" summary: $ref: "#/components/schemas/JSONDocument" usageSettings: $ref: "#/components/schemas/SiteTopicUsageSettings" pages: type: number description: The number of pages associated with the topic records: type: number description: The number of records in the topic findings: type: object description: The number of findings linked to the topic properties: open: type: number description: The number of open findings linked to the topic total: type: number description: The total number of findings linked to the topic required: - open - total questions: $ref: "#/components/schemas/SiteQuestionStats" urls: type: object description: URLs associated with the topic properties: location: type: string description: URL of the topic in the API format: uri required: - location required: - object - id - label - summary - icon - usageSettings - pages - records - findings - questions - createdAt - updatedAt - urls SiteQuestionAnswerRelevance: type: string description: Relevance classification of the user question. enum: - relevant - spam - off-topic - unclear SiteQuestionAnswerResolution: type: string description: Whether the response answered the question. enum: - no - partially - yes SiteQuestionAnswerSourceBase: type: object properties: object: type: string enum: - site-question-answer-source id: type: string description: The ID of the source. weight: type: number description: Relative weight of this source in the generated answer. title: type: string description: The title of the source. urls: type: object description: URLs associated with the site question answer. properties: location: type: string format: uri description: URL of the site question answer in the API. required: - location required: - object - id - title - weight - urls SiteQuestionAnswerSourcePage: allOf: - $ref: "#/components/schemas/SiteQuestionAnswerSourceBase" - type: object title: Page source description: Source data pointing to a page used for a site question answer. properties: type: type: string enum: - page space: type: string description: The space ID of the source page. revision: type: string description: The revision ID used for this source page. page: type: string description: The page ID of the source page. required: - type - space - revision - page SiteQuestionAnswerSourceRecord: allOf: - $ref: "#/components/schemas/SiteQuestionAnswerSourceBase" - type: object properties: type: type: string enum: - record record: type: string description: The site context record ID. connector: $ref: "#/components/schemas/ContextConnector" required: - type - record SiteQuestionAnswerSource: oneOf: - $ref: "#/components/schemas/SiteQuestionAnswerSourcePage" - $ref: "#/components/schemas/SiteQuestionAnswerSourceRecord" discriminator: propertyName: type SiteQuestionAnswerHelpfulness: type: string description: Helpfulness of the response for the end user need. enum: - low - medium - high SiteInsightsSession: type: object description: Identifiers for a GitBook site session, used for analytics and adaptive content. properties: visitorId: type: string description: GitBook's unique identifier of the visitor. sessionId: type: string description: GitBook's unique identifier of the visitor's session. required: - visitorId - sessionId SiteCoreChannelType: type: string enum: - site - embed - api SiteConfigurableChannelType: type: string enum: - builtin:slack - builtin:discord - builtin:github - builtin:linear SiteQuestionAnswer: type: object properties: object: type: string enum: - site-question-answer id: type: string description: The ID of the site question answer. question: type: object properties: id: type: string description: The ID of the parent site question. type: $ref: "#/components/schemas/SiteQuestionType" required: - id - type topics: type: array description: The IDs of the associated site topics. items: type: string input: type: object required: - text - raw properties: text: type: string description: Normalized question text for this answer. raw: type: string description: Raw question text as asked by the user. thread: type: object required: - id - previous properties: id: type: string description: The ID of the thread this answer belongs to. previous: type: string description: ID of the previous answer in the same thread. session: $ref: "#/components/schemas/SiteInsightsSession" feedback: type: object required: - rating properties: rating: type: integer enum: - -1 - 1 description: Feedback rating provided by the user. responseId: type: string description: The response identifier for this answer. language: type: string description: ISO language code of the question. answered: $ref: "#/components/schemas/SiteQuestionAnswerResolution" helpfulness: $ref: "#/components/schemas/SiteQuestionAnswerHelpfulness" relevance: $ref: "#/components/schemas/SiteQuestionAnswerRelevance" channel: oneOf: - type: object properties: type: $ref: "#/components/schemas/SiteCoreChannelType" required: - type - type: object properties: type: $ref: "#/components/schemas/SiteConfigurableChannelType" id: type: - string - "null" description: ID of the associated site channel when the answer originates from a configurable channel. Null if the channel has been deleted. required: - type - id createdAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" urls: type: object description: URLs associated with the site question answer. properties: location: type: string format: uri description: URL of the site question answer in the API. required: - location required: - object - id - question - topics - input - responseId - language - answered - helpfulness - relevance - channel - createdAt - urls AIMessageRole: type: string enum: - user - assistant - developer AIToolCallGetPageContent: type: object properties: tool: type: string enum: - getPageContent spaceId: type: string description: The ID of the space being accessed. revisionId: type: string description: The ID of the revision within which the page content is being fetched. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - tool - spaceId - page - revisionId AIToolCallGetRecordContent: type: object description: Tool to read the body of an external record. properties: tool: type: string enum: - getRecordContent siteId: type: string description: The ID of the site owning the context record. recordId: type: string description: The ID of the context record. title: type: string description: The title of the record. url: type: string format: uri description: URL of the record in the source system. required: - tool - siteId - recordId - title AIToolCallGetPages: type: object properties: tool: type: string enum: - getPages spaceId: type: string description: The ID of the space being accessed. revisionId: type: string description: The revision ID of the space. required: - tool - spaceId - revisionId AIToolCallGetReusableContents: type: object properties: tool: type: string enum: - getReusableContents spaceId: type: string description: The ID of the space being accessed. revisionId: type: string description: The revision ID of the space. required: - tool - spaceId - revisionId AIToolCallSearchResultPage: type: object title: Page result description: Result of a search matching a page. properties: type: type: string enum: - page spaceId: type: string description: The ID of the space pageId: type: string description: The ID of the page revisionId: type: string description: The revision ID of the result anchor: type: string description: The anchor of the result title: type: string description: The title of the result description: type: string description: The description of the result required: - type - spaceId - pageId - revisionId - title AIToolCallSearchResultRecord: type: object title: Site context record result description: Result of a search matching a site context record. properties: type: type: string enum: - record siteId: type: string description: The ID of the site owning the context record recordId: type: string description: The ID of the context record title: type: string description: The title of the record description: type: string description: The description of the record url: type: string format: uri description: URL of the record in its original source required: - type - siteId - recordId - title AIToolCallSearchResult: description: Result of a search oneOf: - $ref: "#/components/schemas/AIToolCallSearchResultPage" - $ref: "#/components/schemas/AIToolCallSearchResultRecord" discriminator: propertyName: type AIToolCallSearch: type: object description: Tool to search for content properties: tool: type: string enum: - search query: type: string description: The query that has been searched for. results: type: array items: $ref: "#/components/schemas/AIToolCallSearchResult" required: - tool - query - results AIToolCallEditPage: type: object properties: tool: type: string enum: - editPage spaceId: type: string description: The ID of the space being edited. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - tool - spaceId - page AIToolCallCreatePage: type: object properties: tool: type: string enum: - createPage spaceId: type: string description: The ID of the space being edited. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - tool - spaceId - page AIToolCallDeletePage: type: object properties: tool: type: string enum: - deletePage spaceId: type: string description: The ID of the space being edited. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - tool - spaceId - page AIToolCallRenamePage: type: object properties: tool: type: string enum: - renamePage spaceId: type: string description: The ID of the space being edited. page: $ref: "#/components/schemas/ChangedRevisionPage" title: type: string description: The new title of the page. required: - tool - spaceId - page - title AIToolCallMovePage: type: object properties: tool: type: string enum: - movePage spaceId: type: string description: The ID of the space being edited. page: $ref: "#/components/schemas/ChangedRevisionPage" to: $ref: "#/components/schemas/ChangedRevisionPage" moveType: type: string description: | Indicates how the page was moved relative to the "to" page. - `within`: moved as the last child of the target page (or to the root when `to` is omitted) - `before`: moved directly before the target page - `after`: moved directly after the target page enum: - within - before - after required: - tool - spaceId - page - moveType AIToolCallListModifiedPages: type: object properties: tool: type: string enum: - listModifiedPages spaceId: type: string description: The ID of the space being accessed. required: - tool - spaceId AIToolCallGetPageDiff: type: object properties: tool: type: string enum: - getPageDiff spaceId: type: string description: The ID of the space being accessed. page: $ref: "#/components/schemas/ChangedRevisionPage" required: - tool - spaceId - page AIToolCallCreateReusableContent: type: object properties: tool: type: string enum: - createReusableContent spaceId: type: string description: The ID of the space being edited. reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" required: - tool - spaceId - reusableContent AIToolCallEditReusableContent: type: object properties: tool: type: string enum: - editReusableContent spaceId: type: string description: The ID of the space being edited. reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" required: - tool - spaceId - reusableContent AIToolCallGetReusableContent: type: object properties: tool: type: string enum: - getReusableContent spaceId: type: string description: The ID of the space being accessed. revisionId: type: string description: The ID of the revision within which the reusable content is being fetched. reusableContent: $ref: "#/components/schemas/ChangedRevisionReusableContent" required: - tool - spaceId - reusableContent - revisionId AIToolCallCreateChangeRequest: type: object properties: tool: type: string enum: - createChangeRequest spaceId: type: string description: The ID of the space the change request belongs to. action: type: string enum: - create - update changeRequest: type: object properties: id: type: string description: The unique identifier of the change request. number: type: number description: Incremental identifier of the change request. subject: type: string description: A brief summary of the change request. required: - id - number - subject required: - tool - spaceId - action - changeRequest AIToolCallComment: type: object properties: tool: type: string enum: - comment spaceId: type: string description: The ID of the space being commented. page: description: The page being commented. $ref: "#/components/schemas/ChangedRevisionPage" commentId: type: string description: The ID of the comment being posted. required: - tool - spaceId - commentId AIToolCallReplyToComment: type: object properties: tool: type: string enum: - replyToComment spaceId: type: string description: The ID of the space being commented. page: description: The page being commented. $ref: "#/components/schemas/ChangedRevisionPage" commentId: type: string description: The ID of the comment being replied to. replyId: type: string description: The ID of the reply being posted. required: - tool - spaceId - commentId - replyId AIToolCallSubmitChangeRequestReview: type: object properties: tool: type: string enum: - submitChangeRequestReview spaceId: type: string description: The ID of the space where the review was submitted. changeRequestId: type: string description: The ID of the change request being reviewed. status: $ref: "#/components/schemas/ChangeRequestReviewStatus" description: Result of the review. reviewId: type: string description: Identifier of the review that was created. commentId: type: string description: Identifier of the comment that was created as part of the review. required: - tool - spaceId - changeRequestId - status - reviewId - commentId AIToolCallMCP: type: object description: Tool called from an MCP server properties: tool: type: string enum: - mcp mcpServerId: type: string description: The ID of the MCP server that has been called. mcpToolName: type: string description: The name of the tool that has been called. mcpToolTitle: type: string description: The title of the tool that has been called. required: - tool - mcpServerId - mcpToolName AIToolCallOtherSummary: type: object description: Summary of a generic tool call. properties: icon: $ref: "#/components/schemas/Icon" text: type: string description: Text to display to the user to describe the tool call. required: - icon - text AIToolCallOther: type: object description: Any tool call that is unknown by GitBook properties: tool: type: string enum: - other summary: $ref: "#/components/schemas/AIToolCallOtherSummary" required: - tool - summary AIToolCall: oneOf: - $ref: "#/components/schemas/AIToolCallGetPageContent" - $ref: "#/components/schemas/AIToolCallGetRecordContent" - $ref: "#/components/schemas/AIToolCallGetPages" - $ref: "#/components/schemas/AIToolCallGetReusableContents" - $ref: "#/components/schemas/AIToolCallSearch" - $ref: "#/components/schemas/AIToolCallEditPage" - $ref: "#/components/schemas/AIToolCallCreatePage" - $ref: "#/components/schemas/AIToolCallDeletePage" - $ref: "#/components/schemas/AIToolCallRenamePage" - $ref: "#/components/schemas/AIToolCallMovePage" - $ref: "#/components/schemas/AIToolCallListModifiedPages" - $ref: "#/components/schemas/AIToolCallGetPageDiff" - $ref: "#/components/schemas/AIToolCallCreateReusableContent" - $ref: "#/components/schemas/AIToolCallEditReusableContent" - $ref: "#/components/schemas/AIToolCallGetReusableContent" - $ref: "#/components/schemas/AIToolCallCreateChangeRequest" - $ref: "#/components/schemas/AIToolCallComment" - $ref: "#/components/schemas/AIToolCallReplyToComment" - $ref: "#/components/schemas/AIToolCallSubmitChangeRequestReview" - $ref: "#/components/schemas/AIToolCallMCP" - $ref: "#/components/schemas/AIToolCallOther" AIMessageStepPhase: type: string description: The phase of a step in a message from the AI agent. enum: - commentary - final_answer Timerange: type: object properties: start: $ref: "#/components/schemas/Timestamp" end: $ref: "#/components/schemas/Timestamp" required: - start - end AIAttachmentImage: type: object properties: type: type: string enum: - image url: $ref: "#/components/schemas/URL" required: - type - url AIAttachmentFile: type: object properties: type: type: string enum: - file url: $ref: "#/components/schemas/URL" filename: type: string description: Name of the file. contentType: type: string enum: - application/pdf required: - type - url - filename - contentType AIAttachment: oneOf: - $ref: "#/components/schemas/AIAttachmentImage" - $ref: "#/components/schemas/AIAttachmentFile" AIMessageStep: type: object description: A step in a message from the AI agent. properties: content: $ref: "#/components/schemas/JSONDocument" reasoning: $ref: "#/components/schemas/JSONDocument" toolCalls: type: array items: $ref: "#/components/schemas/AIToolCall" phase: $ref: "#/components/schemas/AIMessageStepPhase" timing: type: object description: The timing of the step. properties: reasoning: $ref: "#/components/schemas/Timerange" attachments: type: array items: $ref: "#/components/schemas/AIAttachment" AIMessageTask: oneOf: - type: object description: When the agent is responding to a comment. properties: type: type: string enum: - respond_to_comment spaceId: type: string description: The ID of the space to respond to the comment in. changeRequestId: type: string description: The ID of the change request to respond to the comment in. commentId: type: string description: The ID of the comment to respond to. required: - type - spaceId - commentId - type: object description: When the agent is reviewing a change request. properties: type: type: string enum: - review_change_request spaceId: type: string description: The ID of the space the change request is in. changeRequestId: type: string description: The ID of the change request to review. required: - type - spaceId - changeRequestId - type: object description: When the agent is implementing a task in a change request. properties: type: type: string enum: - implement_change_request spaceId: type: string description: The ID of the space the change request is in. changeRequestId: type: string description: The ID of the change request to implement the task in. required: - type - spaceId - changeRequestId AIMessageResponseMetadata: description: The response that generated this message. type: object properties: stopReason: type: string description: The reason the response was stopped. If not defined, the response finished normally. enum: - aborted id: type: string description: The ID of the response that generated this message. It can be undefined if the stream was aborted. previous: type: string description: The ID of the previous response that this message is based on. AIMessage: type: object properties: id: type: string role: $ref: "#/components/schemas/AIMessageRole" steps: type: array items: $ref: "#/components/schemas/AIMessageStep" task: $ref: "#/components/schemas/AIMessageTask" response: $ref: "#/components/schemas/AIMessageResponseMetadata" required: - id - role - steps SiteQuestionAnswerWithResponse: allOf: - $ref: "#/components/schemas/SiteQuestionAnswer" - type: object properties: response: $ref: "#/components/schemas/AIMessage" required: - response SiteSpaceCustomizationSettings: allOf: - $ref: "#/components/schemas/SiteCustomizationSettings" - type: object properties: hasOverrides: type: boolean description: Indicates whether the site customization settings have been overridden. required: - hasOverrides SiteSectionGroupPointer: type: object properties: type: type: string enum: - site-section - site-section-group id: type: string description: Unique identifier for the site section required: - type - id SiteSectionGroupMovePosition: type: object description: Position at which to move the site section group. properties: before: $ref: "#/components/schemas/SiteSectionGroupPointer" after: $ref: "#/components/schemas/SiteSectionGroupPointer" SiteSectionPointer: type: object properties: type: type: string enum: - site-section siteSection: type: string description: Unique identifier for the site section required: - type - siteSection SiteSectionMovePosition: type: object description: Position at which to move the site section to. properties: before: $ref: "#/components/schemas/SiteSectionPointer" after: $ref: "#/components/schemas/SiteSectionPointer" SiteSpacePointer: type: object properties: type: type: string enum: - site-space siteSpace: type: string description: Unique identifier for the site space required: - type - siteSpace SiteSpaceMovePosition: type: object description: Position at which to move the site space to. properties: before: $ref: "#/components/schemas/SiteSpacePointer" after: $ref: "#/components/schemas/SiteSpacePointer" InviteSiteUsersAndTeams: type: object properties: role: description: Role to set. $ref: "#/components/schemas/MemberRoleOrGuest" anyOf: - type: object properties: teams: type: array minItems: 1 items: type: string description: The ID of the team to be invited required: - teams - type: object properties: users: type: array minItems: 1 items: type: string description: The ID of the user to be invited required: - users required: - role OrganizationPointer: type: object properties: type: type: string enum: - organization organization: type: string description: Unique identifier for the organization required: - type - organization UserSitePermissionSiteOrigin: type: object description: Direct site permission origin. properties: type: type: string enum: - site site: type: string description: Unique identifier for the site reason: type: string description: Why the permission was enforced at the site level. enum: - member - team - default team: type: string description: Unique identifier for the team when the permission comes from a team override. required: - type - site - reason UserSitePermissionOrigin: description: The origin that enforced the effective permission level for a user in a site. oneOf: - $ref: "#/components/schemas/SpacePointer" - $ref: "#/components/schemas/OrganizationPointer" - $ref: "#/components/schemas/UserSitePermissionSiteOrigin" UserSitePermission: type: object description: Permission of a user in a site. properties: permission: $ref: "#/components/schemas/MemberRoleOrGuest" user: $ref: "#/components/schemas/User" origin: $ref: "#/components/schemas/UserSitePermissionOrigin" required: - permission - user - origin UserSitePermissionOverride: type: object description: Permission override of a user in a site. properties: permission: $ref: "#/components/schemas/MemberRoleOrGuest" user: $ref: "#/components/schemas/User" required: - permission - user TeamSitePermissionOverride: type: object description: Permission override of a team in a site. properties: permission: $ref: "#/components/schemas/MemberRoleOrGuest" team: $ref: "#/components/schemas/OrganizationTeam" required: - permission - team AIMessageContext: type: object description: Context about the current user sending a message. properties: location: type: object properties: spaceId: type: string description: ID of the current space. pageId: type: string description: ID of the current page. required: - spaceId - pageId AIMessageInput: type: object description: Input version of an AI message. properties: role: $ref: "#/components/schemas/AIMessageRole" content: oneOf: - type: string maxLength: 2048 - $ref: "#/components/schemas/JSONDocument" context: $ref: "#/components/schemas/AIMessageContext" attachments: type: array items: $ref: "#/components/schemas/AIAttachment" required: - role - content AIModel: type: string enum: - fast - reasoning-low - reasoning-medium - reasoning-high AIToolDefinition: type: object description: Description of a tool that can be called from an AI agent. properties: name: type: string description: The name of the tool. It should be unique within the agent. description: type: string description: The description of the tool, passed to the AI agent. inputSchema: type: object description: JSON schema describing the input of the tool. properties: type: type: string enum: - object properties: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - boolean - array - object description: type: string description: Description of the property. required: - type - description additionalProperties: true required: - type - properties required: - name - description AIToolCallResult: type: object description: Result of a tool call. required: - tool - toolCallId - output properties: tool: type: string description: The name of the tool that was called. toolCallId: type: string description: The ID of the tool call. output: type: object description: The output to the tool call. summary: $ref: "#/components/schemas/AIToolCallOtherSummary" AIStreamResponseStart: type: object description: | Message emitted by the server to indicate the start of the AI response. properties: type: type: string enum: - response_start messageId: type: string description: | The ID of the message that this event is composing. task: $ref: "#/components/schemas/AIMessageTask" required: - type - messageId AIStreamResponseStepStart: type: object description: | Message emitted by the server to indicate the start of a step in the AI response. properties: type: type: string enum: - response_step_start messageId: type: string description: | The ID of the message that this event is composing. stepIndex: type: integer description: | The index of the step of the message that this event is composing. phase: $ref: "#/components/schemas/AIMessageStepPhase" required: - type - messageId - stepIndex AIStreamResponseFinish: type: object description: | Message emitted by the server to indicate the end of the AI response. It contains the ID of the response to be referenced for followup requests. properties: type: type: string enum: - response_finish messageId: type: string description: | The ID of the message that this event is composing. responseId: type: string deprecated: true description: The ID of the response response: description: The response metadata associated with the message. $ref: "#/components/schemas/AIMessageResponseMetadata" required: - type - messageId - response AIStreamResponseDocument: type: object description: | Message emitted by the server to indicate the latest block of the document. The block can either be a new block or an update to the previous block. properties: type: type: string enum: - response_document - response_reasoning messageId: type: string description: | The ID of the message that this event is composing. stepIndex: type: integer description: | The index of the step of the message that this event is composing. operation: type: string enum: - insert - update blocks: type: array items: $ref: "#/components/schemas/DocumentBlocksTopLevels" required: - type - messageId - stepIndex - operation - blocks AIStreamResponseObject: type: object description: | Message emitted by the server to indicate a chunk of the JSON object response. properties: type: type: string enum: - response_object messageId: type: string description: | The ID of the message that this event is composing. jsonChunk: type: string description: The chunk of the JSON object response required: - type - messageId - jsonChunk AIStreamResponseToolCall: type: object description: | Message emitted by the server to indicate that the AI has called a tool. properties: type: type: string enum: - response_tool_call messageId: type: string description: | The ID of the message that this event is composing. stepIndex: type: integer description: | The index of the step of the message that this event is composing. toolCall: $ref: "#/components/schemas/AIToolCall" required: - type - messageId - stepIndex - toolCall AIStreamResponseToolCallPending: type: object description: | Message emitted by the server to indicate that the AI is calling a client-side tool. properties: type: type: string enum: - response_tool_call_pending messageId: type: string description: | The ID of the message that this event is composing. stepIndex: type: integer description: | The index of the step of the message that this event is composing. toolCall: type: object description: The tool call that the AI is calling. required: - tool - input properties: tool: type: string description: The name of the tool that the AI is calling. input: type: object description: The input to the tool call. toolCallId: type: string description: The ID of the tool call that the AI is calling. required: - type - messageId - stepIndex - toolCall - toolCallId AIStreamResponseFollowupSuggestion: type: object description: | Message emitted by the server to suggest a followup message the user could respond with. properties: type: type: string enum: - response_followup_suggestion messageId: type: string description: | The ID of the message that this event is composing. suggestions: type: array items: type: string description: | A followup message the user could respond with. required: - type - messageId - suggestions AIStreamResponseAttachment: type: object description: | Message emitted by the server to indicate that the AI has attached an image. properties: type: type: string enum: - response_attachment messageId: type: string description: | The ID of the message that this event is composing. stepIndex: type: integer description: | The index of the step of the message that this event is composing. attachment: $ref: "#/components/schemas/AIAttachment" required: - type - messageId - stepIndex - attachment AIStreamResponse: oneOf: - $ref: "#/components/schemas/AIStreamResponseStart" - $ref: "#/components/schemas/AIStreamResponseStepStart" - $ref: "#/components/schemas/AIStreamResponseFinish" - $ref: "#/components/schemas/AIStreamResponseDocument" - $ref: "#/components/schemas/AIStreamResponseObject" - $ref: "#/components/schemas/AIStreamResponseToolCall" - $ref: "#/components/schemas/AIStreamResponseToolCallPending" - $ref: "#/components/schemas/AIStreamResponseFollowupSuggestion" - $ref: "#/components/schemas/AIStreamResponseAttachment" SiteSettingsScanTopics: type: string enum: - auto - never description: Controls when topics are being scanned for findings. SiteSettingsFindingChangeRequests: type: string enum: - always - auto-fixable - never description: Controls how issue remediation change requests should be handled for a site. SiteAgentSettingsInput: type: object properties: scans: description: Settings related to scanning for a site. type: object properties: topics: $ref: "#/components/schemas/SiteSettingsScanTopics" required: - topics findings: description: Settings related to processing of findings for a site. type: object properties: changeRequests: $ref: "#/components/schemas/SiteSettingsFindingChangeRequests" required: - changeRequests editing: description: Site-specific instructions for the editing agent. type: object properties: customInstructions: $ref: "#/components/schemas/JSONDocument" required: - customInstructions required: - scans - findings - editing SiteAgentSettings: allOf: - type: object properties: object: type: string enum: - site-agent-settings updatedAt: $ref: "#/components/schemas/Timestamp" updatedBy: type: string description: Identifier of the member who last updated the settings. urls: type: object properties: location: type: string description: Relative URL to the resource in the API. required: - location required: - object - urls - $ref: "#/components/schemas/SiteAgentSettingsInput" SiteInsightsEventSession: allOf: - $ref: "#/components/schemas/SiteInsightsSession" - type: object description: Analytics info on the GitBook's site session. properties: cookies: type: object description: The visitors cookies. additionalProperties: type: string ip: type: string description: | IP address of the visitor. If not defined, it'll default to the IP executing the request. userAgent: type: string description: | User-agent of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent language: type: - string - "null" description: | Language of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language referrer: description: Referrer of the session oneOf: - type: "null" - type: string enum: - "" - $ref: "#/components/schemas/URL" visitorAuthToken: type: - string - "null" deprecated: true description: Deprecated, use visitorAuthClaims instead. visitorAuthClaims: description: | Claims of the visitor. This is used to identify the visitor with adaptive content. $ref: "#/components/schemas/PlainObject" required: - cookies - userAgent - language - referrer SiteInsightsDisplayContext: type: string description: Context in which the event was recorded. enum: - site - server - embed - mcp SiteInsightsEventLocation: type: object description: Location of the event. properties: url: description: URL of the location. $ref: "#/components/schemas/URL" displayContext: description: Whether the event was tracked on the site, the server, or an embed widget. $ref: "#/components/schemas/SiteInsightsDisplayContext" default: site siteSection: type: - string - "null" description: ID of the concerned site section. siteSpace: type: - string - "null" description: ID of the concerned site space. siteShareKey: type: - string - "null" description: ID of the concerned site share key. space: type: - string - "null" description: ID of the concerned space. revision: type: - string - "null" description: ID of the concerned revision. page: type: - string - "null" description: ID of the concerned page. required: - url - siteSection - siteSpace - siteShareKey - page - space - revision SiteInsightsEventBase: type: object properties: session: $ref: "#/components/schemas/SiteInsightsEventSession" location: $ref: "#/components/schemas/SiteInsightsEventLocation" timestamp: description: Optional timestamp of the event. If not provided, the current timestamp will be used. Must be within 5 minutes of the current time. $ref: "#/components/schemas/Timestamp" required: - session - location SiteInsightsEventPageView: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - page_view required: - type SiteInsightsEventPageMarkdownRequest: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - page_markdown_request required: - type SiteInsightsEventSearchOpen: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - search_open required: - type SiteInsightsEventSearchTypeQuery: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - search_type_query query: type: string description: Query of the search. required: - type - query SiteInsightsEventSearchOpenResult: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - search_open_result query: type: string description: Query of the search. result: description: Target of the opened search result. oneOf: - type: object properties: spaceId: type: string description: ID of the concerned space. pageId: type: string description: ID of the concerned page. required: - spaceId - pageId - type: object properties: recordId: type: string description: ID of the concerned record. required: - recordId required: - type - query - result SiteInsightsEventPagePostFeedback: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - page_post_feedback feedback: type: object properties: rating: $ref: "#/components/schemas/PageFeedbackRating" required: - rating required: - type - feedback SiteInsightsEventPagePostFeedbackComment: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - page_post_feedback_comment feedback: type: object properties: rating: $ref: "#/components/schemas/PageFeedbackRating" comment: type: string minLength: 1 maxLength: 512 required: - rating - comment required: - type - feedback SiteInsightsEventAskQuestion: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - ask_question query: type: string description: Question being asked. required: - type - query SiteInsightsEventAskView: description: Event when a user views the ask UI. allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - ask_view required: - type SiteInsightsEventAskRateResponse: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - ask_rate_response query: type: string description: Question asked. rating: type: integer enum: - 1 - -1 responseId: type: string description: ID of the AI response. required: - type - query - rating - responseId SiteInsightsLinkPosition: type: string enum: - announcement - header - footer - sidebar - content SiteInsightsEventLinkClick: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - link_click link: type: object properties: target: $ref: "#/components/schemas/ContentRef" position: $ref: "#/components/schemas/SiteInsightsLinkPosition" required: - target - position required: - type - link SiteInsightsEventAPIClientOpen: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - api_client_open operation: $ref: "#/components/schemas/OpenAPIOperationPointer" required: - type - operation SiteInsightsEventAPIClientRequest: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - api_client_request operation: $ref: "#/components/schemas/OpenAPIOperationPointer" required: - type - operation SiteInsightsTrademarkPlacement: type: string enum: - sidebar - ad - footer - pdf - embed SiteInsightsEventTrademarkClick: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - trademark_click placement: $ref: "#/components/schemas/SiteInsightsTrademarkPlacement" required: - type - placement SiteInsightsAdPlacement: type: string enum: - aside SiteInsightsAd: type: object properties: domain: type: string zoneId: type: string placement: $ref: "#/components/schemas/SiteInsightsAdPlacement" required: - domain - zoneId - placement SiteInsightsEventAdClick: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - ad_click ad: $ref: "#/components/schemas/SiteInsightsAd" required: - type - ad SiteInsightsEventAdDisplay: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - ad_display ad: $ref: "#/components/schemas/SiteInsightsAd" required: - type - ad SiteInsightsLLMSVariant: type: string enum: - standard - full SiteInsightsEventLLMSRequest: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - llms_request llmsVariant: $ref: "#/components/schemas/SiteInsightsLLMSVariant" required: - type - llmsVariant SiteInsightsEventMCPRequest: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - mcp_request required: - type SiteInsightsEventRSSRequest: allOf: - $ref: "#/components/schemas/SiteInsightsEventBase" - type: object properties: type: type: string enum: - rss_request required: - type SiteInsightsEvent: oneOf: - $ref: "#/components/schemas/SiteInsightsEventPageView" - $ref: "#/components/schemas/SiteInsightsEventPageMarkdownRequest" - $ref: "#/components/schemas/SiteInsightsEventSearchOpen" - $ref: "#/components/schemas/SiteInsightsEventSearchTypeQuery" - $ref: "#/components/schemas/SiteInsightsEventSearchOpenResult" - $ref: "#/components/schemas/SiteInsightsEventPagePostFeedback" - $ref: "#/components/schemas/SiteInsightsEventPagePostFeedbackComment" - $ref: "#/components/schemas/SiteInsightsEventAskQuestion" - $ref: "#/components/schemas/SiteInsightsEventAskView" - $ref: "#/components/schemas/SiteInsightsEventAskRateResponse" - $ref: "#/components/schemas/SiteInsightsEventLinkClick" - $ref: "#/components/schemas/SiteInsightsEventAPIClientOpen" - $ref: "#/components/schemas/SiteInsightsEventAPIClientRequest" - $ref: "#/components/schemas/SiteInsightsEventTrademarkClick" - $ref: "#/components/schemas/SiteInsightsEventAdClick" - $ref: "#/components/schemas/SiteInsightsEventAdDisplay" - $ref: "#/components/schemas/SiteInsightsEventLLMSRequest" - $ref: "#/components/schemas/SiteInsightsEventMCPRequest" - $ref: "#/components/schemas/SiteInsightsEventRSSRequest" SiteInsightsQueryDateTimeColumn: type: object required: - column properties: column: type: string enum: - datetime interval: type: string enum: - hour - day - week - month SiteInsightsQueryEventsColumn: oneOf: - $ref: "#/components/schemas/SiteInsightsQueryDateTimeColumn" - type: object required: - column properties: column: type: string enum: - url - type: object required: - column properties: column: type: string enum: - eventType - type: object required: - column properties: column: type: string enum: - eventsCount - type: object required: - column properties: column: type: string enum: - sessionsCount - type: object required: - column properties: column: type: string enum: - visitorsCount - type: object required: - column properties: column: type: string enum: - siteSection - type: object required: - column properties: column: type: string enum: - siteSpace - type: object required: - column properties: column: type: string enum: - siteShareKey - type: object required: - column properties: column: type: string enum: - displayContext - type: object required: - column properties: column: type: string enum: - page - type: object required: - column properties: column: type: string enum: - visitorGeoCountry - type: object required: - column properties: column: type: string enum: - visitorGeoPoint precision: type: integer minimum: 0 maximum: 15 - type: object required: - column properties: column: type: string enum: - visitorDevice - type: object required: - column properties: column: type: string enum: - visitorBrowser - type: object required: - column properties: column: type: string enum: - visitorOS - type: object required: - column properties: column: type: string enum: - visitorBot - type: object required: - column properties: column: type: string enum: - visitorLanguage - type: object required: - column properties: column: type: string enum: - eventLinkTargetValue - type: object required: - column properties: column: type: string enum: - eventLinkTargetKind - type: object required: - column properties: column: type: string enum: - eventLinkTargetDomain - type: object required: - column properties: column: type: string enum: - eventLinkPosition - type: object required: - column properties: column: type: string enum: - eventAPIOperationPath - type: object required: - column properties: column: type: string enum: - eventAPIOperationMethod - type: object required: - column properties: column: type: string enum: - eventLLMSVariant - type: object required: - column properties: column: type: string enum: - eventSearchQuery - type: object required: - column properties: column: type: string enum: - eventSearchResultRecordId - type: object required: - column properties: column: type: string enum: - eventPageFeedbackRating - type: object required: - column properties: column: type: string enum: - eventPageFeedbackComment - type: object required: - column properties: column: type: string enum: - eventAskResponseRating - type: object required: - column properties: column: type: string enum: - pageFeedbackRating - type: object required: - column properties: column: type: string enum: - askResponseRating - type: object required: - column properties: column: type: string enum: - referrer - type: object required: - column properties: column: type: string enum: - referrerDomain - type: object required: - column properties: column: type: string enum: - utmSource - type: object required: - column properties: column: type: string enum: - utmMedium - type: object required: - column properties: column: type: string enum: - utmCampaign - type: object required: - column properties: column: type: string enum: - utmTerm - type: object required: - column properties: column: type: string enum: - utmContent - type: object required: - column properties: column: type: string enum: - visitorClaimProperty - type: object required: - column - claim properties: column: type: string enum: - visitorClaim claim: type: string - type: object required: - column properties: column: type: string enum: - eventAdDomain - type: object required: - column properties: column: type: string enum: - eventAdPlacement - type: object required: - column properties: column: type: string enum: - eventTrademarkPlacement SiteInsightsEventType: type: string enum: - page_view - page_markdown_request - search_open - search_type_query - search_open_result - page_post_feedback - page_post_feedback_comment - ask_question - ask_view - ask_rate_response - link_click - api_client_open - api_client_request - ad_click - ad_display - trademark_click - llms_request - mcp_request - rss_request SiteInsightsVisitorBrowser: type: string enum: - chrome - firefox - safari - edge - ie - opera - unknown SiteInsightsVisitorDevice: type: string enum: - desktop - tablet - mobile - unknown SiteInsightsVisitorOS: type: string enum: - windows - macos - linux - android - ios - unknown SiteInsightsVisitorBot: type: - string - "null" enum: - null - unknown - googlebot - bingbot - duckduckbot - facebookbot - applebot - chatgpt - anthropic - gemini - perplexity - cohere - mistral - deepseek - meta - bytespider - ccbot - amazonbot - youbot - cursor - vscode - claude-code SiteInsightsQueryEventsValues: oneOf: - type: object required: - column - values properties: column: type: string enum: - datetime values: type: array items: $ref: "#/components/schemas/Timestamp" - type: object required: - column - values properties: column: type: string enum: - url values: type: array items: $ref: "#/components/schemas/URL" - type: object required: - column - values properties: column: type: string enum: - eventsCount values: type: array items: type: number - type: object required: - column - values properties: column: type: string enum: - sessionsCount values: type: array items: type: number - type: object required: - column - values properties: column: type: string enum: - visitorsCount values: type: array items: type: number - type: object required: - column - values properties: column: type: string enum: - eventType values: type: array items: $ref: "#/components/schemas/SiteInsightsEventType" - type: object required: - column - claim - values properties: column: type: string enum: - visitorClaim claim: type: string values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - visitorClaimProperty values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - visitorBrowser values: type: array items: $ref: "#/components/schemas/SiteInsightsVisitorBrowser" - type: object required: - column - values properties: column: type: string enum: - visitorDevice values: type: array items: $ref: "#/components/schemas/SiteInsightsVisitorDevice" - type: object required: - column - values properties: column: type: string enum: - visitorOS values: type: array items: $ref: "#/components/schemas/SiteInsightsVisitorOS" - type: object required: - column - values properties: column: type: string enum: - visitorBot values: type: array items: oneOf: - $ref: "#/components/schemas/SiteInsightsVisitorBot" - type: string enum: - "" - type: object required: - column - values properties: column: type: string enum: - eventLinkTargetValue values: type: array items: $ref: "#/components/schemas/ContentRef" - type: object required: - column - values properties: column: type: string enum: - eventLinkTargetKind values: type: array items: type: string enum: - url - page - file - anchor - space - collection - user - reusable-content - type: object required: - column - values properties: column: type: string enum: - eventLinkPosition values: type: array items: $ref: "#/components/schemas/SiteInsightsLinkPosition" - type: object required: - column - values properties: column: type: string enum: - siteSection values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - eventLLMSVariant values: type: array items: oneOf: - type: "null" - $ref: "#/components/schemas/SiteInsightsLLMSVariant" - type: object required: - column - values properties: column: type: string enum: - siteSpace values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - siteShareKey values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - displayContext values: type: array items: $ref: "#/components/schemas/SiteInsightsDisplayContext" - type: object required: - column - values properties: column: type: string enum: - page values: type: array items: oneOf: - type: "null" - type: object required: - page - space properties: page: type: - string - "null" space: type: string - type: object required: - column - values properties: column: type: string enum: - visitorGeoCountry values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - visitorGeoPoint values: type: array items: type: - object - "null" required: - latitude - longitude - h3 properties: latitude: type: number longitude: type: number h3: type: string - type: object required: - column - values properties: column: type: string enum: - visitorLanguage values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - eventLinkTargetDomain values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - eventAPIOperationPath values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - eventAPIOperationMethod values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - eventSearchQuery values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - eventSearchResultRecordId values: type: array items: type: - string - "null" - type: object required: - column - values properties: column: type: string enum: - pageFeedbackRating values: type: array items: type: object required: - ok - good - bad properties: ok: type: number good: type: number bad: type: number - type: object required: - column - values properties: column: type: string enum: - askResponseRating values: type: array items: type: object required: - positive - negative properties: positive: type: number negative: type: number - type: object required: - column - values properties: column: type: string enum: - eventPageFeedbackRating values: type: array items: $ref: "#/components/schemas/PageFeedbackRating" - type: object required: - column - values properties: column: type: string enum: - eventAskResponseRating values: type: array items: type: integer - type: object required: - column - values properties: column: type: string enum: - eventPageFeedbackComment values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - referrer values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - referrerDomain values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - utmSource values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - utmMedium values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - utmCampaign values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - utmTerm values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - utmContent values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - eventAdDomain values: type: array items: type: string - type: object required: - column - values properties: column: type: string enum: - eventAdPlacement values: type: array items: $ref: "#/components/schemas/SiteInsightsAdPlacement" - type: object required: - column - values properties: column: type: string enum: - eventTrademarkPlacement values: type: array items: $ref: "#/components/schemas/SiteInsightsTrademarkPlacement" SiteInsightsQueryOperator: type: string enum: - in - notIn - greaterThan - greaterThanOrEqual - lessThan - lessThanOrEqual SiteInsightsQueryEventsFilter: allOf: - $ref: "#/components/schemas/SiteInsightsQueryEventsValues" - type: object properties: operator: $ref: "#/components/schemas/SiteInsightsQueryOperator" SiteInsightsQueryRangePreset: type: string enum: - lastYear - last3Months - last30Days - last7Days - last24Hours SiteInsightsQueryRangeCustom: type: object properties: from: $ref: "#/components/schemas/Timestamp" to: $ref: "#/components/schemas/Timestamp" required: - from - to SiteInsightsQueryRange: oneOf: - $ref: "#/components/schemas/SiteInsightsQueryRangePreset" - $ref: "#/components/schemas/SiteInsightsQueryRangeCustom" SiteInsightsQueryEventsAggregation: type: object required: - range properties: select: type: array items: $ref: "#/components/schemas/SiteInsightsQueryEventsColumn" where: type: array items: $ref: "#/components/schemas/SiteInsightsQueryEventsFilter" groupBy: type: array items: $ref: "#/components/schemas/SiteInsightsQueryEventsColumn" order: type: object required: - by - direction properties: by: $ref: "#/components/schemas/SiteInsightsQueryEventsColumn" direction: type: string enum: - asc - desc range: $ref: "#/components/schemas/SiteInsightsQueryRange" limit: type: integer default: 1000 minimum: 1 maximum: 1000 SiteInsightsQueryEventsAggregationResult: type: object required: - columns properties: columns: type: array items: $ref: "#/components/schemas/SiteInsightsQueryEventsValues" SiteInsightsVisitorSegment: type: object description: A segment of visitors with the same characteristics. properties: title: type: string description: The title of the visitor profile. claims: $ref: "#/components/schemas/PlainObject" events: type: number description: The number of events for this visitor profile. visitors: type: number description: The number of visitors for this visitor profile. sessions: type: number description: The number of sessions for this visitor profile. required: - title - claims - events - visitors - sessions SiteAdsStats: type: object required: - impressions - clicks - revenue properties: impressions: type: number clicks: type: number revenue: type: string SiteRedirectSourcePath: type: string description: The source path to redirect from. maxLength: 512 pattern: ^\/(?!\*)(?!.*\*.+)(?:[A-Za-z0-9\-._~]|%[0-9A-Fa-f]{2})+(?:\/(?:[A-Za-z0-9\-._~]|%[0-9A-Fa-f]{2})+)*(?:\/\*|\*)?$ SiteRedirectDestinationSiteSection: type: object properties: kind: type: string enum: - site-section siteSectionId: type: string description: Unique identifier for the site section to redirect to required: - kind - siteSectionId SiteRedirectDestinationSiteSpace: type: object properties: kind: type: string enum: - site-space siteSpaceId: type: string description: Unique identifier for the site space to redirect to required: - kind - siteSpaceId SiteRedirectDestinationPage: type: object properties: kind: type: string enum: - site-page siteSpaceId: type: string description: Unique identifier for the site space of the page pageId: type: string description: Unique identifier for the page within the site space to redirect to required: - kind - siteSpaceId - pageId SiteRedirectDestinationExternal: type: object properties: kind: type: string enum: - external url: $ref: "#/components/schemas/URL" required: - kind - url SiteRedirectDestination: oneOf: - $ref: "#/components/schemas/SiteRedirectDestinationSiteSection" - $ref: "#/components/schemas/SiteRedirectDestinationSiteSpace" - $ref: "#/components/schemas/SiteRedirectDestinationPage" - $ref: "#/components/schemas/SiteRedirectDestinationExternal" SiteRedirect: type: object properties: object: type: string enum: - site-redirect id: type: string description: The unique identifier for the redirect. source: $ref: "#/components/schemas/SiteRedirectSourcePath" draft: type: boolean description: Whether the redirect is draft and not live. captureWildcard: type: boolean description: Capture and append the wildcard-matched suffix to the destination URL. destination: $ref: "#/components/schemas/SiteRedirectDestination" required: - object - id - source - draft - captureWildcard - destination SiteRedirectInputDestinationPath: type: object properties: kind: type: string enum: - path spaceId: type: string description: Unique identifier for the space containing the page referenced by the path. path: type: string description: Path to the page within the space revision to resolve. required: - kind - spaceId - path SiteRedirectInputDestination: oneOf: - $ref: "#/components/schemas/SiteRedirectDestination" - $ref: "#/components/schemas/SiteRedirectInputDestinationPath" SiteMcpServerName: type: string description: Name of the MCP server minLength: 1 maxLength: 100 SiteMcpServerHeaders: type: object additionalProperties: type: string minLength: 1 maxLength: 512 description: HTTP headers sent with requests to this server SiteMcpServer: type: object properties: object: type: string enum: - site-mcp-server id: type: string description: Unique identifier for the MCP server name: $ref: "#/components/schemas/SiteMcpServerName" url: $ref: "#/components/schemas/URL" headers: $ref: "#/components/schemas/SiteMcpServerHeaders" condition: description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor. $ref: "#/components/schemas/Expression" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the MCP server in the API format: uri required: - location required: - object - id - name - url - headers - urls GenericChannelPattern: type: string description: A generic channel name or pattern. For example, "general" or "support-*". pattern: ^[a-zA-Z0-9_\*-]+$ GitHubRepositoryPattern: type: string description: A GitHub repository name or pattern in the format "owner/repository". For example, "my-org/my-repo" or "my-org/*" to allow all repositories under "my-org". pattern: ^[a-zA-Z0-9._*-]+\/[a-zA-Z0-9._*-]+$ SiteChannelSetup: oneOf: - type: object properties: type: type: string enum: - builtin:slack setupSettings: type: object additionalProperties: false properties: allowedChannels: description: List of allowed Slack channel names or patterns. If empty, all channels are allowed. type: array items: $ref: "#/components/schemas/GenericChannelPattern" required: - type - setupSettings - type: object properties: type: type: string enum: - builtin:linear setupSettings: type: object additionalProperties: false properties: allowedTeams: description: List of allowed Linear team keys or patterns. If empty, all teams are allowed. type: array items: $ref: "#/components/schemas/GenericChannelPattern" required: - type - setupSettings - type: object properties: type: type: string enum: - builtin:github setupSettings: type: object additionalProperties: false properties: allowedRepositories: description: List of allowed GitHub repository names or patterns. If empty, all repositories are allowed. type: array items: $ref: "#/components/schemas/GitHubRepositoryPattern" required: - type - setupSettings - type: object properties: type: type: string enum: - builtin:discord setupSettings: type: object additionalProperties: false properties: allowedChannels: description: List of allowed Discord channel names or patterns. If empty, all channels are allowed. type: array items: $ref: "#/components/schemas/GenericChannelPattern" required: - type - setupSettings SiteChannelStatus: type: string enum: - active - pending SiteChannelRole: type: string enum: - collaborator - support SiteChannel: allOf: - $ref: "#/components/schemas/SiteChannelSetup" - type: object properties: object: type: string enum: - site-channel id: type: string description: Unique identifier for the site channel. status: $ref: "#/components/schemas/SiteChannelStatus" role: $ref: "#/components/schemas/SiteChannelRole" answers: type: integer minimum: 0 description: Number of answers linked to this channel. createdAt: $ref: "#/components/schemas/Timestamp" urls: type: object properties: location: type: string format: uri description: URL of the site channel in the API. required: - location required: - object - id - status - role - answers - createdAt - urls Subdomain: type: object properties: object: type: string enum: - subdomain subdomain: type: string description: The GitBook subdomain, for example "my-company" in "my-company.gitbook.io" pattern: ^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$ minLength: 3 maxLength: 32 target: oneOf: - $ref: "#/components/schemas/OrganizationPointer" isActive: type: boolean required: - object - subdomain - target - isActive CustomHostnameDnsStatus: type: string enum: - dns_passed - dns_wrong_cname - dns_no_cname - dns_cloudflare_proxied - dns_wrong_caa CustomHostnameSslStatus: type: string enum: - live - ssl_unknown - ssl_pending - ssl_failed - ssl_retry_expired CustomHostnameErrorStatus: type: string enum: - invalid_domain - internal_error CustomHostnameStatus: type: string oneOf: - $ref: "#/components/schemas/CustomHostnameDnsStatus" - $ref: "#/components/schemas/CustomHostnameSslStatus" - $ref: "#/components/schemas/CustomHostnameErrorStatus" CustomHostname: type: object properties: object: type: string enum: - custom-hostname hostname: $ref: "#/components/schemas/SiteHostname" target: oneOf: - $ref: "#/components/schemas/OrganizationPointer" - $ref: "#/components/schemas/SitePointer" isActive: type: boolean status: $ref: "#/components/schemas/CustomHostnameStatus" urls: type: object description: URLs associated with the object properties: location: type: string description: URL of the custom hostname in the API format: uri required: - location required: - object - hostname - target - isActive - urls UnsplashImage: type: object required: - kind - id - description - downloadLocation - urls - author properties: kind: type: string enum: - unsplash_image id: type: string description: type: string downloadLocation: type: string urls: type: object properties: full: type: string small: type: string required: - full - small author: type: object properties: name: type: string url: type: string required: - name - url HiveAccessToken: type: object description: JWT tokens to authenticate in Hive for all content. properties: contents: type: object additionalProperties: description: The Hive JWT access token. type: string required: - contents PurgeCDNCacheContext: type: object description: The context to send when purging the CDN Cache properties: tags: type: array description: The list of tags to purge items: type: string required: - tags CloudflareHostnameStatus: type: string description: The Cloudflare Hostname status enum: - pending - active - blocked - moved - deleted CloudflareHostnameTLSStatus: type: string description: The Cloudflare Hostname TLS status enum: - initializing - pending_validation - pending_issuance - pending_deployment - active - pending_deletion - pending_cleanup - deleted CloudflareHostnameTLSValidationMethod: type: string description: The Cloudflare Hostname TLS validation method enum: - http - txt - email CloudflareHostnameTLSCertificate: type: object description: The Cloudflare Hostname TLS certificate properties: issuer: type: string expiresOn: type: string issuedOn: type: string CloudflareHostnameTLSValidationError: type: object description: The Cloudflare Hostname TLS validation error properties: message: type: string required: - message CloudflareHostnameTLSInfo: type: object description: The Cloudflare Hostname TLS information properties: status: $ref: "#/components/schemas/CloudflareHostnameTLSStatus" method: $ref: "#/components/schemas/CloudflareHostnameTLSValidationMethod" certificateAuthority: type: string certificates: type: array items: $ref: "#/components/schemas/CloudflareHostnameTLSCertificate" validationErrors: type: array items: $ref: "#/components/schemas/CloudflareHostnameTLSValidationError" required: - status - method - certificates - validationErrors CustomDomainInfo: type: object description: Cloudflare Custom Domain's information properties: hostname: type: string status: $ref: "#/components/schemas/CloudflareHostnameStatus" createdAt: type: string ssl: $ref: "#/components/schemas/CloudflareHostnameTLSInfo" verificationErrors: type: array items: type: string required: - hostname - status - createdAt - verificationErrors FirebaseUserInfo: type: object description: The User Firebase Auth Info. properties: uid: type: string displayName: type: string email: type: string phoneNumber: type: string photoUrl: type: string providerId: type: string required: - uid UserBackOfficeInfo: type: object description: The GitBook User info shown in the BackOffice. properties: id: type: string authProviders: type: array items: $ref: "#/components/schemas/FirebaseUserInfo" createdAt: type: string lastSignInAt: type: string disabled: type: boolean required: - id - authProviders - createdAt - lastSignInAt - disabled BlockContext: type: object description: The context to send when blocking/unblocking properties: block: type: boolean reason: $ref: "#/components/schemas/BlockReason" blockPaidOrg: type: boolean required: - block UserImpersonationInfo: type: object description: The GitBook User impersonation info. properties: authURL: type: string impersonatorId: type: string required: - authURL - impersonatorId UserImpersonation: type: object description: The info returned when impersonating a GitBook User. allOf: - $ref: "#/components/schemas/UserBackOfficeInfo" - type: object properties: impersonation: $ref: "#/components/schemas/UserImpersonationInfo" required: - impersonation UserOrganizationsTeamsPermissions: type: object description: The teams permissions of a user properties: role: $ref: "#/components/schemas/TeamMemberRole" required: - role UserOrganizationsPermissions: type: object description: The organizations permissions of a user properties: role: $ref: "#/components/schemas/MemberRoleOrGuest" teams: type: object additionalProperties: $ref: "#/components/schemas/UserOrganizationsTeamsPermissions" disabled: type: boolean required: - role - teams UserCollectionsPermissions: type: object description: The collections permissions of a user properties: organization: type: string level: $ref: "#/components/schemas/MemberRoleOrGuest" collection: type: string required: - organization - level UserSpacesPermissions: type: object description: The spaces permissions of a user properties: organization: type: string level: $ref: "#/components/schemas/MemberRoleOrGuest" collection: type: string required: - organization - level _index: type: object description: All the permissions of a user properties: updatedAt: $ref: "#/components/schemas/Timestamp" organizations: type: object additionalProperties: $ref: "#/components/schemas/UserOrganizationsPermissions" collections: type: object additionalProperties: $ref: "#/components/schemas/UserCollectionsPermissions" spaces: type: object additionalProperties: $ref: "#/components/schemas/UserSpacesPermissions" required: - updatedAt - organizations - collections - spaces BackOfficeSite: allOf: - $ref: "#/components/schemas/Site" - type: object properties: organization: type: string description: ID of the organization owning this site required: - organization PublishedContentRedirect: oneOf: - type: object title: Redirect to the application or a different content in the site properties: target: type: string description: Type of target for the redirect enum: - application - content redirect: $ref: "#/components/schemas/URL" required: - target - redirect - type: object title: Redirect to an external resource from the site properties: target: type: string description: Type of target for the redirect enum: - external site: type: string description: ID of the resolved site. redirect: $ref: "#/components/schemas/URL" required: - target - site - redirect discriminator: propertyName: target PublishedSiteContent: type: object title: Site Content properties: site: type: string description: ID of the site matching. siteSection: type: string description: ID of the site-section matching. siteSpace: type: string description: ID of the site-space matching. space: type: string description: ID of the space matching. changeRequest: type: string description: Identifier of the change request being previewed in this URL. revision: type: string description: Identifier of the revision being previewed in this URL. pathname: type: string description: Path of the content relative to the input URL being resolved basePath: type: string description: Prefix of the path in the input URL being resolved siteBasePath: type: string description: Prefix of the site path in the input URL being resolved apiToken: type: string description: Short-lived API token to fetch content related to the space in the context of the URL. organization: type: string description: ID of the organization. shareKey: type: string description: Share link key of the site in case the site was published with share-links. complete: type: boolean description: Whether the resolved site URL is complete and at it's terminal point, meaning no more site path segments can be further expected before any page path segments. contextId: type: string description: Context returned only for a authenticated access session to track changes in the visitor session context that affect content rendering (used for cache invalidation). canonicalUrl: type: string description: The canonical URL of the resolution. preview: type: boolean description: Whether the URL is a preview URL required: - site - siteSpace - space - pathname - basePath - siteBasePath - apiToken - organization - complete - canonicalUrl PublishedSiteContentLookup: oneOf: - $ref: "#/components/schemas/PublishedContentRedirect" - $ref: "#/components/schemas/PublishedSiteContent" SiteVisitorPayload: type: object description: An object that describes the payload of site visitor info. It can include a jwt token with signed claims and/or a record of its unsigned claims. properties: jwtToken: type: string description: JWT token generated for a authenticated access session. unsignedClaims: $ref: "#/components/schemas/PlainObject" SHA256: type: string minLength: 64 maxLength: 64 SpaceTrackPageView: type: object properties: pageId: type: string description: Unique identifier of the page. visitor: type: object description: Analytics info on the GitBook's content visitor. properties: anonymousId: type: string description: GitBook's unique identifier of the visitor. cookies: type: object description: The visitors cookies. additionalProperties: type: string ip: type: string description: | IP address of the visitor. If undefined, it'll default to the IP executing the request. userAgent: type: string description: | User-agent of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent language: type: string description: | Language of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language required: - anonymousId - cookies - userAgent url: type: string description: The GitBook content's URL visited (including URL params). referrer: type: string description: The URL of referrer that linked to the page. required: - visitor - url - referrer SiteTrackPageView: allOf: - type: object properties: pageId: type: string description: Unique identifier of the page. visitor: type: object description: Analytics info on the GitBook's content visitor. properties: anonymousId: type: string description: GitBook's unique identifier of the visitor. cookies: type: object description: The visitors cookies. additionalProperties: type: string ip: type: string description: | IP address of the visitor. If undefined, it'll default to the IP executing the request. userAgent: type: string description: | User-agent of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent language: type: string description: | Language of the visitor. https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language required: - anonymousId - cookies - userAgent url: type: string description: The GitBook content's URL visited (including URL params). referrer: type: string description: The URL of referrer that linked to the page. required: - visitor - url - referrer - oneOf: - type: object properties: spaceId: type: string description: Unique identifier of the space. required: - spaceId - type: object properties: siteSpaceId: description: The site-space that was viewed type: string required: - siteSpaceId UpdateContentPublishingAuth: type: object properties: fallbackURL: type: string format: uri description: A fallback URL that will be used if authentication fails. GitBookUsers: type: string description: Predefined GitBook user identifiers enum: - gitbook:agent SpaceTemplate: type: object properties: id: type: string contentId: type: string title: type: string description: A title of the template. subtitle: type: string description: A subtitle for the template. emoji: description: An emoji representing the template. $ref: "#/components/schemas/Emoji" openAPISpec: description: An optional OpenAPI spec to create along with the template. properties: slug: $ref: "#/components/schemas/OpenAPISpecSlug" sourceURL: $ref: "#/components/schemas/URL" required: - slug - sourceURL features: type: array description: A list of features that the template supports. items: type: string description: A feature supported by the template. previewImage: type: object properties: light: $ref: "#/components/schemas/URL" dark: $ref: "#/components/schemas/URL" required: - light - dark urls: type: object description: URLs associated with the object properties: preview: $ref: "#/components/schemas/URL" required: - preview required: - id - contentId - title - subtitle - emoji - features - previewImage - urls ComputedContentSource: oneOf: - $ref: "#/components/schemas/ComputedContentSourceDocument" - $ref: "#/components/schemas/ComputedContentSourceRevision" InputPageBase: allOf: - type: object properties: id: type: string pattern: ^[a-zA-Z0-9]{1,40}$ description: | Optional unique identifier for the page. It can be used to reference pages in document links. title: type: string minLength: 1 linkTitle: description: Optional custom title for the page ToC and mention entries instead of the page title. type: string minLength: 1 maxLength: 100 required: - title - oneOf: - type: object properties: emoji: description: Emoji of the page. $ref: "#/components/schemas/Emoji" required: - emoji - type: object properties: icon: description: Icon of the page. $ref: "#/components/schemas/Icon" InputPageDocument: allOf: - $ref: "#/components/schemas/InputPageBase" - type: object properties: type: type: string enum: - document description: type: string maxLength: 300 minLength: 0 slug: description: Page's slug in its direct parent type: string pages: type: array items: oneOf: - $ref: "#/components/schemas/InputPageDocument" - $ref: "#/components/schemas/InputPageLink" - $ref: "#/components/schemas/InputPageComputed" computed: $ref: "#/components/schemas/ComputedContentSourceDocument" required: - type InputPageLink: allOf: - $ref: "#/components/schemas/InputPageBase" - type: object properties: type: type: string enum: - link target: $ref: "#/components/schemas/ContentRef" required: - type - target InputPageComputed: allOf: - $ref: "#/components/schemas/InputPageBase" - type: object properties: type: type: string enum: - computed computed: $ref: "#/components/schemas/ComputedContentSourceRevision" required: - type - computed InputPageGroup: allOf: - $ref: "#/components/schemas/InputPageBase" - type: object properties: type: type: string enum: - group slug: description: Page's slug in its direct parent type: string pages: type: array minLength: 1 items: oneOf: - $ref: "#/components/schemas/InputPageDocument" - $ref: "#/components/schemas/InputPageLink" - $ref: "#/components/schemas/InputPageComputed" required: - type - pages InputPage: oneOf: - $ref: "#/components/schemas/InputPageDocument" - $ref: "#/components/schemas/InputPageLink" - $ref: "#/components/schemas/InputPageComputed" - $ref: "#/components/schemas/InputPageGroup" InputFile: type: object properties: id: type: string name: type: string contentType: type: string downloadURL: type: string size: type: number dimensions: type: object description: For images, it contains the dimensions of it. properties: width: type: number height: type: number required: - width - height required: - name - contentType - downloadURL - size RevisionSemanticChangeType: type: string description: The type of semantic change. enum: - page_created - page_edited - page_deleted - page_moved - file_created - file_edited - file_deleted - custom_fields_edited - tag_created - tag_deleted - tag_edited GitSyncOperationState: type: string description: | * `running`: The operation is still running * `failure`: The operation failed * `success`: The operation was successful enum: - running - failure - success GitSyncOperationDirection: type: string enum: - export - import GitSyncOperationStage: type: string description: | Core stages of a Git Sync process. This is not exhaustive, but should cover the important ones. - repo_fetch: Includes fetching the latest repository contents from remote provider. - config_check: Includes checking if the YAML config is valid, etc. - content_process: Includes processing of pages & files to be imported/exported. - finalize: Includes finalizing the sync process like creating the commit on git, or creating a new revision. enum: - repo_fetch - config_check - content_process - finalize GitSyncOperation: type: object properties: state: $ref: "#/components/schemas/GitSyncOperationState" direction: $ref: "#/components/schemas/GitSyncOperationDirection" stage: $ref: "#/components/schemas/GitSyncOperationStage" dispatchedTasks: type: number completedTasks: type: number startedAt: description: Date when the operation was started $ref: "#/components/schemas/Timestamp" updatedAt: description: Date when the operation was last updated $ref: "#/components/schemas/Timestamp" completedAt: description: Date when the operation was successful (when state is `success`) $ref: "#/components/schemas/Timestamp" error: type: string description: Error details, defined if state is `failure`. required: - state - direction - stage - dispatchedTasks - completedTasks - startedAt - updatedAt IntegrationEnvironmentSpaceInstallation: allOf: - $ref: "#/components/schemas/IntegrationContentInstallationBase" - type: object properties: space: description: The space the integration is installed on. type: string required: - space IntegrationEnvironmentSiteInstallation: allOf: - $ref: "#/components/schemas/IntegrationContentInstallationBase" - type: object properties: site: description: The site the integration is installed on. type: string required: - site IntegrationEnvironment: type: object description: Runtime environment provided during the execution of integration's code. properties: authToken: type: string description: Authentication token to use with the HTTP API. Depending on the context, the token might be representing the installation or the integration. deprecated: true integration: $ref: "#/components/schemas/Integration" installation: $ref: "#/components/schemas/IntegrationInstallation" spaceInstallation: $ref: "#/components/schemas/IntegrationEnvironmentSpaceInstallation" siteInstallation: $ref: "#/components/schemas/IntegrationEnvironmentSiteInstallation" secrets: $ref: "#/components/schemas/IntegrationSecrets" signingSecret: type: string description: Secret that can be used to verify the authenticity of incoming HTTP requests to the integration. deprecated: true signingSecrets: type: object properties: integration: type: string description: Secret that can be used to verify the authenticity of incoming HTTP requests to the integration. installation: type: string description: Secret that can be used to verify the authenticity of incoming HTTP requests to the installation. spaceInstallation: type: string description: Secret that can be used to verify the authenticity of incoming HTTP requests to the space installation. siteInstallation: type: string description: Secret that can be used to verify the authenticity of incoming HTTP requests to the site installation. required: - integration apiEndpoint: type: string description: URL of the HTTP API apiTokens: type: object properties: integration: type: string description: API authentication token representing the integration. installation: type: string description: API authentication token representing the current installation. required: - integration network: $ref: "#/components/schemas/IntegrationNetwork" description: Network configuration for the integration environment required: - apiEndpoint - apiTokens - integration - signingSecrets - secrets SpaceIntegrationScript: type: object properties: script: description: Script URL to load. $ref: "#/components/schemas/URL" contentSecurityPolicy: description: Content Security Policy to secure the loading of this script. type: string cookies: type: boolean description: If true, the script will potentially load use cookies and visitors should be aware. required: - script - cookies ContentComputeDocumentEventResponse: type: object description: Response expected for an event of type `content_compute_document`. properties: document: $ref: "#/components/schemas/Document" required: - document ContentComputeRevisionEventResponse: type: object description: Response expected for an event of type `content_compute_pages`. properties: pages: type: array items: $ref: "#/components/schemas/InputPage" files: type: array items: $ref: "#/components/schemas/InputFile" BillingStatus: type: string enum: - trialing - active - past_due - incomplete_expired - canceled - unpaid - paused APIIntegrationScope: type: string enum: - integration:read - integration:update - integration:installation:read - integration:installation:update APIScope: anyOf: - $ref: "#/components/schemas/IntegrationScope" - $ref: "#/components/schemas/APIIntegrationScope" ContentAPIBaseToken: type: object description: Common properties for all Content API tokens. properties: organization: type: string description: ID of the organization that owns the content. A content token is always scoped to spaces from the same organization. spaces: type: array items: type: string description: List of spaces that the token is allowed to access. claims: type: object description: Attributes or assertions that provide specific details about the visitor for which the token was generated. additionalProperties: true rateLimitMultiplier: type: number description: Multiplier for the rate limit applied to the token. required: - organization - spaces SpaceAPIToken: allOf: - $ref: "#/components/schemas/ContentAPIBaseToken" - type: object properties: kind: type: string enum: - space space: type: string description: ID of the space that the token is allowed to access. required: - kind - space CollectionAPIToken: allOf: - $ref: "#/components/schemas/ContentAPIBaseToken" - type: object properties: kind: type: string enum: - collection collection: type: string description: ID of the collection that the token is allowed to access. required: - kind - collection SiteAPIToken: allOf: - $ref: "#/components/schemas/ContentAPIBaseToken" - type: object properties: kind: type: string enum: - site site: type: string description: ID of the site that the token is allowed to access. siteSpace: type: string description: ID of the site-space to be used when using this token for rendering published content. siteSection: type: string description: ID of the site-section to be used when using this token for rendering published content. Only defined for section sites. space: type: string description: ID of the space to be used when using this token for rendering published content. draft: type: boolean default: false description: Whether to include draft data when using this token for rendering content. If false, only live data will be included when rendering content with this token. required: - kind - site - siteSpace - space ContentAPITokenPayload: description: Content properties stored in a Content API token. oneOf: - $ref: "#/components/schemas/SpaceAPIToken" - $ref: "#/components/schemas/CollectionAPIToken" - $ref: "#/components/schemas/SiteAPIToken" APIChannelSpaceInfo: type: object properties: channel: type: string enum: - space space: type: string required: - channel - space APIChannelSpaceContent: type: object description: Channel notified when the main content of a space is changed. properties: channel: type: string enum: - space-content space: type: string required: - channel - space APIChannelSpaceGitInfo: type: object properties: channel: type: string enum: - space-git-info space: type: string required: - channel - space APIChannelSpacePublishingAuth: type: object properties: channel: type: string enum: - space-publishing-auth space: type: string required: - channel - space APIChannelSpacePublishingCustomization: type: object properties: channel: type: string enum: - space-publishing-customization space: type: string required: - channel - space APIChannelSpaceContentRefs: type: object properties: channel: type: string enum: - space-content-refs space: type: string required: - channel - space APIChannelSpaceIntegrations: type: object properties: channel: type: string enum: - space-integrations space: type: string required: - channel - space APIChannelUserAPITokens: type: object properties: channel: type: string enum: - user-api-tokens user: type: string required: - channel - user APIChannelUserOrganizations: type: object properties: channel: type: string enum: - user-organizations user: type: string required: - channel - user APIChannelUserProfile: type: object properties: channel: type: string enum: - user-profile user: type: string required: - channel - user APIChannelChangeRequest: type: object properties: channel: type: string enum: - space-change-request space: type: string changeRequest: type: string required: - channel - space - changeRequest APIChannelChangeRequests: type: object properties: channel: type: string enum: - space-change-requests space: type: string required: - channel - space APIChannelChangeRequestReviews: type: object properties: channel: type: string enum: - space-change-request-reviews space: type: string changeRequest: type: string required: - channel - space - changeRequest APIChannelChangeRequestContentRefs: type: object properties: channel: type: string enum: - space-change-request-content-refs space: type: string changeRequest: type: string required: - channel - space - changeRequest APIChannelCollection: type: object properties: channel: type: string enum: - collection collection: type: string required: - channel - collection APIChannelCollectionPublishingCustomization: type: object properties: channel: type: string enum: - collection-publishing-customization collection: type: string required: - channel - collection APIChannelOrganizationInfo: type: object properties: channel: type: string enum: - organization organization: type: string required: - channel - organization APIChannelOrganizationAgentData: type: object description: Subscription channel for changes in Docs Agent data in an organization. properties: channel: type: string enum: - organization-agent-data organization: type: string required: - channel - organization APIChannelOrganizationInviteLinks: type: object properties: channel: type: string enum: - organization-link-invites organization: type: string required: - channel - organization APIChannelOrganizationMembers: type: object properties: channel: type: string enum: - organization-members organization: type: string required: - channel - organization APIChannelOrganizationMember: type: object properties: channel: type: string enum: - organization-member organization: type: string user: type: string required: - channel - organization - user APIChannelOrganizationSAML: type: object properties: channel: type: string enum: - organization-saml organization: type: string required: - channel - organization APIChannelOrganizationTeams: type: object properties: channel: type: string enum: - organization-teams organization: type: string required: - channel - organization APIChannelOrganizationTeam: type: object properties: channel: type: string enum: - organization-team organization: type: string team: type: string required: - channel - organization - team APIChannelOrganizationTeamMembers: type: object properties: channel: type: string enum: - organization-team-members organization: type: string team: type: string required: - channel - organization - team APIChannelOrganizationTeamMember: type: object properties: channel: type: string enum: - organization-team-member organization: type: string team: type: string member: type: string required: - channel - organization - member APIChannelOrganizationSpaces: type: object description: Subscription channel for changes in spaces in an organization. properties: channel: type: string enum: - organization-spaces organization: type: string required: - channel - organization APIChannelOrganizationCollections: type: object description: Subscription channel for changes in collections in an organization. properties: channel: type: string enum: - organization-collections organization: type: string required: - channel - organization APIChannelOrganizationIntegrations: type: object properties: channel: type: string enum: - organization-integrations organization: type: string required: - channel - organization APIChannelOrganizationInstallations: type: object properties: channel: type: string enum: - organization-installations organization: type: string required: - channel - organization APIChannelOrganizationSites: type: object description: Subscription channel for changes in sites in an organization. properties: channel: type: string enum: - organization-sites organization: type: string required: - channel - organization APIChannelOrganizationOpenAPISpecs: type: object description: Subscription channel for changes in OpenAPI specifications in an organization. properties: channel: type: string enum: - organization-openapi-specs organization: type: string required: - channel - organization APIChannelOrganizationTranslations: type: object description: Subscription channel for changes in translations in an organization. properties: channel: type: string enum: - organization-translations organization: type: string required: - channel - organization APIChannelOrganizationTranslationsGlossary: type: object description: Subscription channel for changes in the glossary in an organization. properties: channel: type: string enum: - organization-translations-glossary organization: type: string required: - channel - organization APIChannelOrganizationCustomFonts: type: object description: Subscription channel for changes in custom fonts in an organization. properties: channel: type: string enum: - organization-fonts organization: type: string required: - channel - organization APIChannelOrganizationAgentInstructions: type: object description: Subscription channel for Docs agent instructions changes in an organization. properties: channel: type: string enum: - organization-agent-instructions organization: type: string required: - channel - organization APIChannelOrganizationChangeRequests: type: object description: Subscription channel for all change requests in an organization. properties: channel: type: string enum: - organization-change-requests organization: type: string required: - channel - organization APIChannelSpaceComments: type: object properties: channel: type: string enum: - space-comments space: type: string required: - channel - space APIChannelChangeRequestComments: type: object properties: channel: type: string enum: - space-change-request-comments space: type: string changeRequest: type: string required: - channel - space - changeRequest APIChannelCommentInfo: type: object properties: channel: type: string enum: - space-comment space: type: string comment: type: string required: - channel - space - comment APIChannelCommentReplies: type: object properties: channel: type: string enum: - space-comment-replies space: type: string comment: type: string required: - channel - space - comment APIChannelIntegration: type: object properties: channel: type: string enum: - integration integration: type: string required: - channel - integration APIChannelIntegrationInstallation: type: object properties: channel: type: string enum: - integration-installation integration: type: string installation: type: string required: - channel - integration - installation APIChannelIntegrationSpaceInstallation: type: object properties: channel: type: string enum: - integration-space-installation integration: type: string installation: type: string space: type: string required: - channel - integration - installation - space APIChannelIntegrationSpaceInstallations: type: object properties: channel: type: string enum: - integration-space-installations integration: type: string installation: type: string required: - channel - integration - installation APIChannelIntegrationSiteInstallation: type: object properties: channel: type: string enum: - integration-site-installation integration: type: string installation: type: string site: type: string required: - channel - integration - installation - site APIChannelIntegrationSiteInstallations: type: object properties: channel: type: string enum: - integration-site-installations integration: type: string installation: type: string required: - channel - integration - installation APIChannelPublishedContentSite: type: object properties: channel: type: string enum: - published-content-site site: type: string required: - channel - site APIChannelSiteRedirects: type: object properties: channel: type: string enum: - site-redirects site: type: string required: - channel - site APIChannelSite: type: object properties: channel: type: string enum: - site site: type: string required: - channel - site APIChannelSiteChannels: type: object description: Subscription channel for changes in site channels. properties: channel: type: string enum: - site-channels site: type: string required: - channel - site APIChannelSiteContext: type: object description: Subscription channel for changes in site context. properties: channel: type: string enum: - site-context site: type: string required: - channel - site APIChannelSiteCustomization: type: object properties: channel: type: string enum: - site-customization site: type: string required: - channel - site APIChannelSiteAgentSettings: type: object properties: channel: type: string enum: - site-agent-settings site: type: string required: - channel - site APIChannelSiteIntegrations: type: object properties: channel: type: string enum: - site-integrations site: type: string required: - channel - site APIChannelSiteSpace: type: object properties: channel: type: string enum: - site-space site: type: string siteSpace: type: string required: - channel - site - siteSpace APIChannelSiteSpaceCustomization: type: object properties: channel: type: string enum: - site-space-customization site: type: string siteSpace: type: string required: - channel - site - siteSpace APIChannelSiteStructure: type: object description: Subscription channel for changes in site structure in an organization. properties: channel: type: string enum: - site-structure site: type: string required: - channel - site APIChannelSiteAdaptiveSchema: type: object properties: channel: type: string enum: - site-adaptive-schema site: type: string required: - channel - site APIChannelSitePublishingAuth: type: object properties: channel: type: string enum: - site-publishing-auth site: type: string required: - channel - site APIChannelSiteShareLinks: type: object description: Subscription channel for changes in share links in a site properties: channel: type: string enum: - site-share-links site: type: string required: - channel - site APIChannelSiteShareLink: type: object properties: channel: type: string enum: - site-share-link site: type: string siteShareLink: type: string required: - channel - site - siteShareLink APIChannelSiteMcpServers: type: object properties: channel: type: string enum: - site-mcp-servers site: type: string required: - channel - site APIChannelSiteMcpServer: type: object properties: channel: type: string enum: - site-mcp-server site: type: string siteMcpServer: type: string required: - channel - site - siteMcpServer APIChannelSiteSection: type: object properties: channel: type: string enum: - site-section site: type: string siteSection: type: string required: - channel - site - siteSection APIChannelCustomHostname: type: object properties: channel: type: string enum: - custom-hostname customHostname: type: string required: - channel - customHostname APIChannelGitSyncOperation: type: object properties: channel: type: string enum: - space-gitsync-operation space: type: string required: - channel - space APIChannelOpenAPISpec: type: object description: Subscription channel for changes in OpenAPI specification. properties: channel: type: string enum: - openapi-spec openAPISpec: type: string required: - channel - openAPISpec APIChannelSubdomain: type: object properties: channel: type: string enum: - subdomain subdomain: type: string required: - channel - subdomain APIChannelTranslation: type: object properties: channel: type: string enum: - translation translation: type: string required: - channel - translation APIChannelTranslationRun: type: object properties: channel: type: string enum: - translation-run translation: type: string required: - channel - translation APIChannelImportRun: type: object properties: channel: type: string enum: - import-run runId: type: string required: - channel - runId APIChannel: description: Channel to subscribe to for realtime updates. oneOf: - $ref: "#/components/schemas/APIChannelSpaceInfo" - $ref: "#/components/schemas/APIChannelSpaceContent" - $ref: "#/components/schemas/APIChannelSpaceGitInfo" - $ref: "#/components/schemas/APIChannelSpacePublishingAuth" - $ref: "#/components/schemas/APIChannelSpacePublishingCustomization" - $ref: "#/components/schemas/APIChannelSpaceContentRefs" - $ref: "#/components/schemas/APIChannelSpaceIntegrations" - $ref: "#/components/schemas/APIChannelUserAPITokens" - $ref: "#/components/schemas/APIChannelUserOrganizations" - $ref: "#/components/schemas/APIChannelUserProfile" - $ref: "#/components/schemas/APIChannelChangeRequest" - $ref: "#/components/schemas/APIChannelChangeRequests" - $ref: "#/components/schemas/APIChannelChangeRequestReviews" - $ref: "#/components/schemas/APIChannelChangeRequestContentRefs" - $ref: "#/components/schemas/APIChannelCollection" - $ref: "#/components/schemas/APIChannelCollectionPublishingCustomization" - $ref: "#/components/schemas/APIChannelOrganizationInfo" - $ref: "#/components/schemas/APIChannelOrganizationAgentData" - $ref: "#/components/schemas/APIChannelOrganizationInviteLinks" - $ref: "#/components/schemas/APIChannelOrganizationMembers" - $ref: "#/components/schemas/APIChannelOrganizationMember" - $ref: "#/components/schemas/APIChannelOrganizationSAML" - $ref: "#/components/schemas/APIChannelOrganizationTeams" - $ref: "#/components/schemas/APIChannelOrganizationTeam" - $ref: "#/components/schemas/APIChannelOrganizationTeamMembers" - $ref: "#/components/schemas/APIChannelOrganizationTeamMember" - $ref: "#/components/schemas/APIChannelOrganizationSpaces" - $ref: "#/components/schemas/APIChannelOrganizationCollections" - $ref: "#/components/schemas/APIChannelOrganizationIntegrations" - $ref: "#/components/schemas/APIChannelOrganizationInstallations" - $ref: "#/components/schemas/APIChannelOrganizationSites" - $ref: "#/components/schemas/APIChannelOrganizationOpenAPISpecs" - $ref: "#/components/schemas/APIChannelOrganizationTranslations" - $ref: "#/components/schemas/APIChannelOrganizationTranslationsGlossary" - $ref: "#/components/schemas/APIChannelOrganizationCustomFonts" - $ref: "#/components/schemas/APIChannelOrganizationAgentInstructions" - $ref: "#/components/schemas/APIChannelOrganizationChangeRequests" - $ref: "#/components/schemas/APIChannelSpaceComments" - $ref: "#/components/schemas/APIChannelChangeRequestComments" - $ref: "#/components/schemas/APIChannelCommentInfo" - $ref: "#/components/schemas/APIChannelCommentReplies" - $ref: "#/components/schemas/APIChannelIntegration" - $ref: "#/components/schemas/APIChannelIntegrationInstallation" - $ref: "#/components/schemas/APIChannelIntegrationSpaceInstallation" - $ref: "#/components/schemas/APIChannelIntegrationSpaceInstallations" - $ref: "#/components/schemas/APIChannelIntegrationSiteInstallation" - $ref: "#/components/schemas/APIChannelIntegrationSiteInstallations" - $ref: "#/components/schemas/APIChannelPublishedContentSite" - $ref: "#/components/schemas/APIChannelSiteRedirects" - $ref: "#/components/schemas/APIChannelSite" - $ref: "#/components/schemas/APIChannelSiteChannels" - $ref: "#/components/schemas/APIChannelSiteContext" - $ref: "#/components/schemas/APIChannelSiteCustomization" - $ref: "#/components/schemas/APIChannelSiteAgentSettings" - $ref: "#/components/schemas/APIChannelSiteIntegrations" - $ref: "#/components/schemas/APIChannelSiteSpace" - $ref: "#/components/schemas/APIChannelSiteSpaceCustomization" - $ref: "#/components/schemas/APIChannelSiteStructure" - $ref: "#/components/schemas/APIChannelSiteAdaptiveSchema" - $ref: "#/components/schemas/APIChannelSitePublishingAuth" - $ref: "#/components/schemas/APIChannelSiteShareLinks" - $ref: "#/components/schemas/APIChannelSiteShareLink" - $ref: "#/components/schemas/APIChannelSiteMcpServers" - $ref: "#/components/schemas/APIChannelSiteMcpServer" - $ref: "#/components/schemas/APIChannelSiteSection" - $ref: "#/components/schemas/APIChannelCustomHostname" - $ref: "#/components/schemas/APIChannelGitSyncOperation" - $ref: "#/components/schemas/APIChannelOpenAPISpec" - $ref: "#/components/schemas/APIChannelSubdomain" - $ref: "#/components/schemas/APIChannelTranslation" - $ref: "#/components/schemas/APIChannelTranslationRun" - $ref: "#/components/schemas/APIChannelImportRun" discriminator: propertyName: channel APIChannelTranslationRunData: type: object properties: channel: type: string enum: - translation-run data: type: object properties: progress: type: number description: The progress of the translation run, between 0 and 100. startedAt: $ref: "#/components/schemas/Timestamp" updatedAt: $ref: "#/components/schemas/Timestamp" required: - progress - startedAt - updatedAt required: - channel - data APIChannelImportRunData: type: object properties: channel: type: string enum: - import-run data: $ref: "#/components/schemas/ContentImportRun" required: - channel - data APIChannelGitSyncOperationData: type: object properties: channel: type: string enum: - space-gitsync-operation data: $ref: "#/components/schemas/GitSyncOperation" required: - channel - data APIChannelSpaceContentRefsData: type: object properties: channel: type: string enum: - space-content-refs data: type: object description: Data passed on the channel messages for content refs indexation. properties: revision: type: string description: ID of the latest indexed revision updatedAt: type: number required: - revision - updatedAt required: - channel - data APIChannelChangeRequestContentRefsData: type: object properties: channel: type: string enum: - space-change-request-content-refs data: type: object description: Data passed on the channel messages for content refs indexation. properties: revision: type: string description: ID of the latest indexed revision updatedAt: type: number required: - revision - updatedAt required: - channel - data APIChannelMutationData: type: object properties: channel: type: string enum: - "*" data: type: object description: Data passed on the channels associated to API endpoints. properties: executionId: type: string description: ID of the API execution that triggered the mutation. required: - executionId required: - channel - data APIChannelData: description: Data passed through a realtime channel oneOf: - $ref: "#/components/schemas/APIChannelGitSyncOperationData" - $ref: "#/components/schemas/APIChannelSpaceContentRefsData" - $ref: "#/components/schemas/APIChannelChangeRequestContentRefsData" - $ref: "#/components/schemas/APIChannelTranslationRunData" - $ref: "#/components/schemas/APIChannelImportRunData" - $ref: "#/components/schemas/APIChannelMutationData" discriminator: propertyName: channel CustomizationThemeMode: type: string enum: - light - dark SiteAdaptiveDeterministicJSONSchemaClaimsProperties: oneOf: - $ref: "#/components/schemas/SiteAdaptiveDeterministicJSONSchemaPrimitives" - type: object properties: type: type: string enum: - object description: type: string properties: type: object additionalProperties: $ref: "#/components/schemas/SiteAdaptiveDeterministicJSONSchemaClaimsProperties" additionalProperties: type: boolean enum: - false required: - type - description - properties - additionalProperties additionalProperties: false SiteAdsStatus: type: string description: The status of ads on the site enum: - pending - in-review - live - rejected - disabled SiteChannelType: oneOf: - $ref: "#/components/schemas/SiteCoreChannelType" - $ref: "#/components/schemas/SiteConfigurableChannelType" SiteQuestionAnswerSourceType: type: string description: Source type used to answer a site question. enum: - page - record Seat: type: object properties: object: type: string enum: - seat organization: description: The unique ID of the organization type: string member: description: The unique ID of the organization member type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - object - organization - member - createdAt - updatedAt AgentStreamMessages: type: object description: | Payload emitted by the agent to reset the messages. properties: type: type: string enum: - messages operation: type: string enum: - append - replace messages: type: array items: $ref: "#/components/schemas/AIMessage" required: - type - operation - messages AgentStreamMessageResponse: type: object description: | Payload emitted by the agent with a partial message. properties: type: type: string enum: - message_response response: $ref: "#/components/schemas/AIStreamResponse" required: - type - response AgentStatus: type: string enum: - idle - processing - errored AgentState: type: object properties: status: $ref: "#/components/schemas/AgentStatus" suggestions: type: array description: A list of response suggestions for the user to select from. items: type: string required: - status - suggestions AgentStreamState: type: object description: | Payload emitted by the agent with its current state. properties: type: type: string enum: - state state: $ref: "#/components/schemas/AgentState" required: - type - state AgentStreamRPC: type: object description: | Payload emitted by the agent is responding to a RPC call. properties: type: type: string enum: - rpc message: oneOf: - type: string - type: object required: - type - message AgentStream: oneOf: - $ref: "#/components/schemas/AgentStreamMessages" - $ref: "#/components/schemas/AgentStreamMessageResponse" - $ref: "#/components/schemas/AgentStreamState" - $ref: "#/components/schemas/AgentStreamRPC" MergeRulesEvaluationContext: type: object description: Context available when evaluating merge rules expressions. properties: space: $ref: "#/components/schemas/Space" changeRequest: $ref: "#/components/schemas/ChangeRequest" reviews: description: The reviews posted on the change request. type: array items: $ref: "#/components/schemas/ChangeRequestReview" actor: description: The user who is attempting to merge the change request. $ref: "#/components/schemas/User" required: - space - changeRequest - reviews - actor LocalizedContentRef: description: Localized content reference, keyed by locale. Contains overrides for non-default languages only. type: object additionalProperties: $ref: "#/components/schemas/ContentRef" propertyNames: $ref: "#/components/schemas/TranslationLanguage" RequestSpaceTrackPageView: $ref: "#/components/schemas/SpaceTrackPageView" RequestSiteTrackPageView: $ref: "#/components/schemas/SiteTrackPageView" RequestPublishIntegration: $ref: "#/components/schemas/PublishIntegration" RequestUpdateIntegrationInstallation: $ref: "#/components/schemas/UpdateIntegrationInstallation" RequestUpdateIntegrationSpaceInstallation: $ref: "#/components/schemas/UpdateIntegrationSpaceInstallation" RequestUpdateIntegrationSiteInstallation: $ref: "#/components/schemas/UpdateIntegrationSiteInstallation" RequestUpgradeOrganizationBilling: $ref: "#/components/schemas/UpgradeOrganizationBilling" RequestInviteUsersToOrganization: $ref: "#/components/schemas/InviteUsersToOrganization" RequestImportGitRepository: $ref: "#/components/schemas/ImportGitRepository" RequestExportToGitRepository: $ref: "#/components/schemas/ExportToGitRepository" RequestCreateSpace: $ref: "#/components/schemas/CreateSpace" RequestRenderIntegrationUI: $ref: "#/components/schemas/RenderIntegrationUI" RequestUpdateContentPublishingAuth: $ref: "#/components/schemas/UpdateContentPublishingAuth" RequestCreateOrganization: $ref: "#/components/schemas/CreateOrganization" RequestUpdateSpaceGitInfo: $ref: "#/components/schemas/UpdateSpaceGitInfo" RequestPurgeCDNCacheContext: $ref: "#/components/schemas/PurgeCDNCacheContext" DocumentTextBackgroundColor: $ref: "#/components/schemas/DocumentTextColor" SpaceVisitorAuth: $ref: "#/components/schemas/VisitorAuth" SpaceVisitorAuthCustomBackend: $ref: "#/components/schemas/VisitorAuthCustomBackend" SpaceVisitorAuthIntegrationBackend: $ref: "#/components/schemas/VisitorAuthIntegrationBackend" IngegrationPropertyTitle: $ref: "#/components/schemas/IntegrationPropertyTitle" UserPermissions: $ref: "#/components/schemas/_index" SiteRedirectDestinationSpace: $ref: "#/components/schemas/SiteRedirectDestinationSiteSpace" OpenAPISpecSourceURL: $ref: "#/components/schemas/URL" responses: NotFoundError: description: Not Found content: application/json: schema: type: object required: - error properties: error: type: object properties: code: type: integer format: int32 enum: - 404 message: type: string required: - code - message 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 ConflictError: description: Conflict content: application/json: schema: type: object required: - error properties: error: type: object properties: code: type: integer format: int32 enum: - 409 message: type: string required: - code - message PreconditionFailedError: description: PreconditionFailed content: application/json: schema: type: object required: - error properties: error: type: object properties: code: type: integer format: int32 enum: - 412 message: type: string required: - code - message UnexpectedError: description: Unexpected Error content: application/json: schema: $ref: "#/components/schemas/Error"