{ "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": [] }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Organization\" grouped=\"false\" %}\n The Organization object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Site\" grouped=\"false\" %}\n The Site object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ShareLink\" grouped=\"false\" %}\n The ShareLink object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteStructure\" grouped=\"false\" %}\n The SiteStructure object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SitePublishingAuth\" grouped=\"false\" %}\n The SitePublishingAuth object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteCustomizationSettings\" grouped=\"false\" %}\n The SiteCustomizationSettings object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteAgentSettings\" grouped=\"false\" %}\n The SiteAgentSettings object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteSpace\" grouped=\"false\" %}\n The SiteSpace object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteSection\" grouped=\"false\" %}\n The SiteSection object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteSectionGroup\" grouped=\"false\" %}\n The SiteSectionGroup object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteRedirect\" grouped=\"false\" %}\n The SiteRedirect object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteMcpServer\" grouped=\"false\" %}\n The SiteMcpServer object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteChannel\" grouped=\"false\" %}\n The SiteChannel object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ContextRecord,ContextConnection,SiteTopic,SiteFinding,SiteFindingPage\" grouped=\"false\" %}\n The Site Context objects\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"SiteQuestion,SiteQuestionAnswer,SiteQuestionAnswerWithResponse,SiteQuestionAnswerSource\" grouped=\"false\" %}\n The Site Questions objects\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Collection\" grouped=\"false\" %}\n The Collection object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Space\" grouped=\"false\" %}\n The Space object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Comment\" grouped=\"false\" %}\n The Comment object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequest\" grouped=\"false\" %}\n The ChangeRequest object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"UserContributor\" grouped=\"false\" %}\n The UserContributor object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"ChangeRequestRequestedReviewer\" grouped=\"false\" %}\n The ChangeRequestRequestedReviewer object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Comment\" grouped=\"false\" %}\n The Comment object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TranslationLanguageSettings\" grouped=\"false\" %}\n The TranslationLanguageSettings object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"GlossaryEntry\" grouped=\"false\" %}\n The GlossaryEntry object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpec\" grouped=\"false\" %}\n The OpenAPISpec object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"OpenAPISpecVersion\" grouped=\"false\" %}\n The OpenAPISpecVersion object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomizationFontDefinition\" grouped=\"false\" %}\n The CustomizationFontDefinition object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Subdomain\" grouped=\"false\" %}\n The Subdomain object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"User\" grouped=\"false\" %}\n The User object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Team\" grouped=\"false\" %}\n The Team object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"TeamMember\" grouped=\"false\" %}\n The TeamMember object\n{% endopenapi-schemas %}\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"Subdomain\" grouped=\"false\" %}\n The Subdomain object\n{% endopenapi-schemas %}\n" }, { "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.\n" }, { "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.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomHostname\" grouped=\"false\" %}\n The CustomHostname object\n{% endopenapi-schemas %}\n" }, { "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.\n" } ], "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": [] }, { "oauth": [ "user:read" ] } ], "description": "Returns details about the user associated with the authentication provided in the request's authorization header.\n", "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.\n", "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.\n", "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.\n", "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 full details of a space by its ID", "description": "Returns the full metadata for a space. Use this to resolve a spaceId into a complete Space object. If you only need content, use the content endpoint instead.", "x-gitbook-mcp": true, "tags": [ "spaces", "critical" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "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's title, icon, or settings", "description": "Updates a space's metadata and settings. To update page content, use the change-request workflow instead.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": "Create a full copy of a space", "description": "Creates a new space that is a complete copy of the specified space, including all pages and their content. The duplicate is created in the same organization. Returns the newly created space. Use this to create a template-based copy or to snapshot a space before making large changes.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 recently deleted space from the trash", "description": "Restores a previously deleted space, making it active again. Only spaces deleted within the last 7 days can be restored; after that they are permanently removed. Returns the restored space object. To delete a space, use the space delete endpoint.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 different collection or position", "description": "Moves a space to a new parent collection and/or a new position within the hierarchy.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 oEmbed object within a space", "description": "Resolves an external URL to an oEmbed representation (title, thumbnail, HTML snippet) within the context of a space. Use this to preview or embed third-party content referenced in a space's pages. Requires the URL as a query parameter.", "x-gitbook-mcp": true, "tags": [ "space-embeds" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Full-text search across all pages in a space", "description": "Searches the full text of all published pages in a space and returns matching pages with ranked excerpts. Use this to find pages by topic or keyword within a specific space. For site-wide search across all spaces in a site, use the site search endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Pull content into a space from a connected Git repository", "description": "Triggers an import from the linked Git repository into the space, updating the space's content to match the repository. This is an async operation — it runs in the background after the request returns 204. Use getSpaceGitInfo to check sync status. The space must already have a Git provider configured.", "x-gitbook-mcp": true, "tags": [ "space-git" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:write" ] } ], "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": "Push space content to a connected Git repository", "description": "Triggers an export of the space's current content to the linked Git repository. This is an async operation — the export runs in the background after the request returns 204. Use getSpaceGitInfo to check the current git sync status. The space must already have a Git provider configured.", "x-gitbook-mcp": true, "tags": [ "space-git" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:write" ] } ], "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 the Git Sync configuration and status for a space", "description": "Returns metadata about the Git Sync provider connected to the space. Returns 404 if no Git provider is configured. Use this to check sync state before triggering an import or export.", "x-gitbook-mcp": true, "tags": [ "space-git" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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 the current published content revision of a space", "description": "Retrieves the live published revision of a space, which includes the full page tree structure and associated files. Use this to inspect the currently published content state of a space. For in-progress edits, use the change-request content endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "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 content template to populate a space with initial pages", "description": "Populates a space with pages and structure from a specified template, bootstrapping it with a standard documentation layout. Use this to initialise a new space rather than creating pages manually. Optionally apply the template to a specific change request instead of main content by providing the changeRequestId field.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 pages in a space with their hierarchy and metadata", "description": "Returns the complete list of all pages in a space's current revision, including their titles, URL paths, and parent-child relationships. Use this to understand the full content structure of a space or build navigation. For the content of a single page, use getPageById or getPageByPath instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 uploaded files and assets in a space", "description": "Returns a paginated list of all files (images, attachments, and other assets) uploaded to a space's current revision. Use this to discover available assets or audit file usage across a space.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 specific uploaded file from a space by its ID", "description": "Retrieves metadata and download URL for a single file (image, attachment, or other asset) in a space's current revision by its file ID. Use this when you have a specific file ID and need its URL, MIME type, or other metadata.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 pages in a space that reference a specific file", "description": "Returns the content locations (pages and inline positions) within the space that link to or embed the specified file. Use this to find where an asset is used before deleting or replacing it.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 single page from a space by its ID", "description": "Retrieves a page's metadata, content, and document structure from a space's current revision by its page ID. Use this when you know the exact page ID and need its content or path. For lookup by URL path, use the content/path endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 outbound links from a specific page in a space", "description": "Returns all content references (internal links, cross-space links, and external URLs) originating from the specified page. Use this to audit link health or detect broken references on a page.", "x-gitbook-mcp": true, "tags": [ "space-content", "links", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 pages in a space that link to a specific page", "description": "Returns the content locations (pages and inline positions) within the space that contain links pointing to the specified page. Use this to understand a page's incoming references before moving, deleting, or renaming it.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Get navigation metadata links for a page (previous, next, parent)", "description": "Returns structural navigation metadata for a page, including references to the previous page, next page, and parent page within the space's hierarchy. Use this to implement or inspect linear navigation flows in a docs site without fetching the full page tree.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 page from a space by its URL path", "description": "Retrieves a page by its URL path (e.g. /guides/getting-started) from the space's current revision. Use this when you have a page's path rather than its ID. Returns either a document page or a group/section page depending on the path.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 reusable content block from a space by its ID", "description": "Retrieves a reusable content block (a shared snippet that can be embedded across multiple pages) from a space's current revision by its ID. Use this to read the content of a reusable block when you have its ID. To find which pages reference it, check the page backlinks endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Compute and render a document from a structured content source", "description": "Server-renders a document from a provided content source definition, evaluating template expressions and resolving variables to produce a fully computed document. Use this to preview how dynamic content will look without publishing a full revision.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Compute and render a full revision from a structured content source", "description": "Server-renders an entire revision — pages, files, and reusable contents — from a provided content source definition, resolving all template expressions and variables. Use this to evaluate and preview computed content before publishing. Returns the full set of pages and files with all dynamic content fully resolved.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 raw document from a space by its document ID", "description": "Returns the structured JSON document for a specific document ID within a space. Documents are the low-level block-based representation of page content. Use this when you have a documentId and need the raw block structure. To retrieve a page's document by pageId, use the page document endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 new change request in a space", "description": "Creates a new change request, which is a draft working copy of the space's content — similar to a Git branch or pull request. Use this before making content edits to avoid modifying the live published content directly. Optionally supply a subject and a template to pre-populate the change request with content. Once created, use the change-request content endpoints to read and modify pages within the draft, then merge it when ready.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 for a space", "description": "Returns a paginated list of change requests for the given space. Use this to discover existing change requests before creating a new one, or to find change requests assigned to a specific user for review.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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", "description": "Retrieves the full details of a single change request, including its status, subject, description, and metadata. Use this to check the current state of a change request before deciding to merge, update, or request a review.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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's subject, description, or status", "description": "Updates the metadata of a change request. Use this to rename a change request, add context before requesting a review, or change the workflow status without merging. To update page content within the change request, use the content endpoint instead.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 into the space's live content", "description": "Merges the change request's draft content into the space's primary (published) content, making all changes live. If the result is \"conflicts\", the merge was still applied but the space may need manual conflict resolution. Consider running updateChangeRequest first to sync with the latest live content and reduce conflicts.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "change-request:merge" ] } ], "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": "Sync a change request with the latest live space content", "description": "Rebases the change request onto the latest primary revision of the space, pulling in any changes that were merged to the live space since this change request was created. Run this before merging to minimise conflicts, especially if the change request has been open for a while.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 formal reviews submitted for a change request", "description": "Returns a paginated list of reviews submitted for the change request. Use this to check the current review status and whether all requested reviewers have responded before merging.", "x-gitbook-mcp": true, "tags": [ "change-requests-reviews" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 an approve or request-changes review for a change request", "description": "Submits a formal review decision (approved or changes-requested) on the change request, optionally with a rich-text comment. Use this to complete a review you were requested to perform. Only users who are requested reviewers or have space review permissions can submit a review.", "x-gitbook-mcp": true, "tags": [ "change-requests-reviews" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 specific review on a change request by its ID", "description": "Retrieves the full details of a single review submission on a change request, including the decision status (approved/changes-requested), reviewer, and any attached comment. Use this when you have a review ID and need its full details.", "x-gitbook-mcp": true, "tags": [ "change-requests-reviews" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "List all users requested to review a change request", "description": "Returns a paginated list of users who have been explicitly requested to review the change request. Use this to check who is currently assigned as a reviewer before adding or removing reviewer requests.", "x-gitbook-mcp": true, "tags": [ "change-request-reviewers" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Send review requests to users for a change request", "description": "Sends review request notifications to one or more users, asking them to review the change request. Optionally updates the change request subject and description at the same time. Use this to move the change request into the review workflow after finishing edits. The users array must contain at least one valid user ID.", "x-gitbook-mcp": true, "tags": [ "change-request-reviewers" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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}/conversations": { "get": { "operationId": "listChangeRequestConversations", "summary": "List AI agent conversations associated with a change request", "description": "Returns a paginated list of AI agent conversations that were created in the context of this change request. These conversations capture the AI-assisted editing sessions that contributed to the draft. Use this to review the history of AI interactions on a change request before merging.", "x-gitbook-mcp": true, "tags": [ "change-request-conversations" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "A list of agent conversations", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConversation" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/conversations/{conversationId}": { "patch": { "operationId": "updateChangeRequestConversation", "summary": "Update the title of an AI agent conversation on a change request", "description": "Updates the title of a specific AI agent conversation associated with a change request. Use this to give a descriptive name to an AI editing session for easier reference.", "x-gitbook-mcp": true, "tags": [ "change-request-conversations" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/conversationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The new title of the conversation." } }, "required": [ "title" ] } } } }, "responses": { "200": { "description": "The updated conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConversation" } } } } } }, "delete": { "operationId": "deleteChangeRequestConversation", "summary": "Delete an agent conversation", "tags": [ "change-request-conversations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/conversationId" } ], "responses": { "205": { "description": "The conversation has been deleted." } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/links": { "get": { "operationId": "listChangeRequestLinks", "summary": "List all content references across an entire change request", "description": "Returns a paginated list of all outbound content references (links) across all pages in the change request. Use this to audit link health across the entire draft before merging.", "x-gitbook-mcp": true, "tags": [ "change-requests-links", "links", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 top-level comments in a change request", "description": "Returns a paginated list of comments posted on the change request, optionally filtered by status, target page, or author. Comments can be anchored to a specific page or be general change-request-level comments. Use this to read the review discussion before responding. To fetch replies to a comment, use the comment replies endpoint.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Post a new comment on a change request", "description": "Posts a new top-level comment on the change request. Comments can be general or anchored to a specific page and inline location within the change request content. Use this to provide review feedback, ask questions, or flag issues. To reply to an existing comment, use the comment replies endpoint instead.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 single comment from a change request by its ID", "description": "Retrieves a specific comment from a change request, including its content, author, and anchor location. Use this when you have a comment ID (e.g., from a notification or list) and need its full details.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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 the content or status of a change request comment", "description": "Replaces the body or status of an existing change request comment. Use this to edit the text of a comment you previously posted, or to resolve/reopen a comment thread. Only the comment author or space admins can update a comment.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 replies to a change request comment", "description": "Returns a paginated list of replies to a specific top-level comment in a change request. Use this to read the full thread of a review discussion on a particular comment before adding a reply.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Post a reply to a change request comment", "description": "Adds a reply to an existing comment thread on a change request. Use this to respond to review feedback or continue a discussion on a specific comment. To start a new top-level comment rather than replying, use the change request comments endpoint.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 single reply to a change request comment", "description": "Retrieves a specific reply within a change request comment thread. Use this when you have a reply ID and need its full content and author details.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 the content of a change request comment reply", "description": "Replaces the body of an existing reply in a change request comment thread. Use this to correct or amend a reply you previously posted. Only the reply author or space admins can update a reply.", "x-gitbook-mcp": true, "tags": [ "change-request-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": "List all users who have made edits to a change request", "description": "Returns a list of users who have contributed content edits to the change request. Use this to identify who has been actively editing the draft, for example when deciding who to notify before merging.", "x-gitbook-mcp": true, "tags": [ "change-request-contributors" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 the latest content revision of a change request", "description": "Returns the current revision snapshot of the change request, including the full page tree structure and metadata. Use this to inspect the overall state of the change request's content, such as the list of pages and their hierarchy, without fetching each page individually. For page content (body text), use the individual page endpoints.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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" } } } } } }, "post": { "operationId": "updateChangeRequestContent", "summary": "Apply a batch of content changes to a change request", "description": "Applies an ordered array of content changes (up to 50) to the change request atomically, creating a single new revision. Changes are applied sequentially; if any single change is invalid the entire batch is rejected and no revision is created. Use this to create, update, move, or delete pages within a change request before merging to live. This is the primary way to programmatically author content in a change request.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "changes" ], "properties": { "changes": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ChangeRequestContentChange" } } } } } } }, "responses": { "200": { "description": "The change request has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } } }, "404": { "description": "The change request could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/pages": { "get": { "operationId": "listPagesInChangeRequest", "summary": "List all pages in a change request as a flat list", "description": "Returns the full flat list of all pages in the change request's current draft revision, including page groups. Does not include page body content — use the individual page endpoint to fetch content. Use this to get an overview of the draft's page structure before reading or modifying specific pages.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 files (images/attachments) in a change request", "description": "Returns a paginated list of files (images and other attachments) stored in the change request's current revision. Use this to inspect uploaded assets within a draft before merging. For files in the live published space, use the space content files endpoint.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 specific file in a change request by its ID", "description": "Retrieves metadata for a single file (image or attachment) stored in the change request's current revision. Use this to get the download URL or details of a specific asset referenced by a page in the change request.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 pages in a change request that reference a file", "description": "Returns a paginated list of content locations (pages and inline positions) within the change request that link to or embed the specified file. Use this to find all usages of an asset before renaming or removing it.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 page in a change request by its ID", "description": "Retrieves a specific page from a change request's draft content, including its title, metadata, and body document. Use the documentFormat parameter to control the format of the returned document (e.g., markdown). This reflects the draft state of the page, not the live published version — use the space content page endpoint for live content.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 content references (links) on a change request page", "description": "Returns all outbound content references from a specific page within the change request, including their status (valid, broken) and usage context. Use this to audit link health on a draft page before merging. Also returns aggregate stats about broken vs healthy references on the page.", "x-gitbook-mcp": true, "tags": [ "change-request-content", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 pages in a change request that link to a specific page", "description": "Returns a paginated list of content locations within the change request that contain links pointing to the specified page. Use this to check what pages would be affected by renaming or removing a page before applying the change.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Get navigation meta-links (prev/next/parent) for a change request page", "description": "Returns the structural navigation links for a specific page within a change request, such as its parent page, previous sibling, and next sibling in the page tree. Use this to understand a page's position within the content hierarchy of the draft.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 reusable content block in a change request by its ID", "description": "Retrieves a specific reusable content block (a shared snippet that can be embedded across multiple pages) from the change request's draft revision. Use this to inspect the current draft state of a shared content block before merging.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "List semantic content changes in a change request vs its base", "description": "Returns the semantic diff between the change request's current content and the base revision it branched from. Each item describes a logical change such as a page added, removed, or modified. Use this to summarise what a change request changes before merging or reviewing. The default limit is 10 — increase it if the change request is large.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 temporary URL to download a change request's content as PDF", "description": "Generates a temporary URL (valid for 1 hour) to download the change request's draft content as a PDF. Optionally scope the export to a single page using the page and only parameters. Use this to share or archive the draft content before merging.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 specific historical revision of a space", "description": "Returns a specific revision snapshot of a space by its revision ID, including the page tree structure and revision metadata. Use this to inspect a historical state of a space. To access the current live content, use the space content endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "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 semantic content changes introduced by a revision", "description": "Returns a structured diff of the semantic changes introduced by a revision compared to its parent revision, such as added, removed, or updated pages and blocks. Use this to understand what changed in a specific revision.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "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 specific historical revision of a space", "description": "Returns the full flat list of all pages (document pages and group pages) in a specific historical revision of a space. Use this to inspect the complete page tree of a past snapshot. For the current live content pages, use the space content pages endpoint.", "x-gitbook-mcp": true, "operationId": "listPagesInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 files (images, assets) in a specific space revision", "description": "Returns a paginated list of files (images and other binary assets) attached to a specific revision of a space. Use this to enumerate all media assets present in a historical snapshot. To get a single file, use the revision file by ID endpoint.", "x-gitbook-mcp": true, "operationId": "listFilesInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 specific file from a space revision by its file ID", "description": "Returns the metadata for a single file (image or binary asset) within a specific revision of a space. Use this to retrieve download URL, MIME type, and dimensions for a known file ID. To list all files in a revision, use the revision files list endpoint.", "x-gitbook-mcp": true, "operationId": "getFileInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 page from a specific historical revision by its page ID", "description": "Returns the full page object (metadata and optionally document content) for a specific page within a historical revision. Use documentFormat to control whether content is returned as blocks or markdown. To get a page from the current live revision, use the space content page endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 raw document body of a page in a historical revision", "description": "Returns the structured JSON document (block tree) for a specific page within a historical revision of a space. Use this when you need the low-level block representation of historical page content. For the current live content, use the space content page document endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 page from a specific historical revision by its URL path", "description": "Returns a page from a historical revision looked up by its URL path (e.g. \"getting-started/installation\") rather than its ID. Useful when you know the page path but not the ID. Use documentFormat to control whether content is returned as blocks or markdown. For the current live revision, use the content path endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 (prev/next navigation) for a page in a revision", "description": "Returns the meta navigation links for a specific page within a historical revision, including the previous and next page in the space's reading order. Use this to implement sequential navigation across historical content or to build a reading flow for a specific revision.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 page in a change request by its URL path", "description": "Retrieves a specific page from a change request's draft content using its URL path (e.g., \"getting-started/installation\") rather than its ID. Use this when you know the path of a page but not its ID. Returns either a document page or a page group, depending on the path. Supports the same format and evaluation options as the ID-based endpoint.", "x-gitbook-mcp": true, "tags": [ "change-request-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/documentMarkdownRefsFormat" }, { "$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 reusable content block from a historical revision by its ID", "description": "Returns metadata for a specific reusable content block within a historical revision of a space. Reusable content blocks are shared content snippets referenced across multiple pages. To get the actual document body of the reusable content, use the reusable content document endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 body of a reusable content block in a historical revision", "description": "Returns the structured JSON document (block tree) for a reusable content block within a specific historical revision of a space. Use this to read the actual content of a shared snippet at a point in time. For the metadata, use the reusable content by ID endpoint.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 top-level comments posted on a space", "description": "Returns a paginated list of comments posted directly on the space (not inside a change request). To read replies to a specific comment, use the comment replies endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Post a new comment on a space or a specific page", "description": "Creates a new top-level comment on the space, optionally anchored to a specific page or a text selection within a page. Use this to leave feedback, start a review thread, or annotate content. To reply to an existing comment, use the comment replies endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 single comment from a space by its ID", "description": "Returns a specific comment posted on a space. To list all comments in a space, use the space comments list endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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 the body or status of a space comment", "description": "Updates the content or resolution status of an existing comment on a space. Only the comment author or a space admin can update a comment. Use this to edit a comment's text, mark it as resolved, or reopen it.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 replies to a comment in a space", "description": "Returns a paginated list of replies posted under a specific comment in a space. Use this to read the full conversation thread for a comment. To get the parent comment itself, use the space comment by ID endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comment" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "Post a reply to an existing space comment", "description": "Creates a reply to an existing comment on a space. Use this to continue a discussion thread started by a top-level comment. To start a new thread, use the space comment creation endpoint instead.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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 single reply to a space comment by its ID", "description": "Returns a specific reply to a comment in a space. To list all replies for a comment, use the comment replies list endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 the body of a reply to a space comment", "description": "Updates the content of an existing reply to a comment in a space. Only the reply author or a space admin can update the reply. To update the parent comment, use the space comment update endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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 have posted comments in a space", "description": "Returns a paginated list of organization members who have posted at least one comment in the space. Use this to identify participants in a space's review or annotation workflow. For the actual comment content, use the space comments endpoint.", "x-gitbook-mcp": true, "tags": [ "space-comments", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 have commented in a change request", "description": "Returns a paginated list of organization members who have posted at least one comment in the change request. Use this to identify who is actively engaged in the review discussion before adding or directing comments.", "x-gitbook-mcp": true, "tags": [ "change-request-comments", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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 all third-party integrations enabled on a space", "description": "Returns a paginated list of integrations that are currently installed and enabled on the space. Use the query parameter to filter by integration name. Use this to check which integrations are active before interacting with integration-specific features or blocks.", "x-gitbook-mcp": true, "tags": [ "space-integrations" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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 custom content blocks provided by integrations in a space", "description": "Returns all custom block types contributed by integrations installed on the space. Integration blocks are custom content elements (e.g. embedded widgets, code runners) that integrations register for use in pages. Use this to discover what custom block types are available in a given space.", "x-gitbook-mcp": true, "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 temporary URL to download a space or page as PDF", "description": "Returns a short-lived URL (valid for 1 hour) to download the space's content as a PDF file.", "x-gitbook-mcp": true, "tags": [ "space-content" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "List all links in a space with their status and location", "description": "Returns a paginated list of all internal and external links found in the space's content. Use this to audit link health across an entire space.", "x-gitbook-mcp": true, "tags": [ "spaces", "links", "critical" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:write" ] } ], "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": [] }, { "oauth": [ "space:permissions:read" ] } ], "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": [] }, { "integration-installation": [] } ], "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": [] }, { "integration-installation": [] } ], "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.\n" } }, "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": [] }, { "integration": [] }, { "integration-installation": [] } ], "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": [] }, { "integration": [] }, { "integration-installation": [] } ], "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.\n", "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", "x-gitbook-mcp": true, "tags": [ "organizations", "critical" ], "security": [ { "user": [] }, { "oauth": [ "organization:read" ] } ], "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", "x-gitbook-mcp": true, "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", "x-gitbook-mcp": true, "tags": [ "organizations" ], "security": [ { "user": [] }, { "oauth": [ "organization:write" ] } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" }, { "$ref": "#/components/parameters/memberRoleFilter" }, { "$ref": "#/components/parameters/memberSearch" }, { "$ref": "#/components/parameters/memberSort" } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "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": [] }, { "oauth": [ "organization:members:write" ] } ], "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": [] }, { "oauth": [ "organization:members:write" ] } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "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": [] }, { "oauth": [ "organization:members:write" ] } ], "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": [] }, { "oauth": [ "organization:members:read" ] } ], "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": [] }, { "oauth": [ "organization:members:write" ] } ], "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": [] }, { "oauth": [ "organization:members:write" ] } ], "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.\n", "tags": [ "team-members" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMembersInOrganizationTeam" } } } }, "responses": { "204": { "description": "Members have been updated" } } }, "get": { "operationId": "listTeamMembersInOrganizationById", "summary": "List all team members", "description": "Lists members, and their roles, for the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationTeamMember" } } } } ] } } } } } } }, "/orgs/{organizationId}/teams/{teamId}/members/{userId}": { "put": { "operationId": "addMemberToOrganizationTeamById", "summary": "Add a team member", "description": "Add or updates member in the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/TeamMemberRole" } } } } } }, "responses": { "204": { "description": "Member has been added to the team" } } }, "delete": { "operationId": "deleteMemberFromOrganizationTeamById", "summary": "Delete a team member", "description": "Deletes member from the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Member was not part of the team" }, "205": { "description": "Member has been deleted from the team" } } } }, "/orgs/{organizationId}/invites": { "post": { "operationId": "inviteUsersToOrganization", "summary": "Invite users in an organization", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "string", "description": "The unique identifiers of the users who were added to the organization" } }, "invited": { "type": "number", "description": "The number of users who were added to the organization" }, "failedSSOEmails": { "type": "array", "items": { "type": "string", "description": "A list of emails who were invited to the organization, but who were not added as SSO users as they are members of another org" } } }, "required": [ "users", "invited" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersToOrganization" } } } } } }, "/orgs/{organizationId}/invites/{inviteId}": { "post": { "operationId": "joinOrganizationWithInvite", "summary": "Join an organization with an invite", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/orgs/{organizationId}/link-invites": { "get": { "operationId": "listOrganizationInviteLinks", "summary": "List organization invites", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "List of invite links in the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InviteLinkToOrganization" } } } } ] } } } } } }, "post": { "operationId": "createOrganizationInvite", "summary": "Create an organization invite", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInvite" } } } }, "responses": { "201": { "description": "The organization invite has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } } }, "/orgs/{organizationId}/link-invites/{inviteId}": { "get": { "operationId": "getOrganizationInviteLink", "summary": "Get an organization by its ID", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "responses": { "200": { "description": "Invite link in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } }, "patch": { "operationId": "updateOrganizationInviteById", "summary": "Update an organization invite", "tags": [ "organization-invites" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Update role of an organization invite", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "required": [ "role" ] }, { "type": "object", "description": "Update level of an organization content invite", "properties": { "level": { "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "required": [ "level" ] } ] } } } }, "responses": { "200": { "description": "The organization invite has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } }, "delete": { "operationId": "deleteOrganizationInviteById", "summary": "Deletes an organization invite.", "tags": [ "organizations" ], "security": [ { "user": [] }, { "oauth": [ "organization:members:write" ] } ], "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", "x-gitbook-mcp": true, "description": "Join an organization if the user's verified email domain matches one of the organization's allowed email domains.\nThis endpoint allows existing users to join organizations they're eligible for based on their email domain.\n", "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", "x-gitbook-mcp": true, "tags": [ "organizations" ], "security": [ { "user": [] }, { "oauth": [ "organization:search" ] } ], "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 across an entire organization", "description": "Returns a paginated list of change requests across all spaces in the organization. Use this for an organization-wide view of open drafts — for example, to find all change requests needing a specific reviewer's attention. For a single space's change requests, use the space-scoped endpoint instead.", "x-gitbook-mcp": true, "tags": [ "change-requests" ], "security": [ { "user": [] }, { "oauth": [ "space:read" ] } ], "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": "site", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests linked to this site will be returned." }, { "name": "space", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests from this space 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": "finding", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "none", "all" ] }, "description": "Controls whether change requests from triage are included. Pass `none` to exclude change requests from triage, or `all` to include them. Default is `none`." }, { "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 in an organization", "description": "Returns a paginated list of all spaces belonging to the organization. A space is a collection of documentation pages with its own content tree and revision history. Use this to discover spaces before reading their content, adding them to a site, or performing operations on specific spaces.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "integration-installation": [] }, { "oauth": [ "space:read" ] } ], "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 new documentation space in an organization", "description": "Creates a new space within the organization. A space is the primary container for documentation content, holding pages, files, and revisions. After creation, add the space to a site to make it publicly accessible, or start adding content directly via the space content endpoints.", "x-gitbook-mcp": true, "tags": [ "spaces" ], "security": [ { "user": [] }, { "oauth": [ "space:write" ] } ], "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": [] }, { "oauth": [ "space:read" ] } ], "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": [] }, { "oauth": [ "space:write" ] } ], "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.\n", "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": [] }, { "oauth": [ "organization:ask" ] } ], "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": [] }, { "oauth": [ "organization:ask" ] } ], "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": [] }, { "oauth": [ "organization:ask" ] } ], "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": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "organization:ask" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi" ], "security": [ { "user": [] }, { "oauth": [ "openapi:write" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi" ], "security": [ { "user": [] }, { "oauth": [ "openapi:write" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi" ], "security": [ { "user": [] }, { "oauth": [ "openapi:write" ] } ], "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": [] }, { "oauth": [ "openapi:write" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi-versions" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi-versions" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi-versions" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi-versions" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "tags": [ "openapi-versions" ], "security": [ { "user": [] }, { "oauth": [ "openapi:read" ] } ], "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", "x-gitbook-mcp": true, "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", "x-gitbook-mcp": true, "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.\nAt least one font face with weight 400 (regular) must be provided.\n", "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.\n", "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": [] }, { "oauth": [ "space:write" ] } ], "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 documentation sites in an organization", "description": "Returns a paginated list of all documentation sites belonging to the organization. Use this to discover available sites before fetching their content, settings, or structure.", "x-gitbook-mcp": true, "tags": [ "sites", "critical" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 new documentation site in an organization", "description": "Creates a new documentation site within the organization. Optionally links one or more existing spaces as content sources at creation time. The site is created in an unpublished state; call the publish endpoint separately to make it publicly accessible.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 documentation site by its ID", "description": "Retrieves full details for a single documentation site. Use this to inspect a specific site's metadata before reading or modifying its settings, structure, or content.", "x-gitbook-mcp": true, "tags": [ "sites" ], "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 the properties of a documentation site", "description": "Updates a documentation site's configuration. Use this to rename a site, change its access level, or point it at a reverse-proxy path such as https://company.com/docs.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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`.\nUse `null` to remove the proxy.\n", "oneOf": [ { "$ref": "#/components/schemas/SiteProxyOrigin" }, { "type": "null" } ] }, "styleguide": { "description": "Attach an existing styleguide to the site by the ID of the styleguide space, or `null` to detach the current one. The space must be a styleguide owned by the same organization.\n", "oneOf": [ { "type": "string" }, { "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": [] }, { "oauth": [ "site:write" ] } ], "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}/spaces/git/installations": { "get": { "operationId": "listSiteGitSyncInstallations", "summary": "List the Git Sync installations for a site and its spaces", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "Git Sync installations for the site and its spaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncInstallation" } } }, "required": [ "items" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/adaptive-schema": { "get": { "operationId": "getSiteAdaptiveSchema", "summary": "Get the visitor attributes JSON schema for an adaptive content site", "description": "Returns the JSON schema that defines the visitor attributes expected by an adaptive content site. Adaptive content uses these attributes (e.g., user role, plan tier) to conditionally show or hide content sections. Use this to understand what visitor data must be provided when rendering adaptive content.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "site:read" ] } ], "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 visitor attributes JSON schema for an adaptive content site", "description": "Replaces the JSON schema that defines expected visitor attributes for adaptive content. The schema controls which attributes (e.g., role, subscription tier) can be used in conditional expressions to show or hide content for specific visitors. After updating, existing conditional expressions are evaluated against the new schema.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "integration": [] }, { "integration-installation": [] }, { "oauth": [ "site:write" ] } ], "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 condition templates for adaptive content expressions in a site", "description": "Returns pre-generated condition templates derived from the site's visitor attributes schema. These templates can be used as building blocks when writing adaptive content expressions to conditionally show or hide content for different visitor types. Use this to discover available conditions before authoring adaptive rules.", "x-gitbook-mcp": true, "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 the full published profile of a site including structure and customization", "description": "Returns the complete profile needed to render the published experience of a site. Use this when building a site renderer or preview rather than fetching each resource individually.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 to make it publicly accessible", "description": "Makes the site publicly accessible at its configured URL by publishing it. If the organization's plan requires an upgrade, the response includes a Stripe checkout session ID instead of the site object. Use unpublish to take the site offline again.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:publish" ] } ], "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": "Take a site offline by unpublishing it", "description": "Removes the site from public access by unpublishing it. The site's configuration and content are preserved; use the publish endpoint to make it accessible again. Use this when you need to temporarily hide a site or take it down for maintenance.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:publish" ] } ], "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 private share links for a site", "description": "Returns a paginated list of share links configured for the site. Share links grant access to a private site without requiring full authentication. Use this to audit existing share links, check their active status, or find a link ID before updating or revoking it.", "x-gitbook-mcp": true, "tags": [ "site-share-links" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:read" ] } ], "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 private share link for a site", "description": "Creates a new named share link that grants access to the private site without requiring full user authentication. Share links are useful for sharing pre-publication content with reviewers or stakeholders. Each link has a unique key and can be activated or deactivated independently.", "x-gitbook-mcp": true, "tags": [ "site-share-links" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:write" ] } ], "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 private share link for a site", "description": "Updates a share link's properties. Use this to temporarily disable a share link without losing its configuration.", "x-gitbook-mcp": true, "tags": [ "site-share-links" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:write" ] } ], "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": [] }, { "oauth": [ "site:auth:write" ] } ], "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 the full navigation structure of a site", "description": "Returns the complete hierarchical structure of a site, including all sections, section groups, and site spaces in their current order. Use this to understand how a site's navigation is organized before making structural changes, or to render the full navigation tree of a site.", "x-gitbook-mcp": true, "tags": [ "site-structure" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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, section, or section group to a new position", "description": "Reorders an item in the site's navigation structure by moving a site space, section, or section group to a specified position relative to another item. Use this to reorganize the navigation order after adding new sections or to reflect a new content hierarchy.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 the published content authentication configuration for a site", "description": "Retrieves the authentication settings that protect a site's published content. Use this to review the current auth method before making changes or troubleshooting access issues.", "x-gitbook-mcp": true, "tags": [ "site-publishing-auth" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:read" ] } ], "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 the published content authentication configuration for a site", "description": "Modifies the authentication method used to protect a site's published content. Use this to enable, disable, or change the auth method for a published site.", "x-gitbook-mcp": true, "tags": [ "site-publishing-auth" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:write" ] } ], "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 the private key for a site's published content authentication", "description": "Re-generates the private key used for the site's publishing authentication (e.g., JWT signing key for SSO). Existing tokens signed with the old key will become invalid immediately. Use this to rotate credentials after a security incident or as part of a regular key rotation policy.", "x-gitbook-mcp": true, "tags": [ "site-publishing-auth" ], "security": [ { "user": [] }, { "oauth": [ "site:auth:write" ] } ], "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": "Generate a temporary preview URL for a site's published content", "description": "Generates a time-limited URL (valid for 1 hour) to preview how a site will look when published. Use this to verify changes before making the site publicly accessible.", "x-gitbook-mcp": true, "tags": [ "site-preview" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 the branding and visual customization settings for a site", "description": "Retrieves the full customization configuration for a site. Use this before making updates to read the current state, or to audit branding settings.", "x-gitbook-mcp": true, "tags": [ "site-customization" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 the branding and visual customization settings for a site", "description": "Replaces the full customization configuration for a site. This is a full replacement — unset fields revert to defaults. Use the GET endpoint first to read the current settings before making targeted changes.", "x-gitbook-mcp": true, "tags": [ "site-customization" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 custom scripts injected into a site's published pages", "description": "Returns all integration scripts configured to be injected into the published pages of a site, such as analytics trackers, chat widgets, or custom JavaScript. Use this to audit which third-party scripts are active on the site.", "x-gitbook-mcp": true, "tags": [ "integrations", "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 third-party integrations enabled on a site", "description": "Returns a paginated list of integrations currently enabled on the site. Integrations extend site functionality with third-party services such as analytics, support, or authentication providers. Use this to audit which integrations are active, or to find an integration before updating its settings.", "x-gitbook-mcp": true, "tags": [ "integrations", "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 as a content source", "description": "Links an existing space to the site by creating a site space relationship.", "x-gitbook-mcp": true, "tags": [ "site-spaces" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 spaces linked to a site as content sources", "description": "Returns a paginated list of site spaces — the links between a site and its content source spaces. Each site space can be a language variant or content version within a section. Use the default filter to retrieve only the primary site space, or omit it to get all linked spaces including drafts.", "x-gitbook-mcp": true, "tags": [ "site-spaces", "critical" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 section groups in a site's navigation structure", "description": "Returns a paginated list of section groups for the site. Section groups are containers that organize multiple sections into a hierarchical navigation structure. Use this to inspect the current grouping before adding, updating, or reordering items in the site structure.", "x-gitbook-mcp": true, "tags": [ "site-section-groups" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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's navigation structure", "description": "Creates a new section group to organize multiple sections under a shared navigation label. Section groups can be nested by providing a parent group ID. Existing sections can be assigned to the group at creation time via their IDs. Create the group in draft mode to stage it before publishing.", "x-gitbook-mcp": true, "tags": [ "site-section-groups" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 section group in a site's navigation structure", "description": "Updates a section group's properties in the site's navigation structure.", "x-gitbook-mcp": true, "tags": [ "site-section-groups" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 should be kept in draft mode. Setting it to true makes the site section group draft. Setting it to false makes the site section group 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": [] }, { "oauth": [ "site:write" ] } ], "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 new navigation section to a site backed by a space", "description": "Creates a new top-level navigation section in the site by linking a space as its primary content source. The section appears as a tab or sidebar entry in the site navigation.", "x-gitbook-mcp": true, "tags": [ "site-sections" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 navigation sections in a site", "description": "Returns a paginated list of sections in the site. Each section is a top-level navigation item backed by one or more site spaces. Use this to inspect the current navigation structure, find a section ID before updating it, or check whether sections are in draft or live state.", "x-gitbook-mcp": true, "tags": [ "site-sections" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 navigation section in a site", "description": "Updates a navigation section's configuration in the site structure.", "x-gitbook-mcp": true, "tags": [ "site-sections" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 should be kept in draft mode. Setting it to true makes the site section draft. Setting it to false makes the site section 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": [] }, { "oauth": [ "site:write" ] } ], "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": "Full-text search across all content in a site", "description": "Performs a full-text search across all published spaces in the site and returns matching pages with relevant excerpts. Use the scope parameter to restrict the search to specific site spaces or sections. Prefer this over the space-level search when you need to search across a multi-section site in one call.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:search" ] } ], "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": [] }, { "oauth": [ "site:ask" ] } ], "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.\n", "properties": { "siteSpaceId": { "type": "string" }, "goal": { "type": "string", "maxLength": 1024, "description": "The end goal the agent is trying to accomplish on behalf of the user. Unlike the question, which is the immediate query, the goal describes the broader task or outcome the agent is working towards. GitBook uses this to steer the answer towards what is ultimately useful for that goal.\n" } } }, "scope": { "$ref": "#/components/schemas/SiteSearchScope" }, "session": { "$ref": "#/components/schemas/SiteInsightsSession" } } } } } }, "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": [] }, { "oauth": [ "site:ask" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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" } }, { "name": "hasChangeRequests", "in": "query", "description": "Filter findings that have at least one associated change request.", "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/SiteFinding" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}": { "get": { "operationId": "getSiteFindingById", "summary": "Get a site finding by ID", "tags": [ "site-context" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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", "done", "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:read" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": "channelType", "in": "query", "description": "Filter questions by answer channel type.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannelType" } } }, { "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": "channelType", "in": "query", "description": "Filter stats by answer channel type.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannelType" } } }, { "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": "channelType", "in": "query", "description": "Filter answer sources by answer channel type.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannelType" } } }, { "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": "channelType", "in": "query", "description": "Filter stats by answer channel type.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannelType" } } }, { "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": "channelType", "in": "query", "description": "Filter answers by answer channel type.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannelType" } } }, { "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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": [] }, { "oauth": [ "site:insights:read" ] } ], "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 space linked to a site", "description": "Updates the configuration of a site space. Use this to remap a site space to a different space, hide it from navigation, or promote it from draft to live.", "x-gitbook-mcp": true, "tags": [ "site-spaces" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 true makes the site space draft. 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": [] }, { "oauth": [ "site:write" ] } ], "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 the customization overrides for a site space", "description": "Retrieves the customization settings that override the site-level branding for a specific site space, such as a language variant or content version. Returns the effective settings with site-level defaults where no override is set. Use this before applying or removing overrides.", "x-gitbook-mcp": true, "tags": [ "site-customization" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 branding and customization settings for a specific site space", "description": "Applies customization overrides to a specific site space, such as a language variant or content version, that take precedence over the site-level settings. Only provided fields are overridden; set a field to null to clear its override and fall back to the site-level value.", "x-gitbook-mcp": true, "tags": [ "site-customization" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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" ] } } }, "feedback": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "If true, feedback gathering is enabled. Set to null to reset the override." } }, "required": [ "enabled" ] }, "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:permissions:write" ] } ], "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": [] }, { "oauth": [ "site:permissions:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" }, { "$ref": "#/components/parameters/memberRoleFilter" }, { "$ref": "#/components/parameters/memberSearch" }, { "$ref": "#/components/parameters/memberSort" }, { "name": "team", "in": "query", "description": "Team identifier. Filter the list to members of a specific team.", "schema": { "type": "string" } } ], "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": [] }, { "oauth": [ "site:permissions:read" ] } ], "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": [] }, { "oauth": [ "site:permissions:write" ] } ], "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": [] }, { "oauth": [ "site:permissions:write" ] } ], "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": [] }, { "oauth": [ "site:permissions:read" ] } ], "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": [] }, { "oauth": [ "site:permissions:write" ] } ], "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": [] }, { "oauth": [ "site:permissions:write" ] } ], "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.\n", "tags": [ "site-ai" ], "security": [ { "user": [] }, { "oauth": [ "site:ask" ] } ], "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 the AI agent configuration for a site", "description": "Retrieves the configuration for the AI built into the GitBook editor that assists authors with drafting and refining content changes. Use this before updating agent settings to understand the current configuration.", "x-gitbook-mcp": true, "tags": [ "site-agent-settings" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 the AI agent configuration for a site", "description": "Replaces the configuration for the AI built into the GitBook editor that helps authors draft, review, and refine content changes. Use this to customize how the AI behaves when assisting authors working on content for this site.", "x-gitbook-mcp": true, "tags": [ "site-agent-settings" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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}/styleguide": { "post": { "operationId": "createSiteStyleguideById", "summary": "Create or retrieve the styleguide space for a site", "description": "Ensures the site has a dedicated styleguide space and returns a reference to it. The styleguide defines writing style and tone guidelines that the AI editor agent references when generating or refining content for the site. If a styleguide already exists, this is idempotent and returns the existing reference.", "x-gitbook-mcp": true, "tags": [ "sites" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "description": "Built-in template id to seed the styleguide content with. Omit (or send no body) to create a blank styleguide.\n" } } } } } }, "responses": { "200": { "description": "Styleguide created or already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentRefSpace" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/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": [] }, { "oauth": [ "site:insights:read" ] } ], "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 the advertising settings for a site", "description": "Updates the advertising configuration for a site, including the review status and topic category used to select relevant ads. This controls GitBook's monetization feature for sites opted into the ads program.", "x-gitbook-mcp": true, "tags": [ "site-ads" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 URL redirect rule for a site", "description": "Creates a new redirect rule mapping a source path to a destination URL or content reference. Use the bulk upsert endpoint instead when creating many redirects at once.", "x-gitbook-mcp": true, "tags": [ "site-redirects" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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, update, delete, or publish site redirect rules in bulk", "description": "Processes up to 500 redirect operations in a single request. Each redirect in the array is processed independently and the response includes per-item status. Prefer this over individual create/update calls when managing large sets of redirects.", "x-gitbook-mcp": true, "tags": [ "site-redirects" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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.\n" } }, "required": [ "source", "intent" ] }, { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/SiteRedirectSourcePath" }, "intent": { "type": "string", "enum": [ "live", "draft" ], "default": "live", "description": "Redirect operation intent.\n- live: upsert/delete a live redirect (draft=false)\n- draft: upsert/delete a draft redirect (draft=true)\n" }, "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 URL redirect rules configured for a site", "description": "Returns a paginated list of redirect rules for the site. Supports filtering by draft status and searching by path. Use this to audit redirects, find a specific rule before updating it, or check whether draft redirects are pending publication.", "x-gitbook-mcp": true, "tags": [ "site-redirects" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 URL redirect rule for a site", "description": "Updates an existing redirect rule for a site. Only provided fields are updated.", "x-gitbook-mcp": true, "tags": [ "site-redirects" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "oauth": [ "site:write" ] } ], "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": "Resolve a site redirect rule by its source path", "description": "Looks up a redirect rule by its source URL path and returns both the redirect configuration and the resolved destination URL. Use this to check whether a specific path has a redirect configured, or to resolve where a path currently points before updating or removing the redirect.", "x-gitbook-mcp": true, "tags": [ "site-redirects" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 configured for a site", "description": "Returns a paginated list of Model Context Protocol (MCP) server configurations attached to the site. MCP servers expose tools and resources that the AI Assistant can call when helping site visitors find information. Use this to audit or manage the AI tool integrations available on a site.", "x-gitbook-mcp": true, "tags": [ "site-mcp-servers" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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": "Add a new MCP server configuration to a site", "description": "Registers a new Model Context Protocol (MCP) server with the site, providing its URL, transport type, request headers, and an optional conditional expression to control visibility per visitor. Once added, the MCP server's tools become available to the AI Assistant when helping visitors of this site.", "x-gitbook-mcp": true, "tags": [ "site-mcp-servers" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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" }, "transport": { "$ref": "#/components/schemas/SiteMcpServerTransport" }, "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 an MCP server configuration for a site by its ID", "description": "Retrieves the configuration of a specific MCP server registered with the site. Use this to inspect an MCP server's details before updating or removing it.", "x-gitbook-mcp": true, "tags": [ "site-mcp-servers" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 an MCP server configuration for a site", "description": "Modifies an existing MCP server's configuration. Only provided fields are updated; omitting a field leaves it unchanged. Set condition to null to remove it and make the MCP server available to all visitors.", "x-gitbook-mcp": true, "tags": [ "site-mcp-servers" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 }, "transport": { "$ref": "#/components/schemas/SiteMcpServerTransport" }, "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": [] }, { "oauth": [ "site:write" ] } ], "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 GitBook Agent channels for a site", "description": "Returns a paginated list of channels configured for the site. Channels are integrations that allow GitBook Agent to operate within external tools your team already uses, bringing documentation assistance directly into existing workflows. Each channel has a role that determines whether the Agent answers questions from the site's documentation or actively collaborates by opening and managing content changes. Use this to inspect or manage the Agent channel integrations for a site.", "x-gitbook-mcp": true, "tags": [ "site-channels" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 new GitBook Agent channel for a site", "description": "Configures a new channel integration that allows GitBook Agent to operate within an external tool connected to this site. The channel role determines whether the Agent acts as a support assistant — answering questions sourced from the site's documentation — or as a collaborator that can open change requests and sync documentation updates directly from the connected platform.", "x-gitbook-mcp": true, "tags": [ "site-channels" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 GitBook Agent channel for a site by its ID", "description": "Retrieves the configuration of a specific GitBook Agent channel integration, including its connected platform type and role. Use this to inspect or verify the channel's setup before updating it.", "x-gitbook-mcp": true, "tags": [ "site-channels" ], "security": [ { "user": [] }, { "oauth": [ "site:read" ] } ], "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 GitBook Agent channel for a site", "description": "Modifies the configuration of a specific GitBook Agent channel integration, including its role. Use this to change whether the Agent answers documentation questions or actively collaborates on content changes through the connected platform.", "x-gitbook-mcp": true, "tags": [ "site-channels" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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 GitBook Agent channel from a site", "tags": [ "site-channels" ], "security": [ { "user": [] }, { "oauth": [ "site:write" ] } ], "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": [] }, { "user-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": [] }, { "integration": [] }, { "integration-installation": [] } ], "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" } } } }, "/git/installations": { "post": { "operationId": "installGitSyncProviderOnTarget", "summary": "Install a Git Sync provider on a target", "tags": [ "git" ], "security": [ { "user": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/GitSyncInstallationProvider" }, "target": { "$ref": "#/components/schemas/GitSyncInstallationTarget" } }, "required": [ "provider", "target" ] } } } }, "responses": { "201": { "description": "Git Sync installation was created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitSyncInstallation" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" } } } }, "/git/installations/{installationId}": { "get": { "operationId": "getGitSyncInstallationById", "summary": "Get a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { "description": "Git Sync installation was found successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitSyncInstallation" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateGitSyncInstallationById", "summary": "Update a Git Sync installation configuration", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitSyncInstallationSetup" } } } }, "responses": { "200": { "description": "Git Sync installation was updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitSyncInstallation" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" } } }, "delete": { "operationId": "uninstallGitSyncInstallation", "summary": "Uninstall a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" } ], "responses": { "205": { "description": "Git Sync installation was removed successfully" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/git/installations/{installationId}/github/repos": { "get": { "operationId": "listGitHubRepositoriesForGitSyncInstallation", "summary": "List GitHub repositories available for a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { "description": "GitHub repositories available for the Git Sync installation", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncGitHubRepository" } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/git/installations/{installationId}/github/repos/{accountName}/{repositoryName}/branches": { "get": { "operationId": "listGitHubRepoBranchesForGitSyncInstallation", "summary": "List GitHub repository branches available for a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" }, { "name": "accountName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repositoryName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GitHub branches available for the selected repository", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncBranch" } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/git/installations/{installationId}/gitlab/projects": { "get": { "operationId": "listGitLabProjectsForGitSyncInstallation", "summary": "List GitLab projects available for a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { "description": "GitLab projects available for the Git Sync installation", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncGitLabProject" } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/git/installations/{installationId}/gitlab/projects/{projectId}/branches": { "get": { "operationId": "listGitLabProjectBranchesForGitSyncInstallation", "summary": "List GitLab project branches available for a Git Sync installation", "tags": [ "git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/installationId" }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "GitLab branches available for the selected project", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncBranch" } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } } }, "components": { "securitySchemes": { "user": { "type": "http", "scheme": "bearer" }, "user-internal": { "type": "http", "scheme": "bearer" }, "user-staff": { "type": "http", "scheme": "bearer" }, "integration": { "type": "http", "scheme": "bearer" }, "integration-installation": { "type": "http", "scheme": "bearer" }, "oauth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://oauth.gitbook.com/authorize", "tokenUrl": "https://oauth.gitbook.com/token", "scopes": { "user:read": "Read your GitBook user profile.", "organization:read": "Read organization settings and metadata.", "organization:write": "Create and update organization settings.", "organization:members:read": "Read organization members, invites and link invites.", "organization:members:write": "Manage organization members, invites and link invites.", "organization:ask": "Ask AI questions across an organization's content.", "organization:search": "Search across an organization's content.", "space:read": "Read spaces and their content.", "space:write": "Create, update and delete spaces and their content, including imports.", "space:permissions:read": "Read space permissions.", "space:permissions:write": "Manage space permissions.", "change-request:merge": "Merge change requests, publishing their changes to the space.", "site:read": "Read sites and their settings.", "site:write": "Create, update and delete sites, sections and their settings.", "site:publish": "Publish and unpublish sites, controlling their public exposure.", "site:permissions:read": "Read site permissions.", "site:permissions:write": "Manage site permissions.", "site:auth:read": "Read site authentication and security configuration.", "site:auth:write": "Manage site authentication and security configuration.", "site:insights:read": "Read site analytics and insights.", "site:ask": "Ask AI questions across a site's content.", "site:search": "Search across a site's content.", "openapi:read": "Read OpenAPI specifications.", "openapi:write": "Create, update and delete OpenAPI specifications." } } } } }, "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" ] } }, "documentMarkdownRefsFormat": { "name": "format.markdown.refs", "in": "query", "description": "Controls how content references are formatted in markdown output. Ignored unless `format=markdown`.\n\n- `relative`: Format page references as relative links from the current page. Other references might not be handled.\n- `stable`: Format content references as stable idempotent refs containing their identifiers.\n", "schema": { "type": "string", "default": "relative", "enum": [ "relative", "stable" ] } }, "documentEvaluated": { "name": "evaluated", "in": "query", "description": "Controls whether the document should be evaluated.\n- When set to `true`, the entire document will be evaluated.\n- When set to `deterministic-only`, only expressions that depend\n exclusively on deterministic inputs will be evaluated.\n", "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).\n- When set to `true`, the entire document will be deferenced\n- When set to `reusable-contents`, only reusable contents will be deferenced.\n", "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" } }, "conversationId": { "name": "conversationId", "in": "path", "required": true, "description": "The unique ID of the agent conversation (its client-generated local id, or \"default\" for the default conversation)", "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\n", "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" } }, "memberRoleFilter": { "name": "role", "in": "query", "description": "The role to filter the list by", "schema": { "oneOf": [ { "$ref": "#/components/schemas/MemberRole" }, { "type": "string", "enum": [ "guest" ] } ] } }, "memberSearch": { "name": "search", "in": "query", "description": "A query to filter the list by display name and email", "schema": { "type": "string" } }, "memberSort": { "name": "sort", "in": "query", "description": "The property to sort the list by", "schema": { "type": "string", "default": "joinedAt", "enum": [ "joinedAt", "lastSeenAt", "name" ] } }, "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.\n* `unlisted`: Anyone can access the content, and the content is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the content.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the content.\n* `in-collection`: Anyone who can access the parent collection can access the content.\n Only available for spaces in a collection.\n* `private`: Authorized members can access the content.\n", "enum": [ "public", "unlisted", "share-link", "visitor-auth", "in-collection", "private" ] }, "SpaceEditMode": { "type": "string", "description": "Determines how a Space can be edited.\n* `live`: Users can directly edit the space\n* `locked`: All edits are locked for this space.\n", "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" }, "message": { "type": "string", "description": "Optional message to display when the expression evaluates to false." } }, "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", "zh-tw", "yue", "ko", "ar", "hi", "nl", "pl", "tr", "sv", "no", "da", "fi", "el", "cs", "hu", "ro", "th", "vi", "id", "ms", "he", "uk", "sk", "bg", "hr", "lt", "lv", "et", "sl" ] }, "GitSyncInstallationStatus": { "type": "string", "enum": [ "unauthenticated", "active", "pending" ] }, "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." }, "installationStatus": { "$ref": "#/components/schemas/GitSyncInstallationStatus" }, "installationProvider": { "$ref": "#/components/schemas/GitSyncProvider" }, "integration": { "type": "string", "deprecated": true, "description": "The integration name providing the Git Sync." }, "installationId": { "type": "string", "description": "The ID of the Git Sync installation." }, "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.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n", "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" }, "type": { "type": "string", "description": "Kind of space. Only set to `styleguide` for spaces holding a team's writing styleguide; omitted for regular spaces.", "enum": [ "styleguide" ] }, "mergeRules": { "$ref": "#/components/schemas/MergeRulesSpaceConfiguration" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "location": { "type": "string", "description": "URL of the space in the API", "format": "uri" }, "app": { "type": "string", "description": "URL of the space in the application", "format": "uri" }, "published": { "type": "string", "description": "URL of the published version of the space. Only defined when visibility is not \"private.\"", "format": "uri" }, "public": { "type": "string", "description": "URL of the public version of the space. Only defined when visibility is \"public\".", "format": "uri" }, "icon": { "description": "URL of the icon of this space, if defined.", "$ref": "#/components/schemas/URL" } }, "required": [ "app", "location" ] }, "organization": { "type": "string", "description": "ID of the organization owning this space" }, "parent": { "type": "string", "description": "ID of the parent collection." }, "language": { "$ref": "#/components/schemas/TranslationLanguage" }, "gitSync": { "$ref": "#/components/schemas/GitSyncState" }, "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.\n", "$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.\n", "$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", "example": "# Hello World\n\nThis is a markdown document linking to [another page](/pages/page_id).\n" } }, "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", "description": "Allowed color tokens for color marks (text and background; background reuses this enum). Named colors are fixed palette keys. `$*` tokens are semantic: resolved from the published sites customization when rendering; authors may still persist them in content when valid.\n", "enum": [ "default", "green", "blue", "red", "orange", "yellow", "purple", "pink", "violet", "cyan", "$primary", "$info", "$success", "$warning", "$danger", "$tint" ] }, "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\nin columnWidths would be scaled to ensure a 100% width table.\n\nWe later changed this to treat the widths in columnWidths as exact values - they are\nnever scaled. A columnWidth of 50 is rendered as 50px.\n\nIn order to maintain backwards compatibility, we track whether or not we\nuse the new system here.\n\nAll new tables should have this value set to true, older tables will have it set\nto undefined.\n" } }, "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" }, "search": { "type": "boolean", "description": "Whether to show the search bar on the table. When unset, search is shown automatically on grid tables once they have enough rows." } }, "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" ] }, "DocumentBlockPrompt": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "prompt" ] }, "key": { "type": "string" }, "data": { "type": "object", "properties": { "description": { "type": "string" }, "icon": { "$ref": "#/components/schemas/Icon" }, "openInAIProviders": { "type": "boolean" } }, "required": [ "description" ], "additionalProperties": false }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlockCode" } ] }, "minItems": 1, "maxItems": 1 }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "data", "nodes" ] }, "DocumentBlocksTopLevels": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockPrompt" }, { "$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" }, { "$ref": "#/components/schemas/DocumentBlockUpdates" } ] }, "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.\nThis property is set when creating a block from a URL (unfurl) to ensure\nwe can convert the block back to an embed.\n" }, "fullWidth": { "type": "boolean" } }, "required": [ "integration", "block", "props" ] }, "isVoid": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "properties": { "token": { "type": "string", "description": "A content token that can be used to authenticate requests for cross-space integration blocks." }, "spaceId": { "type": "string", "description": "ID of the space the integration block originates from" } } } }, "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/DocumentBlockPrompt" }, { "$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/DocumentBlockPrompt" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" } ] } }, "data": { "type": "object", "properties": { "title": { "type": "string" }, "icon": { "$ref": "#/components/schemas/Icon" } } }, "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" }, "headless": { "type": "boolean", "x-internal": true, "description": "When true, the block omits its own title and description; the page renders them instead. Set by the computed one-operation-per-page layout; not intended to be set manually." } }, "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" }, "headless": { "type": "boolean", "x-internal": true, "description": "When true, the block omits its own title and description; the page renders them instead. Set by the computed one-operation-per-page layout; not intended to be set manually." } }, "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/DocumentBlockPrompt" }, { "$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/DocumentBlockPrompt" }, { "$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/DocumentBlockPrompt" }, { "$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/DocumentBlockPrompt" }, { "$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" ], "example": { "object": "document", "data": {}, "nodes": [ { "object": "block", "type": "paragraph", "data": {}, "nodes": [ { "object": "text", "leaves": [ { "object": "leaf", "text": "Hello world", "marks": [] } ] } ] } ] } }, "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.\n* `private`: The spec is not publicly available.\n* `public`: The spec is available to anyone with a public link.\n", "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." }, "grouping": { "type": "string", "enum": [ "by-tag", "by-operation" ], "description": "How GitBook will group generated pages. \"by-tag\" groups operations under their tag; \"by-operation\" creates a separate page per operation. Defaults to \"by-tag\" when absent." } }, "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" }, "language": { "$ref": "#/components/schemas/TranslationLanguage" } }, "required": [ "space", "revision", "language" ] }, "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.\nThe state of the dependencies will be passed to the computation.\nWhen the dependency's targets are updated, the computation will be updated.\n", "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?" }, "actions": { "type": "boolean", "description": "Should the page actions be visible on the page?" } }, "required": [ "width", "cover", "coverSize", "title", "description", "tableOfContents", "outline", "pagination", "metadata", "tags", "actions" ] }, "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 } } }, { "type": "object", "required": [ "doc", "page", "method" ], "properties": { "doc": { "type": "string", "enum": [ "operation" ] }, "page": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "get", "post", "put", "delete", "patch", "options", "head", "trace", "hook" ] }, "deprecated": { "type": "boolean" } } }, { "type": "object", "required": [ "doc", "page" ], "properties": { "doc": { "type": "string", "enum": [ "tag" ] }, "page": { "type": "string", "minLength": 1 } } } ] } } } ] }, "ComputedContentSourceDocumentTranslation": { "type": "object", "description": "Parameters for a document translation computed content source", "required": [ "type", "props", "dependencies" ], "properties": { "type": { "type": "string", "enum": [ "builtin:translation" ] }, "props": { "type": "object", "required": [ "space", "document" ], "properties": { "space": { "type": "string" }, "document": { "type": "string" } } }, "dependencies": { "type": "object", "required": [ "translation" ], "properties": { "translation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ref" ], "properties": { "ref": { "$ref": "#/components/schemas/TranslationRef" } } }, { "$ref": "#/components/schemas/ComputedContentDependencyTranslation" } ] } } } } }, "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" ] }, "sourceRevision": { "type": "string", "description": "ID of the non-computed revision used to compute this revision." }, "mergedFrom": { "description": "The change request the source revision was merged from, when the computed revision is derived from a merge revision.", "$ref": "#/components/schemas/ChangeRequest" } }, "required": [ "type", "sourceRevision" ] } ] }, "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. \nIf false, organization must resolve other billing issues before a checkout can be done.\n", "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" }, "canChangeInterval": { "description": "Whether changing billing interval is allowed", "type": "boolean" }, "canUseSAML": { "description": "Whether configuring SAML is allowed", "type": "boolean" } }, "required": [ "interval", "endDate", "hasPaymentFailed", "canCheckout", "isScheduledToCancel", "pricing", "usageAddons", "canChangeInterval", "canUseSAML" ] }, "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.\n", "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:\n- `ok` - No problems detected for this content reference.\n- `broken` - The target does not exist in the revision.\n- `in-app` - The target is a URL link pointing to an internal location in the app.\n" }, "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.\n- `reference` - The content soft-references the ref target\n- `dependsOn` - The content depends on the ref target\n" }, "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" ] } ] } ] }, "AgentConversation": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"agent-conversation\"", "enum": [ "agent-conversation" ] }, "id": { "type": "string", "description": "The unique ID of the conversation. This is the client-generated identifier used to address the conversation; for the default conversation of a change request it is \"default\"." }, "title": { "type": "string", "description": "The title of the conversation, generated from the first message. Absent until generated." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "object", "id", "createdAt", "updatedAt" ] }, "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" ] } ] }, "ChangeRequestContentChangeUpdatePage": { "type": "object", "description": "Replace the document of an existing page with another document.", "required": [ "operation", "page", "document" ], "properties": { "operation": { "type": "string", "enum": [ "update_page" ] }, "page": { "type": "string", "description": "ID of the page whose content should be updated." }, "document": { "$ref": "#/components/schemas/Document" } }, "example": { "operation": "update_page", "page": "page_id", "document": { "markdown": "# Hello World\n\nThis is a markdown document linking to [another page](/pages/page_id).\n" } } }, "ChangeRequestContentChangeInsertPage": { "type": "object", "description": "Insert a new page into the change request.", "required": [ "operation", "title", "document" ], "properties": { "operation": { "type": "string", "enum": [ "insert_page" ] }, "title": { "type": "string", "description": "Title of the new page." }, "into": { "type": "string", "description": "ID of the parent page to insert the new page into. If omitted, the page is inserted as a root page." }, "at": { "type": "integer", "minimum": 0, "description": "Zero-based index to insert the page at among its siblings. If omitted, the page is appended at the end." }, "document": { "$ref": "#/components/schemas/Document" } }, "example": { "operation": "insert_page", "title": "New page", "document": { "markdown": "# New page\n\nThis is a new page.\n" } } }, "ChangeRequestContentChangeDeletePage": { "type": "object", "description": "Delete an existing page (and its subpages) from the change request.", "required": [ "operation", "page" ], "properties": { "operation": { "type": "string", "enum": [ "delete_page" ] }, "page": { "type": "string", "description": "ID of the page to delete." } }, "example": { "operation": "delete_page", "page": "page_id" } }, "ChangeRequestContentChange": { "oneOf": [ { "$ref": "#/components/schemas/ChangeRequestContentChangeUpdatePage" }, { "$ref": "#/components/schemas/ChangeRequestContentChangeInsertPage" }, { "$ref": "#/components/schemas/ChangeRequestContentChangeDeletePage" } ], "discriminator": { "propertyName": "operation", "mapping": { "update_page": "#/components/schemas/ChangeRequestContentChangeUpdatePage", "insert_page": "#/components/schemas/ChangeRequestContentChangeInsertPage", "delete_page": "#/components/schemas/ChangeRequestContentChangeDeletePage" } } }, "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" }, "sites": { "type": "number" } }, "required": [ "object", "id", "role", "user", "disabled", "joinedAt", "sso", "spaces", "teams", "sites" ] }, "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:visitor:claims", "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 \nheaders when processing the script fetch event and the blocks fetch events.\n", "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" }, "publicContentEndpoint": { "type": "string", "description": "Public endpoint serving the integration's rendered content (e.g. WebFrames), isolated from the cookie-bearing publicEndpoint origin. Equals publicEndpoint when no separate content origin is configured.", "format": "uri" } }, "required": [ "location", "app", "assets", "publicEndpoint", "publicContentEndpoint" ] }, "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" }, "publicContentEndpoint": { "type": "string", "description": "Public endpoint serving the integration's rendered content (e.g. WebFrames), isolated from the cookie-bearing publicEndpoint origin. Equals publicEndpoint when no separate content origin is configured.", "format": "uri" } }, "required": [ "location", "app", "publicEndpoint", "publicContentEndpoint" ] }, "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" }, "updatedBy": { "type": "array", "description": "Users who updated the content", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "type", "revisionId", "updatedBy" ] } ] }, "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" }, "searchParams": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Whitelisted search parameters from the visitor authentication request." }, "action": { "type": "string", "enum": [ "logout" ], "description": "The visitor authentication action to resolve. If omitted, integrations resolve to the existing login redirect." } }, "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.\nThe integration should respond with a `Document`.\n", "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.\nThe integration should respond with an array of pages and files.\n", "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" }, "publicContentEndpoint": { "type": "string", "description": "Public endpoint serving the integration's rendered content (e.g. WebFrames), isolated from the cookie-bearing publicEndpoint origin. Equals publicEndpoint when no separate content origin is configured.", "format": "uri" } }, "required": [ "location", "publicEndpoint", "publicContentEndpoint" ] } }, "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.\n* `public`: Anyone can access the site, and the site is indexed by search engines.\n* `unlisted`: Anyone can access the site, and the site is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the site.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the site.\n", "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-ai-insights", "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" }, "gitSync": { "$ref": "#/components/schemas/GitSyncState" }, "createdAt": { "type": "string", "format": "date-time" }, "adaptiveContent": { "$ref": "#/components/schemas/SiteAdaptiveContent" }, "ads": { "$ref": "#/components/schemas/SiteAds" }, "styleguide": { "$ref": "#/components/schemas/ContentRefSpace", "description": "Reference to a GitBook space holding the team's writing styleguide.\nWhen present on a site, the editing agent receives the styleguide\ntable of contents in its system prompt and can fetch sections on\ndemand to check edits against the rules.\n" }, "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.\n", "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.\n", "format": "uri" }, "logout": { "type": "string", "description": "URL of the logout endpoint for visitors to sign out from the site auth backend.\n", "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" }, "canAccessVisitorClaims": { "type": "boolean", "description": "Whether the rendered integration UI can receive visitor claims." } }, "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" ] }, "OrganizationStyleguide": { "type": "object", "description": "A styleguide space and all the sites referencing it.", "properties": { "space": { "$ref": "#/components/schemas/Space" }, "sites": { "type": "array", "description": "Sites in the organization that reference this styleguide.", "items": { "$ref": "#/components/schemas/Site" } } }, "required": [ "space", "sites" ] }, "OrganizationStyleguides": { "type": "object", "properties": { "styleguides": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationStyleguide" } } }, "required": [ "styleguides" ] }, "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" ] }, "MemberSitePermission": { "type": "object", "description": "Permission of an organization member in a site.", "properties": { "site": { "$ref": "#/components/schemas/Site" }, "permission": { "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "required": [ "site", "permission" ] }, "TeamMemberRole": { "type": "string", "description": "\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n", "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.\n", "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\n", "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\n", "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.\n- `active`: The provider is active and can be used to authenticate users.\n- `pending`: The provider is pending and is not yet fully configured.\n", "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" ] }, "reason": { "description": "Reason for the import failure when `status` is `failed`.", "type": "string" }, "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.\n", "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" ] } ] }, "GitSyncInstallationPriority": { "type": "string", "description": "Which side should be treated as the source of truth when Git Sync is configured.", "enum": [ "git", "gitbook" ] }, "GitSyncInstallationSetupCommon": { "type": "object", "description": "Common setup fields for a Git Sync installation.", "properties": { "projectDirectory": { "type": "string", "description": "Optional directory used when syncing a monorepo subdirectory." }, "commitMessageTemplate": { "type": "string", "description": "Optional template used when generating commit messages." }, "previewExternalBranches": { "type": "boolean", "default": false, "description": "Whether previews should be generated from branches outside the configured branch." }, "priority": { "$ref": "#/components/schemas/GitSyncInstallationPriority" } } }, "GitSyncInstallationSetupGitHub": { "type": "object", "description": "GitHub provider configuration for a Git Sync installation.", "properties": { "provider": { "type": "string", "enum": [ "github" ] }, "providerConfiguration": { "type": "object", "description": "GitHub specific configuration for the Git Sync installation.", "properties": { "repositoryId": { "type": "number", "description": "GitHub repository identifier." }, "branch": { "type": "string", "pattern": "^refs/heads/.+$", "description": "GitHub repository branch ref." } } } }, "required": [ "provider", "providerConfiguration" ] }, "GitSyncInstallationSetupGitLab": { "type": "object", "description": "GitLab provider configuration for a Git Sync installation.", "properties": { "provider": { "type": "string", "enum": [ "gitlab" ] }, "providerConfiguration": { "type": "object", "description": "GitLab specific configuration for the Git Sync installation.", "properties": { "projectId": { "type": "number", "description": "GitLab project identifier." }, "accessToken": { "type": "string", "description": "GitLab access token with appropriate scopes for repository access." }, "customInstanceURL": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom GitLab instance URL, if using a self-hosted GitLab. Use null to clear a self-hosted URL." }, "branch": { "type": "string", "pattern": "^refs/heads/.+$", "description": "GitLab repository branch ref." } } } }, "required": [ "provider", "providerConfiguration" ] }, "GitSyncInstallationSetup": { "description": "Provider-specific setup payload for a Git Sync installation.", "allOf": [ { "$ref": "#/components/schemas/GitSyncInstallationSetupCommon" }, { "oneOf": [ { "$ref": "#/components/schemas/GitSyncInstallationSetupGitHub" }, { "$ref": "#/components/schemas/GitSyncInstallationSetupGitLab" } ], "discriminator": { "propertyName": "provider" } } ] }, "GitSyncInstallationTarget": { "description": "Resource targeted by a Git Sync installation.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "space" ], "description": "Type of resource targeted by the Git Sync installation." }, "spaceId": { "type": "string", "description": "Unique identifier of the space targeted by the Git Sync installation." } }, "required": [ "type", "spaceId" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site" ], "description": "Type of resource targeted by the Git Sync installation." }, "siteId": { "type": "string", "description": "Unique identifier of the site targeted by the Git Sync installation." } }, "required": [ "type", "siteId" ] } ], "discriminator": { "propertyName": "type" } }, "GitSyncInstallation": { "allOf": [ { "$ref": "#/components/schemas/GitSyncInstallationSetup" }, { "type": "object", "properties": { "object": { "type": "string", "enum": [ "git-sync-installation" ] }, "id": { "type": "string", "description": "Unique identifier of the Git Sync installation." }, "target": { "$ref": "#/components/schemas/GitSyncInstallationTarget" }, "status": { "$ref": "#/components/schemas/GitSyncInstallationStatus" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "createdBy": { "type": "string", "description": "Identifier of the user who created the installation." }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "urls": { "type": "object", "description": "URLs associated with the installation", "properties": { "location": { "type": "string", "description": "URL of the installation endpoint in the API", "format": "uri" } }, "required": [ "location" ] } }, "required": [ "object", "id", "target", "status", "createdAt", "createdBy", "updatedAt", "urls" ] } ] }, "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.\n- `clean`: Modern theme featuring translucency and minimally-styled elements.\n- `muted`: Sophisticated theme with decreased contrast between elements.\n- `bold`: High-impact theme with prominent colors and strong contrasts.\n- `gradient`: Trendy theme featuring colorful gradients and splashes of color.\n", "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.\n- `subtle`: Subtle shadows and minimal elevation.\n- `flat`: Flat elements, no shadows and no elevation.\n", "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.\n- `default`: Links are colored in the primary color and feature an underline in the same color.\n- `accent`: Links are colored the same as body text and feature an underline in the primary color.\n", "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.\n- `filled`: Muted background color that extends to sidebar edges.\n", "enum": [ "default", "filled" ] }, "CustomizationSidebarListStyle": { "type": "string", "description": "- `default`: Simple list items without special styling, groups are inset with a line.\n- `pill`: Rounded capsule shape around selected/active items.\n- `line`: Continuous line next to all items, with colored line part for selected/active items.\n", "enum": [ "default", "pill", "line" ] }, "CustomizationSearchStyle": { "type": "string", "description": "The style of the search button.\n- `prominent`: large search bar in the middle of the header, with less room for other header items,\n- `subtle`: small search bar in the corner of the header, with more room for other header items.\n", "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 }, "CustomizationPageActionType": { "type": "string", "description": "Type of a built-in page action that can be displayed in the page actions menu of a published page.", "enum": [ "assistant", "external-ai", "markdown", "mcp", "git", "pdf" ] }, "SiteExternalLinksTarget": { "type": "string", "description": "How external links should open when clicked.\n- `self`: External links open in the current tab.\n- `blank`: External links open in a new browser tab.\n", "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.\n", "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" ] }, "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" ] }, "pageActions": { "type": "object", "properties": { "items": { "type": "array", "description": "Ordered list of the page actions enabled in the page menu. This is the source of truth for\nwhich actions are enabled and in which order: the position defines the display order, the\nfirst action is the default one, surfaced as the main button on the page, and actions not\npresent in the list are disabled. The `assistant` action is governed by the `ai.mode` setting\nrather than this list: it is always present (prepended by default if missing, otherwise\nkeeping its position) when the assistant is enabled, and always absent when it is disabled.\n", "items": { "$ref": "#/components/schemas/CustomizationPageActionType" } } }, "required": [ "items" ] }, "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", "feedback", "ai", "advancedCustomization", "trademark", "externalLinks", "pagination", "pageActions", "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.\nIt is used to represent the structure of a site.\n", "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.\n", "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." }, "logoutURL": { "type": "string", "format": "uri", "description": "URL used to log visitors out from the upstream custom auth backend." }, "integration": { "type": "string", "description": "Name of the authenticated access integration installed on the site (if any).\nIt is also the one being used as VA backend when the published auth settings are configured to use \"integration\" as backend.\n" } }, "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." }, "logoutURL": { "type": [ "string", "null" ], "format": "uri", "description": "A logout URL used to log visitors out from the upstream custom auth backend. If not provided, the logout URL will not be changed. If set to null, the logout 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.\n", "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.\n" } } }, { "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" ] }, "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" ] }, "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", "builtin:zendesk", "builtin:pylon" ] } ] }, "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:\n - Outdated content: The content is no longer up to date with external context and may be misleading or incorrect.\n - Incoherent content: The content contains information that is inconsistent or contradictory.\n - Content gap: The content is missing important information that should be present to answer user questions effectively.\n - 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" ] }, { "type": "object", "properties": { "connector": { "type": "string", "enum": [ "builtin:zendesk" ] }, "setupSettings": { "type": "object", "properties": { "subdomain": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 }, "apiToken": { "type": "string", "minLength": 1 } }, "required": [ "subdomain", "email", "apiToken" ] } }, "required": [ "connector", "setupSettings" ] }, { "type": "object", "properties": { "connector": { "type": "string", "enum": [ "builtin:pylon" ] }, "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" ] }, "SiteCoreChannelType": { "type": "string", "enum": [ "site", "embed", "api" ] }, "SiteConfigurableChannelType": { "type": "string", "enum": [ "builtin:slack", "builtin:discord", "builtin:github", "builtin:linear" ] }, "SiteChannelType": { "oneOf": [ { "$ref": "#/components/schemas/SiteCoreChannelType" }, { "$ref": "#/components/schemas/SiteConfigurableChannelType" } ] }, "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" ] }, "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" ] }, "AIMessageStepStartCondition": { "type": "string", "description": "Describe the state in which the steps started.", "enum": [ "compaction" ] }, "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." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the page change in the current conversation." }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "tool", "spaceId", "baseRevisionId", "page" ] }, "AIToolCallCreatePage": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "createPage" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the page change in the current conversation." }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "tool", "spaceId", "baseRevisionId", "page" ] }, "AIToolCallDeletePage": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "deletePage" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the page deletion in the current conversation." }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "tool", "spaceId", "baseRevisionId", "page" ] }, "AIToolCallRenamePage": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "renamePage" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the page rename in the current conversation." }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" }, "title": { "type": "string", "description": "The new title of the page." } }, "required": [ "tool", "spaceId", "baseRevisionId", "page", "title" ] }, "AIToolCallMovePage": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "movePage" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the page move in the current conversation." }, "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.\n- `within`: moved as the last child of the target page (or to the root when `to` is omitted)\n- `before`: moved directly before the target page\n- `after`: moved directly after the target page\n", "enum": [ "within", "before", "after" ] } }, "required": [ "tool", "spaceId", "baseRevisionId", "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." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the reusable content change in the current conversation." }, "reusableContent": { "$ref": "#/components/schemas/ChangedRevisionReusableContent" } }, "required": [ "tool", "spaceId", "baseRevisionId", "reusableContent" ] }, "AIToolCallEditReusableContent": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "editReusableContent" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the reusable content change in the current conversation." }, "reusableContent": { "$ref": "#/components/schemas/ChangedRevisionReusableContent" } }, "required": [ "tool", "spaceId", "baseRevisionId", "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" ] }, "AIToolCallGetVariables": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getVariables" ] }, "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" ] }, "AIToolCallUpdateVariables": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "updateVariables" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the change in the current conversation." }, "page": { "description": "The page whose variables are being updated. Omitted when updating space variables.", "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "tool", "spaceId", "baseRevisionId" ] }, "AIToolCallGetTags": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getTags" ] }, "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" ] }, "AIToolCallUpdateTags": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "updateTags" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "baseRevisionId": { "type": "string", "description": "The base revision ID used to compare the change in the current conversation." } }, "required": [ "tool", "spaceId", "baseRevisionId" ] }, "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" ] }, "AIToolCallGetChangeRequestDetails": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getChangeRequestDetails" ] }, "spaceId": { "type": "string", "description": "The ID of the space the change request belongs to." }, "changeRequestId": { "type": "string", "description": "The ID of the change request." } }, "required": [ "tool", "spaceId", "changeRequestId" ] }, "AIToolCallSetChangeRequestDetails": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "setChangeRequestDetails" ] }, "spaceId": { "type": "string", "description": "The ID of the space the change request belongs to." }, "changeRequestId": { "type": "string", "description": "The ID of the change request." } }, "required": [ "tool", "spaceId", "changeRequestId" ] }, "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/AIToolCallGetVariables" }, { "$ref": "#/components/schemas/AIToolCallUpdateVariables" }, { "$ref": "#/components/schemas/AIToolCallGetTags" }, { "$ref": "#/components/schemas/AIToolCallUpdateTags" }, { "$ref": "#/components/schemas/AIToolCallCreateChangeRequest" }, { "$ref": "#/components/schemas/AIToolCallGetChangeRequestDetails" }, { "$ref": "#/components/schemas/AIToolCallSetChangeRequestDetails" }, { "$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" }, "filename": { "type": "string", "description": "Name of the image file." } }, "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" } ] }, "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" ] }, "selection": { "type": "object", "description": "Range of the current selection in a document.", "properties": { "anchorKey": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "anchorOffset": { "type": "integer" }, "focusKey": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "focusOffset": { "type": "integer" }, "content": { "type": "string", "description": "Snapshot of the selection for display." } }, "required": [ "anchorKey", "anchorOffset", "focusKey", "focusOffset" ] } } }, "AIMessageStep": { "type": "object", "description": "A step in a message from the AI agent.", "properties": { "startCondition": { "$ref": "#/components/schemas/AIMessageStepStartCondition" }, "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" } }, "context": { "$ref": "#/components/schemas/AIMessageContext" } } }, "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" }, "disabled": { "type": "boolean", "description": "Whether the user is disabled" }, "lastSeenAt": { "description": "Date at which the user was last seen", "$ref": "#/components/schemas/Timestamp" } }, "required": [ "permission", "user", "origin", "disabled" ] }, "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" ] }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_start" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_step_start" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_finish" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_document", "response_reasoning" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_object" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_tool_call" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_tool_call_pending" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" }, "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.\n", "properties": { "type": { "type": "string", "enum": [ "response_followup_suggestion" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "suggestions": { "type": "array", "items": { "type": "string", "description": "A followup message the user could respond with.\n" } } }, "required": [ "type", "messageId", "suggestions" ] }, "AIStreamResponseAttachment": { "type": "object", "description": "Message emitted by the server to indicate that the AI has attached an image.\n", "properties": { "type": { "type": "string", "enum": [ "response_attachment" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" }, "attachment": { "$ref": "#/components/schemas/AIAttachment" } }, "required": [ "type", "messageId", "stepIndex", "attachment" ] }, "AIStreamResponseCompaction": { "type": "object", "description": "Message emitted by the server to indicate a context compaction event.\n", "properties": { "type": { "type": "string", "enum": [ "response_compaction" ] }, "messageId": { "type": "string", "description": "The ID of the message that this event is composing.\n" }, "stepIndex": { "type": "integer", "description": "The index of the step of the message that this event is composing.\n" } }, "required": [ "type", "messageId", "stepIndex" ] }, "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" }, { "$ref": "#/components/schemas/AIStreamResponseCompaction" } ] }, "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.\nIf not defined, it'll default to the IP executing the request.\n" }, "userAgent": { "type": "string", "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" }, "language": { "type": [ "string", "null" ], "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" }, "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.\nThis is used to identify the visitor with adaptive content.\n", "$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", "openai", "claude", "anthropic", "gemini", "perplexity", "cohere", "mistral", "deepseek", "meta", "bytespider", "ccbot", "amazonbot", "youbot", "cursor", "vscode", "claude-code", "codex", "opencode" ] }, "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 }, "SiteMcpServerTransport": { "type": "string", "description": "Transport protocol used to connect to the MCP server", "enum": [ "sse", "http" ], "default": "sse" }, "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" }, "transport": { "$ref": "#/components/schemas/SiteMcpServerTransport" }, "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", "transport", "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" ] }, "SignedURL": { "type": "object", "properties": { "object": { "type": "string", "description": "The kind of signed URL", "enum": [ "signed-url" ] }, "url": { "$ref": "#/components/schemas/URL", "description": "Signed URL that can be opened by the browser" }, "expiresAt": { "$ref": "#/components/schemas/Timestamp", "description": "Expiration time of the signed URL" } }, "required": [ "object", "url", "expiresAt" ] }, "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" } }, "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" ] }, "OrganizationBillingDateOverride": { "description": "Date-based billing override value, either indefinite or a timestamp.", "oneOf": [ { "type": "boolean", "enum": [ true ] }, { "$ref": "#/components/schemas/Timestamp" } ] }, "OrganizationBillingNumericOverride": { "type": "integer", "minimum": 0, "description": "Current numeric billing override, when set." }, "OrganizationBillingOverrides": { "type": "object", "properties": { "overrides": { "type": "object", "properties": { "frozenInterval": { "description": "Current interval-change override, when set.", "$ref": "#/components/schemas/OrganizationBillingDateOverride" }, "enableSAML": { "description": "Current SAML override, when set.", "$ref": "#/components/schemas/OrganizationBillingDateOverride" }, "minUsers": { "description": "Current minimum users override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" }, "maxUsers": { "description": "Current maximum users override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" }, "minPremiumSites": { "description": "Current minimum premium sites override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" }, "maxPremiumSites": { "description": "Current maximum premium sites override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" }, "minUltimateSites": { "description": "Current minimum ultimate sites override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" }, "maxUltimateSites": { "description": "Current maximum ultimate sites override, when set.", "$ref": "#/components/schemas/OrganizationBillingNumericOverride" } } } }, "required": [ "overrides" ] }, "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" } } }, "GitSyncInstallationProvider": { "type": "string", "description": "The provider of the Git Sync installation.", "enum": [ "github", "gitlab" ] }, "GitSyncGitHubRepository": { "type": "object", "description": "GitHub repository that can be selected for Git Sync.", "properties": { "id": { "type": "number" }, "accountName": { "type": "string" }, "repositoryName": { "type": "string" }, "fullName": { "type": "string" }, "defaultBranch": { "type": [ "string", "null" ] } }, "required": [ "id", "accountName", "repositoryName", "fullName", "defaultBranch" ] }, "GitSyncBranch": { "type": "object", "description": "Branch that can be used for Git Sync.", "properties": { "name": { "type": "string" }, "ref": { "type": "string" } }, "required": [ "name", "ref" ] }, "GitSyncGitLabProject": { "type": "object", "description": "GitLab project that can be selected for Git Sync.", "properties": { "id": { "type": "number" }, "accountName": { "type": "string" }, "repositoryName": { "type": "string" }, "fullName": { "type": "string" }, "defaultBranch": { "type": [ "string", "null" ] } }, "required": [ "id", "accountName", "repositoryName", "fullName", "defaultBranch" ] }, "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.\nIf undefined, it'll default to the IP executing the request.\n" }, "userAgent": { "type": "string", "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" }, "language": { "type": "string", "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" } }, "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.\nIf undefined, it'll default to the IP executing the request.\n" }, "userAgent": { "type": "string", "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" }, "language": { "type": "string", "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" } }, "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.\nIt can be used to reference pages in document links.\n" }, "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\n* `failure`: The operation failed\n* `success`: The operation was successful\n", "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\nthe important ones.\n- repo_fetch: Includes fetching the latest repository contents from remote provider.\n- config_check: Includes checking if the YAML config is valid, etc.\n- content_process: Includes processing of pages & files to be imported/exported.\n- finalize: Includes finalizing the sync process like creating the commit on git, or\ncreating a new revision.\n", "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" ] }, "GitSyncSiteStructureSectionGroup": { "type": "object", "additionalProperties": false, "description": "A section group — a container that nests sections (and other section\ngroups). Discriminated by `type: section-group`. Up to one level of nested\nsection groups is allowed.\n", "properties": { "type": { "type": "string", "enum": [ "section-group" ], "description": "Discriminator for a section group node." }, "key": { "type": "string", "description": "Stable identifier for this section group, used as the Git Sync key.\nMust be unique amongst all other section groups of the site. For\nexample: `section-group-product` or `section-group-1`.\n", "minLength": 1 }, "title": { "$ref": "#/components/schemas/SiteSectionGroupTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "icon": { "$ref": "#/components/schemas/Icon" }, "draft": { "type": "boolean", "description": "Whether the section group is draft and not live." }, "children": { "type": "array", "description": "Section or section group nodes nested under this group.", "items": { "oneOf": [ { "$ref": "#/components/schemas/GitSyncSiteStructureSectionGroup" }, { "$ref": "#/components/schemas/GitSyncSiteStructureSection" } ] } } }, "required": [ "type", "key", "title" ] }, "GitSyncSiteStructureSpace": { "type": "object", "additionalProperties": false, "description": "A space — a single content unit in the site's navigation tree. Discriminated\nby `type: space`.\n\nThe space's content lives in the synced repository at the directory pointed\nto by `content.directory`. Hierarchy comes from where the space appears in\nthe YAML (under a section, a section group, or at the root), not from an\nexplicit parent reference.\n", "properties": { "type": { "type": "string", "enum": [ "space" ], "description": "Discriminator for a space node." }, "key": { "type": "string", "description": "Stable identifier for this space, used as the Git Sync key. Must be\nunique amongst all other spaces of the site. For example: `space-docs`\nor `space-1`.\n", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "path": { "$ref": "#/components/schemas/SiteSpacePath" }, "default": { "type": "boolean", "description": "Whether this is the default space for the site." }, "hidden": { "type": "boolean", "description": "Whether the space is hidden from the site's navigation." }, "draft": { "type": "boolean", "description": "Whether the space is draft and not live." }, "condition": { "$ref": "#/components/schemas/Expression" }, "content": { "type": "object", "additionalProperties": false, "description": "Where the space's content lives in the synced repository.", "properties": { "directory": { "type": "string", "description": "Repository-relative directory containing this space's content.", "minLength": 1 }, "language": { "$ref": "#/components/schemas/TranslationLanguage" } }, "required": [ "directory" ] } }, "required": [ "type", "key", "title", "path", "content" ] }, "GitSyncSiteStructureSection": { "type": "object", "additionalProperties": false, "description": "A section — a group of spaces sharing a top-level navigation entry.\nDiscriminated by `type: section`.\n\nSpaces inside a section are listed inline under `children`. A site with\nsections must mark exactly one section with `default: true`.\n", "properties": { "type": { "type": "string", "enum": [ "section" ], "description": "Discriminator for a section node." }, "key": { "type": "string", "description": "Stable identifier for this section, used as the Git Sync key. Must be\nunique amongst all other sections of the site. For example:\n`section-guides` or `section-1`.\n", "minLength": 1 }, "title": { "$ref": "#/components/schemas/SiteSectionTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "description": { "$ref": "#/components/schemas/SiteSectionDescription" }, "localizedDescription": { "$ref": "#/components/schemas/LocalizedString256" }, "icon": { "$ref": "#/components/schemas/Icon" }, "default": { "type": "boolean", "description": "Whether this is the default section for the site." }, "draft": { "type": "boolean", "description": "Whether the section is draft and not live." }, "path": { "$ref": "#/components/schemas/SiteSectionPath" }, "condition": { "$ref": "#/components/schemas/Expression" }, "children": { "type": "array", "description": "Space nodes nested under this section.", "items": { "$ref": "#/components/schemas/GitSyncSiteStructureSpace" } } }, "required": [ "type", "key", "title", "path" ] }, "GitSyncSiteStructureNode": { "description": "A single node in a Git Sync site structure tree — a section group, a\nsection, or a space, discriminated by `type`.\n", "oneOf": [ { "$ref": "#/components/schemas/GitSyncSiteStructureSectionGroup" }, { "$ref": "#/components/schemas/GitSyncSiteStructureSection" }, { "$ref": "#/components/schemas/GitSyncSiteStructureSpace" } ] }, "GitSyncSiteStructure": { "type": "array", "description": "Hierarchical structure of a site in a Git Sync YAML. Each entry is one of\nthree node types: a section group, a section, or a space.\n", "items": { "$ref": "#/components/schemas/GitSyncSiteStructureNode" } }, "GitSyncSiteCustomizationFontSource": { "type": "string", "description": "Reserved repository-relative path to the font file:\n`.gitbook/assets/-.`, where `` is the parent\nfont definition's `key`, `` is this face's `weight`, and\n`` is one of `woff2`, `woff`.\n\nFor example, a font with `key: brand` and a `700` face is read from\n`.gitbook/assets/brand-700.woff2`. Any other path is rejected.\n", "minLength": 1 }, "GitSyncSiteCustomizationFontDefinition": { "type": "object", "description": "Custom font definition for a `site.fonts[]` entry. Referenced from\n`customization.styling.font` or `customization.styling.monospaceFont` via\nits `key`.\n\nRules enforced on a definition:\n- It must declare exactly one face for the `400` weight and one for the\n `700` weight; the `600` weight is optional. No other weights are allowed,\n and a weight may not be declared more than once.\n- Each face has a single source file whose `url` is the reserved repository\n asset path `.gitbook/assets/-.` (`` is `woff2` or\n `woff`). For example a definition with `key: brand` is read from\n `.gitbook/assets/brand-400.woff2` and `.gitbook/assets/brand-700.woff2`.\n", "properties": { "key": { "type": "string", "description": "Stable identifier referenced from `styling.font` /\n`styling.monospaceFont`, and used as the prefix of each face's\nreserved asset path (`.gitbook/assets/-.`).\n", "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "fontFamily": { "$ref": "#/components/schemas/FontFamily" }, "fontFaces": { "type": "object", "description": "Font-face declarations keyed by weight, each specifying its single\nsource file. The `400` and `700` weights are required; `600` is\noptional.\n", "properties": { "400": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontSource" }, "600": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontSource" }, "700": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontSource" } }, "required": [ "400", "700" ], "additionalProperties": false } }, "required": [ "key", "fontFamily", "fontFaces" ] }, "GitSyncSiteCustomizationThemedColor": { "type": "object", "description": "Themed color (light + dark).\n", "properties": { "light": { "$ref": "#/components/schemas/Color" }, "dark": { "$ref": "#/components/schemas/Color" } }, "required": [ "light", "dark" ] }, "GitSyncSiteCustomizationTint": { "type": "object", "description": "Tint configuration.\n", "properties": { "color": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" } }, "required": [ "color" ] }, "GitSyncSiteCustomizationFontReference": { "type": "object", "description": "Reference to a custom font defined under `site.fonts[]`. Matches by `key`.\n", "properties": { "key": { "type": "string", "description": "Matches the `key` of an entry in `site.fonts[]`.", "minLength": 1 } }, "required": [ "key" ] }, "GitSyncSiteCustomizationFont": { "description": "Body font for the site. Either one of the built-in `CustomizationDefaultFont`\nvalues, or a reference to a custom font declared in `site.fonts[]`.\n", "oneOf": [ { "$ref": "#/components/schemas/CustomizationDefaultFont" }, { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontReference" } ] }, "GitSyncSiteCustomizationMonospaceFont": { "description": "Monospace font for the site. Either one of the built-in\n`CustomizationDefaultMonospaceFont` values, or a reference to a custom font\ndeclared in `site.fonts[]`.\n", "oneOf": [ { "$ref": "#/components/schemas/CustomizationDefaultMonospaceFont" }, { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontReference" } ] }, "GitSyncSiteCustomizationThemedCodeTheme": { "type": "object", "description": "Themed code theme (light + dark).\n", "properties": { "light": { "$ref": "#/components/schemas/CustomizationCodeTheme" }, "dark": { "$ref": "#/components/schemas/CustomizationCodeTheme" } }, "required": [ "light", "dark" ] }, "GitSyncSiteCustomizationCodeThemes": { "type": "object", "description": "Code-block syntax-highlighting themes — one for default code blocks and one for OpenAPI request/response samples.\n", "properties": { "default": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedCodeTheme" }, "openapi": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedCodeTheme" } }, "required": [ "default", "openapi" ] }, "GitSyncSiteCustomizationSidebar": { "type": "object", "description": "Sidebar style settings.\n", "properties": { "background": { "$ref": "#/components/schemas/CustomizationSidebarBackgroundStyle" }, "list": { "$ref": "#/components/schemas/CustomizationSidebarListStyle" } }, "required": [ "background", "list" ] }, "GitSyncSiteCustomizationStyling": { "type": "object", "description": "Styling settings.\n", "properties": { "theme": { "$ref": "#/components/schemas/CustomizationTheme" }, "primaryColor": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" }, "tint": { "$ref": "#/components/schemas/GitSyncSiteCustomizationTint" }, "infoColor": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" }, "successColor": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" }, "warningColor": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" }, "dangerColor": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedColor" }, "corners": { "$ref": "#/components/schemas/CustomizationCorners" }, "depth": { "$ref": "#/components/schemas/CustomizationDepth" }, "links": { "$ref": "#/components/schemas/CustomizationLinksStyle" }, "font": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFont" }, "monospaceFont": { "$ref": "#/components/schemas/GitSyncSiteCustomizationMonospaceFont" }, "icons": { "$ref": "#/components/schemas/CustomizationIconsStyle" }, "codeTheme": { "$ref": "#/components/schemas/GitSyncSiteCustomizationCodeThemes" }, "sidebar": { "$ref": "#/components/schemas/GitSyncSiteCustomizationSidebar" }, "search": { "$ref": "#/components/schemas/CustomizationSearchStyle" } } }, "GitSyncSiteCustomizationAssetPath": { "type": "string", "description": "Repository-relative path to an asset in a site Git Sync, e.g.\n`.gitbook/assets/header-logo-light.svg`. Absolute URLs are not accepted\nhere — Git Sync assets must live in the synced repository under\n`.gitbook/assets/`.\n\nThis is the shared base type and only validates the `.gitbook/assets/`\nprefix. Each field that uses it additionally reserves a specific filename\nand set of allowed extensions (e.g. the header logo must be\n`header-logo-light.` / `header-logo-dark.`); see the description\non the consuming field for the exact reserved path.\n", "pattern": "^\\.gitbook/assets/.+", "maxLength": 2048 }, "GitSyncSiteCustomizationThemedAssetPath": { "type": "object", "description": "Light/dark variants of a Git Sync repository asset path. Used for logos and\nfavicons that switch with the active theme. Both variants are required.\n\nEach consuming field reserves the exact light/dark filenames and allowed\nextensions (e.g. header logo → `header-logo-light.` /\n`header-logo-dark.`); see the description on the consuming field.\n", "properties": { "light": { "$ref": "#/components/schemas/GitSyncSiteCustomizationAssetPath" }, "dark": { "$ref": "#/components/schemas/GitSyncSiteCustomizationAssetPath" } }, "required": [ "light", "dark" ] }, "GitSyncSiteCustomizationFavicon": { "description": "Favicon for the published site. The `icon` variant references a repository asset path; the `emoji` variant uses a single emoji character;\n", "oneOf": [ { "type": "object", "properties": { "icon": { "description": "Themed favicon. Each variant must use its reserved repository\nasset path — light: `.gitbook/assets/favicon-light.`,\ndark: `.gitbook/assets/favicon-dark.`, where `` is\nthe image's file extension (e.g. `png`, `svg`, `ico`). Any\nother filename is rejected.\n", "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedAssetPath" } }, "required": [ "icon" ] }, { "type": "object", "properties": { "emoji": { "$ref": "#/components/schemas/Emoji" } }, "required": [ "emoji" ] } ] }, "GitSyncSiteCustomizationContentLinkTo": { "type": "string", "description": "Link destination, written as a path-string in YAML. Same format as\nmarkdown content links, e.g. `https://example.com`, `/pages/`,\n`/spaces//pages/`, `#anchor`, `/files/`, `/spaces/`.\n" }, "GitSyncSiteCustomizationContentLink": { "type": "object", "description": "A label plus a destination, used inside header items, footer groups, and announcements.\n", "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/GitSyncSiteCustomizationContentLinkTo" } }, "required": [ "title", "to" ] }, "GitSyncSiteCustomizationHeaderItem": { "type": "object", "description": "A single item in the published site's top navigation bar.\n", "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": { "description": "Header item destination. Use `null` for items that act as a\ndropdown root without a link of their own.\n", "oneOf": [ { "$ref": "#/components/schemas/GitSyncSiteCustomizationContentLinkTo" }, { "type": "null" } ] }, "links": { "type": "array", "description": "Sub-links shown as a dropdown under this header item. Empty array means no dropdown.", "items": { "$ref": "#/components/schemas/GitSyncSiteCustomizationContentLink" } }, "condition": { "description": "Conditional expression evaluated to decide whether the item is shown to the visitor.", "$ref": "#/components/schemas/Expression" } }, "required": [ "title", "to", "links" ] }, "GitSyncSiteCustomizationHeader": { "type": "object", "description": "Header settings.\n", "properties": { "logo": { "description": "Themed header logo. Each variant must use its reserved repository\nasset path — light: `.gitbook/assets/header-logo-light.`, dark:\n`.gitbook/assets/header-logo-dark.`, where `` is the\nimage's file extension (e.g. `png`, `svg`). Any other filename is\nrejected.\n", "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedAssetPath" }, "primaryLink": { "$ref": "#/components/schemas/GitSyncSiteCustomizationContentLinkTo" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncSiteCustomizationHeaderItem" } } } }, "GitSyncSiteCustomizationFooterGroup": { "type": "object", "description": "A group of links shown in the published site's footer.\n", "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/GitSyncSiteCustomizationContentLink" } } }, "required": [ "title", "links" ] }, "GitSyncSiteCustomizationFooter": { "type": "object", "description": "Footer settings.\n", "properties": { "logo": { "description": "Themed footer logo. Each variant must use its reserved repository\nasset path — light: `.gitbook/assets/footer-logo-light.`, dark:\n`.gitbook/assets/footer-logo-dark.`, where `` is the\nimage's file extension (e.g. `png`, `svg`). Any other filename is\nrejected.\n", "$ref": "#/components/schemas/GitSyncSiteCustomizationThemedAssetPath" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFooterGroup" } }, "copyright": { "type": "string", "maxLength": 300 } } }, "GitSyncSiteCustomizationAnnouncement": { "type": "object", "description": "Announcement banner shown above the published site.\n", "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/GitSyncSiteCustomizationContentLink" }, "style": { "description": "Semantic style of the announcement banner.", "type": "string", "enum": [ "info", "warning", "danger", "success" ] } }, "required": [ "enabled", "message", "style" ] }, "GitSyncSiteCustomizationThemeModes": { "type": "object", "description": "Dark/light theme mode settings.\n", "properties": { "default": { "$ref": "#/components/schemas/CustomizationDefaultThemeMode" }, "toggeable": { "description": "Whether readers can switch between dark and light mode.", "type": "boolean" } }, "required": [ "default", "toggeable" ] }, "GitSyncSiteCustomizationFeedback": { "type": "object", "description": "Reader feedback settings.\n", "properties": { "enabled": { "type": "boolean", "description": "Whether reader feedback gathering is enabled." } }, "required": [ "enabled" ] }, "GitSyncSiteCustomizationAI": { "type": "object", "description": "AI assistant settings.\n", "properties": { "mode": { "$ref": "#/components/schemas/CustomizationAIMode" }, "suggestions": { "$ref": "#/components/schemas/CustomizationSuggestedQuestions" } }, "required": [ "mode" ] }, "GitSyncSiteCustomizationPageActions": { "type": "array", "description": "Ordered page-level action buttons exposed in the published site's page menu.\n", "uniqueItems": true, "items": { "$ref": "#/components/schemas/CustomizationPageActionType" } }, "GitSyncSiteCustomizationExternalLinks": { "type": "object", "description": "External link behavior.\n", "properties": { "target": { "$ref": "#/components/schemas/SiteExternalLinksTarget" } }, "required": [ "target" ] }, "GitSyncSiteCustomizationPagination": { "type": "object", "description": "Pagination navigation settings.\n", "properties": { "enabled": { "type": "boolean", "description": "Whether the prev/next pagination navigation is shown on pages." } }, "required": [ "enabled" ] }, "GitSyncSiteCustomizationPrivacyPolicy": { "type": "object", "description": "Privacy policy link shown on the published site.\n", "properties": { "url": { "$ref": "#/components/schemas/URL" } } }, "GitSyncSiteCustomizationSocialPreview": { "type": "object", "description": "Social preview asset.\n", "properties": { "url": { "description": "Reserved repository asset path for the social preview image:\n`.gitbook/assets/social-preview.`, where `` is the\nimage's file extension (e.g. `png`, `jpg`). Any other filename is\nrejected.\n", "$ref": "#/components/schemas/GitSyncSiteCustomizationAssetPath" } } }, "GitSyncSiteCustomizationSocialAccount": { "type": "object", "description": "A single social account entry.\n", "properties": { "platform": { "$ref": "#/components/schemas/SiteSocialAccountPlatform" }, "handle": { "$ref": "#/components/schemas/SiteSocialAccountHandle" }, "display": { "type": "object", "properties": { "footer": { "type": "boolean" }, "header": { "type": "boolean" } }, "required": [ "footer", "header" ] } }, "required": [ "platform", "handle", "display" ] }, "GitSyncSiteCustomizationInsights": { "type": "object", "description": "Visitor insights settings.\n", "properties": { "trackingCookie": { "type": "boolean", "description": "Whether GitBook identifies visitors on the site using a cookie." } }, "required": [ "trackingCookie" ] }, "GitSyncSiteCustomization": { "type": "object", "description": "Customization settings for the published site, authored in `docs.yaml`.\n\nEvery top-level field is optional — a Git Sync YAML is a **sparse override** of\nthe live customization. Fields you don't include stay at whatever the site\nhas as default.\n\nCustom fonts referenced from `styling.font` / `styling.monospaceFont` must\nhave a matching definition under `site.fonts[]`.\n", "properties": { "publishedTitle": { "description": "Title to use for the published site. If omitted, falls back to the default site title.", "$ref": "#/components/schemas/SiteTitle" }, "localizedPublishedTitles": { "description": "Localized titles for the published site, keyed by locale.", "$ref": "#/components/schemas/LocalizedString128" }, "styling": { "$ref": "#/components/schemas/GitSyncSiteCustomizationStyling" }, "favicon": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFavicon" }, "header": { "$ref": "#/components/schemas/GitSyncSiteCustomizationHeader" }, "footer": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFooter" }, "announcement": { "$ref": "#/components/schemas/GitSyncSiteCustomizationAnnouncement" }, "themeModes": { "$ref": "#/components/schemas/GitSyncSiteCustomizationThemeModes" }, "feedback": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFeedback" }, "ai": { "$ref": "#/components/schemas/GitSyncSiteCustomizationAI" }, "pageActions": { "$ref": "#/components/schemas/GitSyncSiteCustomizationPageActions" }, "externalLinks": { "$ref": "#/components/schemas/GitSyncSiteCustomizationExternalLinks" }, "pagination": { "$ref": "#/components/schemas/GitSyncSiteCustomizationPagination" }, "privacyPolicy": { "$ref": "#/components/schemas/GitSyncSiteCustomizationPrivacyPolicy" }, "socialPreview": { "$ref": "#/components/schemas/GitSyncSiteCustomizationSocialPreview" }, "socialAccounts": { "type": "array", "description": "Social accounts to surface on the site.", "items": { "$ref": "#/components/schemas/GitSyncSiteCustomizationSocialAccount" }, "maxItems": 10 }, "insights": { "$ref": "#/components/schemas/GitSyncSiteCustomizationInsights" } } }, "GitSyncSiteConfig": { "type": "object", "description": "Schema for a site `docs.yaml` file — the canonical contract for what\ncan be authored in Git Sync to drive a site's customization and structure.\n", "properties": { "version": { "type": "integer", "description": "Reserved for future use. When a breaking schema change ships, this\nfield lets the parser branch on the version; absence means v1.\n", "enum": [ 1 ], "default": 1 }, "site": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "Display title for the site.", "minLength": 1 }, "structure": { "$ref": "#/components/schemas/GitSyncSiteStructure" }, "fonts": { "type": "array", "description": "Custom font definitions referenced from `site.customization.styling`.", "items": { "$ref": "#/components/schemas/GitSyncSiteCustomizationFontDefinition" } }, "customization": { "$ref": "#/components/schemas/GitSyncSiteCustomization" } }, "required": [ "title", "structure" ] } }, "required": [ "site" ] }, "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" ] }, "APIChannelGitSyncInstallation": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "git-sync-installation" ] }, "installation": { "type": "string" } }, "required": [ "channel", "installation" ] }, "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/APIChannelGitSyncInstallation" }, { "$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" ] }, "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.\n", "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.\n", "properties": { "type": { "type": "string", "enum": [ "message_response" ] }, "response": { "$ref": "#/components/schemas/AIStreamResponse" } }, "required": [ "type", "response" ] }, "AgentStatus": { "type": "string", "enum": [ "idle", "processing", "errored" ] }, "AgentActivity": { "type": "object", "description": "Describes what the agent is currently doing while processing, used to display a live activity indicator in the conversation.\n", "properties": { "type": { "type": "string", "description": "The kind of activity the agent is currently performing. `thinking` while it reasons or decides on a next action, `tool` while it runs a tool, and `responding` while it writes its answer.\n", "enum": [ "thinking", "tool", "responding" ] }, "tool": { "type": "string", "description": "When `type` is `tool`, the name of the tool being called (matches `AIToolCall.tool`).\n" } }, "required": [ "type" ] }, "AgentQuestionOption": { "type": "object", "description": "An option the user can pick when answering a question asked by the agent.", "properties": { "label": { "type": "string", "description": "Short label for the option, displayed as a button and used as the answer." }, "description": { "type": "string", "description": "Optional longer description to clarify what the option means." } }, "required": [ "label" ] }, "AgentPendingQuestion": { "type": "object", "description": "A question the agent is waiting for the user to answer. While set, the client replaces the prompt with a choice control. The user can pick one of the options or answer with a custom free-text message; either way the answer resolves the pending tool call.\n", "properties": { "toolCallId": { "type": "string", "description": "ID of the tool call this question resolves, used to continue the conversation." }, "question": { "type": "string", "description": "The question to display to the user." }, "options": { "type": "array", "description": "The options the user can choose from.", "items": { "$ref": "#/components/schemas/AgentQuestionOption" } } }, "required": [ "toolCallId", "question", "options" ] }, "AgentState": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/AgentStatus" }, "suggestions": { "type": "array", "description": "List of response suggestions for the user to select from.", "items": { "type": "string" } }, "queuedMessages": { "type": "array", "description": "List of messages sent by the users queued to processed.", "items": { "$ref": "#/components/schemas/AIMessageInput" } }, "activity": { "$ref": "#/components/schemas/AgentActivity", "description": "What the agent is currently doing. Only set while the agent is processing.\n" }, "pendingQuestion": { "$ref": "#/components/schemas/AgentPendingQuestion", "description": "A question the agent is waiting for the user to answer. While set, the client replaces the prompt with a choice control.\n" } }, "required": [ "status", "suggestions", "queuedMessages" ] }, "AgentStreamState": { "type": "object", "description": "Payload emitted by the agent with its current state.\n", "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.\n", "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" } } } }, "UnauthorizedError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "enum": [ 401 ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } } } }