{ "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": "[email protected]" }, "version": "0.0.1-beta" }, "servers": [ { "url": "{host}/v1", "variables": { "host": { "default": "https://api.gitbook.com" } } } ], "security": [ { "user": [] }, { "user-internal": [] }, { "user-staff": [] }, { "user-internal-or-staff": [] }, { "integration": [] }, { "integration-installation": [] } ], "tags": [ { "name": "organizations", "x-page-icon": "building", "x-page-title": "Organizations", "x-page-description": "Manage your organizations and group your members, spaces, and resources under one collaborative structure.", "description": "The Organizations API provides a robust way to handle the administrative structure of your GitBook workspace. By creating and configuring organizations, you can group multiple users, spaces, and collections, simplifying your permission management and fostering efficient collaboration for teams of any size.\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": [] } ], "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 a space by its ID", "tags": [ "spaces", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/siteShareKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } } } }, "patch": { "operationId": "updateSpaceById", "summary": "Update a space", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "editMode": { "$ref": "#/components/schemas/SpaceEditMode" }, "title": { "$ref": "#/components/schemas/SpaceTitle" }, "defaultLevel": { "$ref": "#/components/schemas/DefaultLevel" }, "language": { "$ref": "#/components/schemas/TranslationLanguage" }, "mergeRules": { "$ref": "#/components/schemas/MergeRulesSpaceConfiguration" } } }, { "oneOf": [ { "type": "object", "title": "Emoji", "properties": { "emoji": { "$ref": "#/components/schemas/Emoji" } }, "required": [ "emoji" ] }, { "type": "object", "title": "Icon", "properties": { "icon": { "$ref": "#/components/schemas/URL" } }, "required": [ "icon" ] }, { "type": "object", "title": "Remove icon or emoji", "properties": { "emoji": { "type": "null" }, "icon": { "type": "null" } } } ] } ] } } } }, "responses": { "200": { "description": "The space has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } } } }, "delete": { "operationId": "deleteSpaceById", "summary": "Delete a space", "description": "Deleted spaces will be permanently removed after 7 days.", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "204": { "description": "Space did not exist" }, "205": { "description": "Space has been deleted" } } } }, "/spaces/{spaceId}/duplicate": { "post": { "operationId": "duplicateSpace", "summary": "Duplicate a space", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "201": { "description": "Space duplicated", "headers": { "Location": { "description": "API URL for the newly created space", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } } } } }, "/spaces/{spaceId}/restore": { "post": { "operationId": "restoreSpace", "summary": "Restore a deleted space", "description": "Only spaces deleted in the last 7 days can be restored.", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "200": { "description": "Space restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } } } } }, "/spaces/{spaceId}/move": { "post": { "operationId": "moveSpace", "summary": "Move a space to a new position", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "parent": { "description": "The unique id of the parent collection", "type": [ "string", "null" ] }, "position": { "description": "Where to move the space. By default, it will be moved at the end.", "$ref": "#/components/schemas/ContentPosition" } } } } } }, "responses": { "200": { "description": "Space moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } }, "400": { "description": "Invalid position space or collection provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching Space found for given ID", "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Operation would not result in any update", "$ref": "#/components/responses/ConflictError" } } } }, "/spaces/{spaceId}/embed": { "get": { "operationId": "getEmbedByUrlInSpace", "summary": "Resolve a URL to an embed in a given space", "tags": [ "space-embeds" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "name": "url", "in": "query", "required": true, "description": "URL to resolve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Embed" } } } } } } }, "/spaces/{spaceId}/search": { "get": { "operationId": "searchSpaceContent", "summary": "Search content in a space", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchPageResult" } } } } ] } } } } } } }, "/spaces/{spaceId}/git/import": { "post": { "operationId": "importGitRepository", "summary": "Import a Git repository", "tags": [ "space-git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "204": { "description": "Operation to import the repository has been started." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportGitRepository" } } } } } }, "/spaces/{spaceId}/git/export": { "post": { "operationId": "exportToGitRepository", "summary": "Export the to a Git repository", "tags": [ "space-git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "204": { "description": "Operation to export the space has been started." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportToGitRepository" } } } } } }, "/spaces/{spaceId}/git/info": { "get": { "operationId": "getSpaceGitInfo", "summary": "Get space Git info", "description": "Get metadata about the Git Sync provider currently set up on the space.", "tags": [ "space-git" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "200": { "description": "The Git Sync info for the space", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitSyncState" } } } }, "404": { "description": "No Git provider currently set up on the space", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/git/legacy-installation": { "delete": { "operationId": "deleteLegacyGitInstallation", "summary": "Remove the legacy Git Sync installation from the space to be able to upgrade it to use the new Git integrations", "tags": [ "space-git" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "204": { "description": "The legacy Git installation was already removed" }, "205": { "description": "The legacy Git installation was successfully removed" } } } }, "/spaces/{spaceId}/permissions": { "post": { "operationId": "inviteToSpace", "summary": "Invite a user or a team to a space", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "204": { "description": "OK" }, "404": { "description": "No team or user with the provided Id", "$ref": "#/components/responses/NotFoundError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersAndTeams" } } } } } }, "/spaces/{spaceId}/permissions/teams/{teamId}": { "patch": { "operationId": "updateTeamPermissionInSpace", "summary": "Update an org team's permission in a space", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } } } } } }, "responses": { "204": { "description": "Team permission was updated" }, "404": { "description": "No team found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeTeamFromSpace", "summary": "Remove an org team from a space", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "204": { "description": "The team was not found in the space" }, "205": { "description": "The team has been removed from the space" }, "400": { "description": "Team does not have access to space", "$ref": "#/components/responses/BadRequestError" } } } }, "/spaces/{spaceId}/permissions/users": { "get": { "operationId": "listUserPermissionsInSpace", "summary": "List space user permissions", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of users who have been added to a space.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserContentPermission" } } } } ] } } } }, "404": { "description": "No space was found with the given Id", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/permissions/users/{userId}": { "patch": { "operationId": "updateUserPermissionInSpace", "summary": "Update space user permissions", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } } } } } }, "responses": { "204": { "description": "User permission was updated" }, "404": { "description": "No user found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeUserFromSpace", "summary": "Remove a space user", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "The user was not found in the space" }, "205": { "description": "The user has been removed from the space" } } } }, "/spaces/{spaceId}/permissions/teams": { "get": { "operationId": "listTeamPermissionsInSpace", "summary": "List an org team's permission in a space", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of teams who have been added to a space.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Permission of a team in a space.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRole" }, "team": { "$ref": "#/components/schemas/OrganizationTeam" } }, "required": [ "permission", "team" ] } } } } ] } } } }, "404": { "description": "No space was found with the given Id", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/content": { "get": { "operationId": "getCurrentRevision", "summary": "Get a space current revision", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } } }, "/spaces/{spaceId}/content/template": { "post": { "operationId": "applyTemplateToSpace", "summary": "Apply a template to a space.", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "201": { "description": "Template applied to space." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApplySpaceTemplate" }, { "type": "object", "properties": { "changeRequestId": { "type": "string", "description": "The ID of the change request to apply the template to. If not provided, the template is applied to the main content." } } } ] } } } } } }, "/spaces/{spaceId}/content/pages": { "get": { "operationId": "listPages", "summary": "List all space pages", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPage" } } }, "required": [ "pages" ] } } } } } } }, "/spaces/{spaceId}/content/files": { "get": { "operationId": "listFiles", "summary": "List all space files", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionFile" } } } } ] } } } } } } }, "/spaces/{spaceId}/content/files/{fileId}": { "get": { "operationId": "getFileById", "summary": "Get a space file by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/fileId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionFile" } } } } } } }, "/spaces/{spaceId}/content/files/{fileId}/backlinks": { "get": { "operationId": "listSpaceFileBacklinks", "summary": "List all space file backlink locations", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/fileId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentLocation" } } } } ] } } } } } } }, "/spaces/{spaceId}/content/page/{pageId}": { "get": { "operationId": "getPageById", "summary": "Get a space page by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 space page links", "tags": [ "space-content", "links", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ContentReferenceStatus" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/ContentReferencesStats" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentReferenceUsage" } } }, "required": [ "items", "stats" ] } ] } } } } } } }, "/spaces/{spaceId}/content/page/{pageId}/backlinks": { "get": { "operationId": "listSpacePageBacklinks", "summary": "List all space page backlink locations", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentLocation" } } } } ] } } } } } } }, "/spaces/{spaceId}/content/page/{pageId}/meta-links": { "get": { "operationId": "listSpacePageMetaLinks", "summary": "List all meta links for a space page", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pageId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionPageMetaLinks" } } } } } } }, "/spaces/{spaceId}/content/path/{pagePath}": { "get": { "operationId": "getPageByPath", "summary": "Get a space page by its path", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 space reusable content by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/reusableContentId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionReusableContent" } } } } } } }, "/spaces/{spaceId}/content/computed/document": { "post": { "operationId": "getComputedDocument", "summary": "Get a space computed document", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/documentSchema" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ComputedContentSourceDocument" }, "seed": { "type": "string", "description": "Seed to use for the generation of IDs." } }, "required": [ "source", "seed" ] } } } }, "responses": { "200": { "description": "Document computed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONDocument" } } } } } } }, "/spaces/{spaceId}/content/computed/revision": { "post": { "operationId": "getComputedRevision", "summary": "Get a space computed revision", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ComputedContentSourceRevision" }, "seed": { "type": "string", "description": "Seed to use for the generation of IDs." } }, "required": [ "source", "seed" ] } } } }, "responses": { "200": { "description": "Computed pages and files", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPage" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionFile" } }, "reusableContents": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionReusableContent" } } }, "required": [ "pages", "files", "reusableContents" ] } } } } } } }, "/spaces/{spaceId}/documents/{documentId}": { "get": { "operationId": "getDocumentById", "summary": "Get a space document by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "name": "documentId", "in": "path", "required": true, "description": "ID of the document in the space", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/documentSchema" } ], "responses": { "200": { "description": "Document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONDocument" } } } } } } }, "/spaces/{spaceId}/change-requests": { "post": { "operationId": "createChangeRequest", "summary": "Create a change request", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "201": { "description": "Change Request Created", "headers": { "Location": { "description": "API URL for the newly created change-request", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject of the change-request" }, "template": { "$ref": "#/components/schemas/ApplySpaceTemplate", "description": "Template to apply to the change request" } }, "additionalProperties": true } } } } }, "get": { "operationId": "listChangeRequestsForSpace", "summary": "List all change requests", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/spaceId" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ChangeRequestStatus", "default": "open" }, "description": "If defined, only change requests matching this status will be returned." }, { "name": "creator", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests created by this user will be returned." }, { "name": "contributor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests with contributions from this user will be returned." }, { "name": "requestedReviewer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests with a requested reviewer for this user will be returned." }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests linked to this site topic will be returned." }, { "name": "orderBy", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ChangeRequestOrderBy" } } ], "responses": { "200": { "description": "List of the space's change requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequest" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}": { "get": { "operationId": "getChangeRequestById", "summary": "Get a change request by its ID", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "200": { "description": "The matching change request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } } }, "404": { "description": "The change request could not be found.", "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateChangeRequestById", "summary": "Update a change request", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/ChangeRequestSubject" }, "description": { "$ref": "#/components/schemas/JSONDocument" }, "links": { "$ref": "#/components/schemas/ChangeRequestLinks" }, "status": { "type": "string", "enum": [ "draft", "open", "archived" ] } } } } } }, "responses": { "200": { "description": "The change request has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequest" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": { "post": { "operationId": "mergeChangeRequest", "summary": "Merge a change request", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string", "description": "ID of the resulting revision" }, "result": { "type": "string", "enum": [ "merge", "conflicts" ] } }, "required": [ "revision", "result" ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/update": { "post": { "operationId": "updateChangeRequest", "summary": "Pull primary content into the change request", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "type": "string", "description": "ID of the resulting revision" }, "result": { "type": "string", "enum": [ "update", "conflicts" ] } }, "required": [ "revision", "result" ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": { "get": { "operationId": "getReviewsByChangeRequestId", "summary": "List all change request reviews", "tags": [ "change-requests-reviews" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/documentFormat" }, { "in": "query", "name": "outdated", "description": "Filter reviews marked as outdated.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "All reviews for the given change request.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequestReview" } } } } ] } } } }, "404": { "description": "The change request or space could not be found.", "$ref": "#/components/responses/NotFoundError" } } }, "post": { "operationId": "submitChangeRequestReview", "summary": "Submit a change request review", "tags": [ "change-requests-reviews" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "201": { "headers": { "Location": { "description": "API URL for the newly created review", "schema": { "type": "string" } } }, "description": "A new review has been created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequestReview" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "The status of the submitted review.", "$ref": "#/components/schemas/ChangeRequestReviewStatus" }, "comment": { "description": "Optionally, provide a comment along with the review.", "$ref": "#/components/schemas/Document" } }, "required": [ "status" ] } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews/{reviewId}": { "get": { "operationId": "getChangeRequestReviewById", "summary": "Get a change request review by its ID", "tags": [ "change-requests-reviews" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/reviewId" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "The matching change request review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeRequestReview" } } } }, "404": { "description": "The change request review could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers": { "get": { "operationId": "getRequestedReviewersByChangeRequestId", "summary": "Get all change request reviewers", "tags": [ "change-request-reviewers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "A list of requested reviewers", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequestRequestedReviewer" } } } } ] } } } } } }, "post": { "operationId": "requestReviewersForChangeRequest", "summary": "Request change request reviewers", "tags": [ "change-request-reviewers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "200": { "description": "The requests have successfully been sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "description": "The user requests that were sent.", "items": { "$ref": "#/components/schemas/ChangeRequestRequestedReviewer" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "description": "An array of user ids that will be requested.", "items": { "type": "string" } }, "subject": { "type": "string", "description": "Optionally, update the subject of the change request when requesting reviewers." }, "description": { "$ref": "#/components/schemas/JSONDocument", "description": "Optionally, update the description of the change request when requesting reviewers." } }, "required": [ "users" ] } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers/{userId}": { "delete": { "operationId": "removeRequestedReviewerFromChangeRequest", "summary": "Remove a reviewer from a change request", "tags": [ "change-request-reviewers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Reviewer was not found" }, "205": { "description": "The reviewer has been removed from the change request" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/links": { "get": { "operationId": "listChangeRequestLinks", "summary": "List all change request links", "tags": [ "change-requests-links", "links", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ContentReferenceStatus" } }, { "name": "brokenContext", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "change-request", "space" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/ContentReferencesStats" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentReferenceUsage" } } }, "required": [ "items", "stats" ] } ] } } } }, "404": { "description": "The change request could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/comments": { "get": { "operationId": "listCommentsInChangeRequest", "summary": "List all change request comments", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/targetPage" }, { "$ref": "#/components/parameters/authors" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "post": { "operationId": "postCommentInChangeRequest", "summary": "Create a change request comment", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommentSchema" } } } }, "responses": { "200": { "description": "The comment was posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}": { "get": { "operationId": "getCommentInChangeRequest", "summary": "Get a change request comment", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "The returned comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } }, "delete": { "operationId": "deleteCommentInChangeRequest", "summary": "Delete a change request comment", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" } ], "responses": { "204": { "description": "Comment did not exist." }, "205": { "description": "The comment has been deleted." } } }, "put": { "operationId": "updateCommentInChangeRequest", "summary": "Update a change request comment", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentSchema" } } } }, "responses": { "200": { "description": "The comment was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies": { "get": { "operationId": "listCommentRepliesInChangeRequest", "summary": "List all change request comment replies", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CommentReply" } } } } ] } } } } } }, "post": { "operationId": "postCommentReplyInChangeRequest", "summary": "Create a change request comment reply", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/documentFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommentReplySchema" } } } }, "responses": { "200": { "description": "The reply was posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies/{commentReplyId}": { "get": { "operationId": "getCommentReplyInChangeRequest", "summary": "Get a change request comment reply", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "The returned comment reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } }, "put": { "operationId": "updateCommentReplyInChangeRequest", "summary": "Update a change request comment reply", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentSchema" } } } }, "responses": { "200": { "description": "The reply was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } }, "delete": { "operationId": "deleteCommentReplyInChangeRequest", "summary": "Delete a change request comment reply", "tags": [ "change-request-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" } ], "responses": { "204": { "description": "Comment reply did not exist." }, "205": { "description": "The comment has been deleted." } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": { "get": { "operationId": "getContributorsByChangeRequestId", "summary": "Get all contribors of a change request", "tags": [ "change-request-contributors" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" } ], "responses": { "200": { "description": "Contributors on the change request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequestUserContributor" } } } } ] } } } }, "404": { "description": "The change request could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content": { "get": { "operationId": "getRevisionOfChangeRequestById", "summary": "Get a change request the latest content revision", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/pages": { "get": { "operationId": "listPagesInChangeRequest", "summary": "List all change request pages", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPage" } } }, "required": [ "pages" ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files": { "get": { "operationId": "listFilesInChangeRequestById", "summary": "List all change request files", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionFile" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}": { "get": { "operationId": "getFileInChangeRequestById", "summary": "Get a change request file by its ID", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/fileId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionFile" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}/backlinks": { "get": { "operationId": "listChangeRequestFileBacklinks", "summary": "List all backlink locations of a change request file", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/fileId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentLocation" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}": { "get": { "operationId": "getPageInChangeRequestById", "summary": "Get a change request page by its ID", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 change request links", "tags": [ "change-request-content", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/ContentReferencesStats" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentReferenceUsage" } } }, "required": [ "items", "stats" ] } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/backlinks": { "get": { "operationId": "listChangeRequestPageBacklinks", "summary": "List all backlink locations of a change request page", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentLocation" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/meta-links": { "get": { "operationId": "listChangeRequestPageMetaLinks", "summary": "List all meta links of a change request page", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pageId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionPageMetaLinks" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/reusable-contents/{reusableContentId}": { "get": { "operationId": "getReusableContentInChangeRequestById", "summary": "Get a change request reusable content by its ID", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/reusableContentId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionReusableContent" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/changes": { "get": { "operationId": "getChangeRequestChanges", "summary": "Get change request semantic changes", "description": "Return the semantic changes between a change request and its base revision.", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "name": "limit", "in": "query", "description": "Limit the number of changes returned", "schema": { "type": "number", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionSemanticChanges" } } } }, "404": { "description": "The change request could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/pdf": { "get": { "operationId": "getChangeRequestPDF", "summary": "Get a URL of the content of a change request as PDF", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "in": "query", "name": "only", "description": "Generate a PDF only for the provided page.", "schema": { "type": "boolean" } }, { "in": "query", "name": "page", "description": "ID of a specific page to generate a PDF for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "URL of the PDF", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Temporary URL to print the content. The URL will work for 1h.", "$ref": "#/components/schemas/URL" } }, "required": [ "url" ] } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}": { "get": { "operationId": "getRevisionById", "summary": "Get a space revision", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/changes": { "get": { "operationId": "getRevisionSemanticChanges", "summary": "Get space revision semantic changes", "description": "Return the semantic changes between a revision and its parent.", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" }, { "name": "limit", "in": "query", "description": "Limit the number of changes returned", "schema": { "type": "number", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionSemanticChanges" } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/pages": { "get": { "summary": "List all pages in a space revision", "operationId": "listPagesInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPage" } } }, "required": [ "pages" ] } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/files": { "get": { "summary": "List all space revision files", "operationId": "listFilesInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionFile" } } } } ] } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}": { "get": { "summary": "Get a space revision file by its ID", "operationId": "getFileInRevisionById", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/fileId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionFile" } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": { "get": { "operationId": "getPageInRevisionById", "summary": "Get a space revision page by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 document of a page in a revision", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pageId" }, { "$ref": "#/components/parameters/documentEvaluated" }, { "$ref": "#/components/parameters/documentDereferenced" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONDocument" } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}": { "get": { "operationId": "getPageInRevisionByPath", "summary": "Get a space revision page by its path", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 for a revision page", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/pageId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionPageMetaLinks" } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}": { "get": { "operationId": "getPageInChangeRequestByPath", "summary": "Get a change request page by its path", "tags": [ "change-request-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/pagePath" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/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 space revision reusable content by its ID", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/reusableContentId" }, { "$ref": "#/components/parameters/revisionMetadata" }, { "$ref": "#/components/parameters/revisionComputed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionReusableContent" } } } } } } }, "/spaces/{spaceId}/revisions/{revisionId}/reusable-contents/{reusableContentId}/document": { "get": { "operationId": "getReusableContentDocumentInRevisionById", "summary": "Get the document of a reusable content in a revision", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/reusableContentId" }, { "$ref": "#/components/parameters/documentEvaluated" }, { "$ref": "#/components/parameters/documentDereferenced" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JSONDocument" } } } } } } }, "/spaces/{spaceId}/comments": { "get": { "operationId": "listCommentsInSpace", "summary": "List all space comments", "tags": [ "space-comments", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" }, { "$ref": "#/components/parameters/status" }, { "$ref": "#/components/parameters/documentFormat" }, { "$ref": "#/components/parameters/targetPage" }, { "$ref": "#/components/parameters/authors" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "post": { "operationId": "postCommentInSpace", "summary": "Create a space comment", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommentSchema" } } } }, "responses": { "200": { "description": "The comment was posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } } }, "/spaces/{spaceId}/comments/{commentId}": { "get": { "operationId": "getCommentInSpace", "summary": "Get a space comment", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "The returned comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } }, "delete": { "operationId": "deleteCommentInSpace", "summary": "Delete a space comment", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" } ], "responses": { "204": { "description": "Comment did not exist." }, "205": { "description": "The comment has been deleted." } } }, "put": { "operationId": "updateCommentInSpace", "summary": "Update a space comment", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentSchema" } } } }, "responses": { "200": { "description": "The comment was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } } } } }, "/spaces/{spaceId}/comments/{commentId}/replies": { "get": { "operationId": "listCommentRepliesInSpace", "summary": "List all space comment replies", "tags": [ "space-comment" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CommentReply" } } } } ] } } } } } }, "post": { "operationId": "postCommentReplyInSpace", "summary": "Create a space comment reply", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostCommentReplySchema" } } } }, "responses": { "200": { "description": "The reply was posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } } }, "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": { "get": { "operationId": "getCommentReplyInSpace", "summary": "Get a space comment reply", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" }, { "$ref": "#/components/parameters/documentFormat" } ], "responses": { "200": { "description": "The returned comment reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } }, "put": { "operationId": "updateCommentReplyInSpace", "summary": "Update a space comment reply", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentReplySchema" } } } }, "responses": { "200": { "description": "The reply was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentReply" } } } } } }, "delete": { "operationId": "deleteCommentReplyInSpace", "summary": "Delete a space comment reply", "tags": [ "space-comments" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/commentId" }, { "$ref": "#/components/parameters/commentReplyId" } ], "responses": { "204": { "description": "Comment reply did not exist." }, "205": { "description": "The comment has been deleted." } } } }, "/spaces/{spaceId}/commenters": { "get": { "operationId": "listCommentersInSpace", "summary": "List all users who commented in a space", "tags": [ "space-comments", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMember" } } } } ] } } } } } } }, "/spaces/{spaceId}/change-requests/{changeRequestId}/commenters": { "get": { "operationId": "listCommentersInChangeRequest", "summary": "List all users who commented in a CR", "tags": [ "change-request-comments", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/changeRequestId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMember" } } } } ] } } } } } } }, "/spaces/{spaceId}/permissions/aggregate": { "get": { "operationId": "listPermissionsAggregateInSpace", "summary": "List all space users permissions", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "role", "in": "query", "description": "If defined, only members with this role will be returned.", "schema": { "$ref": "#/components/schemas/MemberRole" } } ], "responses": { "200": { "description": "Listing of users who can access the space.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserContentPermission" } } } } ] } } } } } } }, "/spaces/{spaceId}/integrations": { "get": { "operationId": "listSpaceIntegrations", "summary": "List integrations enabled in a space", "tags": [ "space-integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/integrationSearchQuery" } ], "responses": { "200": { "description": "Listing of integrations enabled in the space.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } ] } } } } } } }, "/spaces/{spaceId}/integration-blocks": { "get": { "operationId": "listSpaceIntegrationsBlocks", "summary": "List all space integrations blocks", "tags": [ "space-integrations" ], "parameters": [ { "$ref": "#/components/parameters/spaceId" } ], "responses": { "200": { "description": "list of installed integration blocks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpaceIntegrationBlocks" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/spaces/{spaceId}/pdf": { "get": { "operationId": "getSpacePDF", "summary": "Get a URL of the content of a space as PDF", "tags": [ "space-content" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "in": "query", "name": "only", "description": "Generate a PDF only for the provided page.", "schema": { "type": "boolean" } }, { "in": "query", "name": "page", "description": "ID of a specific page to generate a PDF for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "URL of the PDF", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Temporary URL to print the content. The URL will work for 1h.", "$ref": "#/components/schemas/URL" } }, "required": [ "url" ] } } } } } } }, "/spaces/{spaceId}/links": { "get": { "operationId": "listSpaceLinks", "summary": "Get all links in a space including their status and location where they appear.", "tags": [ "spaces", "links", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/spaceId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ContentReferenceStatus" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/ContentReferencesStats" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContentReferenceUsage" } } }, "required": [ "items", "stats" ] } ] } } } }, "404": { "description": "The space could not be found.", "$ref": "#/components/responses/NotFoundError" } } } }, "/collections/{collectionId}": { "get": { "operationId": "getCollectionById", "summary": "Get a collection by its ID", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } } } }, "patch": { "operationId": "updateCollectionById", "summary": "Update a collection", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/CollectionTitle" }, "description": { "$ref": "#/components/schemas/CollectionDescription" }, "defaultLevel": { "$ref": "#/components/schemas/DefaultLevel" } } } } } }, "responses": { "200": { "description": "The collection has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } } } }, "delete": { "operationId": "deleteCollectionById", "summary": "Delete a collection", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "responses": { "204": { "description": "Collection did not exist" }, "205": { "description": "Collection has been deleted" } } } }, "/collections/{collectionId}/spaces": { "get": { "operationId": "listSpacesInCollectionById", "summary": "List all collection spaces", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Space" } } } } ] } } } } } } }, "/collections/{collectionId}/move": { "post": { "operationId": "moveCollection", "summary": "Move a collection to a new position.", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "parent": { "description": "The unique id of the parent collection", "type": [ "string", "null" ] }, "position": { "description": "Where to move the collection. By default, it will be moved at the end.", "$ref": "#/components/schemas/ContentPosition" } } } } } }, "responses": { "200": { "description": "Collection moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Invalid position space or collection provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching Collection found for given ID", "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Operation would not result in any update", "$ref": "#/components/responses/ConflictError" } } } }, "/collections/{collectionId}/transfer": { "post": { "operationId": "transferCollection", "summary": "Transfer a collection", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "string", "description": "The unique id of the target organization" } }, "required": [ "organization" ] } } } }, "responses": { "200": { "description": "Collection transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "404": { "description": "No matching Collection found for given ID", "$ref": "#/components/responses/NotFoundError" }, "409": { "description": "Transfer would not result in any update", "$ref": "#/components/responses/ConflictError" }, "412": { "description": "The collection cannot be moved.", "$ref": "#/components/responses/PreconditionFailedError" } } } }, "/collections/{collectionId}/permissions": { "post": { "operationId": "inviteToCollection", "summary": "Invite to a collection", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" } ], "responses": { "204": { "description": "OK" }, "404": { "description": "No team or user with the provided Id", "$ref": "#/components/responses/NotFoundError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersAndTeams" } } } } } }, "/collections/{collectionId}/permissions/teams": { "get": { "operationId": "listTeamPermissionsInCollection", "summary": "List an org team's permission in collection", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of teams who have been added to a collection.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "Permission of a team in a content.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRole" }, "team": { "$ref": "#/components/schemas/OrganizationTeam" } }, "required": [ "permission", "team" ] } } } } ] } } } } } } }, "/collections/{collectionId}/permissions/teams/{teamId}": { "patch": { "operationId": "updateTeamPermissionInCollection", "summary": "Update an org team's permission in a collection", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } } } } } }, "responses": { "204": { "description": "Team permission was updated" }, "404": { "description": "No team found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeTeamFromCollection", "summary": "Remove an org team from a collection", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "204": { "description": "The team was not found in the collection" }, "205": { "description": "The team has been removed from the collection" } } } }, "/collections/{collectionId}/permissions/users": { "get": { "operationId": "listUserPermissionsInCollection", "summary": "List collection user permissions", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of users who have been added to a collection.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserContentPermission" } } } } ] } } } }, "404": { "description": "No space found with the given Id", "$ref": "#/components/responses/NotFoundError" } } } }, "/collections/{collectionId}/permissions/users/{userId}": { "patch": { "operationId": "updateUserPermissionInCollection", "summary": "Update a collection user permission", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } } } } } }, "responses": { "204": { "description": "User permission was updated" }, "404": { "description": "No user found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeUserFromCollection", "summary": "Remove a user from a collection", "tags": [ "collection-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "The user was not found in the collection" }, "205": { "description": "The user has been removed from the collection" } } } }, "/collections/{collectionId}/permissions/aggregate": { "get": { "operationId": "listPermissionsAggregateInCollection", "summary": "List all collections users permissions", "tags": [ "space-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "role", "in": "query", "description": "If defined, only members with this role will be returned.", "schema": { "$ref": "#/components/schemas/MemberRole" } } ], "responses": { "200": { "description": "Listing of users who can access the collections.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserContentPermission" } } } } ] } } } } } } }, "/integrations": { "get": { "operationId": "listIntegrations", "summary": "List all public integrations", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/integrationSearchQuery" }, { "$ref": "#/components/parameters/integrationSearchCategory" }, { "$ref": "#/components/parameters/integrationSearchBlockDomain" }, { "$ref": "#/components/parameters/integrationSearchBlocks" }, { "$ref": "#/components/parameters/integrationSearchContentSources" }, { "$ref": "#/components/parameters/integrationSearchOwner" }, { "$ref": "#/components/parameters/integrationSearchScope" }, { "$ref": "#/components/parameters/integrationSearchTarget" } ], "responses": { "200": { "description": "Paginated list of integrations", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } ] } } } } } } }, "/integrations/{integrationName}": { "get": { "operationId": "getIntegrationByName", "summary": "Get an integration by its name", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/integrationName" } ], "responses": { "200": { "description": "Integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } }, "404": { "description": "No matching integration found for given name", "$ref": "#/components/responses/NotFoundError" } } }, "post": { "operationId": "publishIntegration", "summary": "Publish an integration", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } }, "404": { "description": "Organization could not be found for the given hostname", "$ref": "#/components/responses/NotFoundError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishIntegration" } } } } }, "delete": { "operationId": "unpublishIntegration", "summary": "Unpublish an integration", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" } ], "responses": { "204": { "description": "Integration did not exist" }, "205": { "description": "Integration has been deleted" } } } }, "/integrations/{integrationName}/installations": { "get": { "operationId": "listIntegrationInstallations", "summary": "List all integration installations", "tags": [ "integrations" ], "security": [ { "integration": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "externalId", "in": "query", "description": "External Id to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationInstallation" } } } } ] } } } } } }, "post": { "operationId": "installIntegration", "summary": "Install an integration", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationTarget" } } } }, "responses": { "201": { "headers": { "Location": { "description": "URL for the installed integration", "schema": { "type": "string" } } }, "description": "Integration installed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationInstallation" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/integrations/{integrationName}/events": { "get": { "operationId": "listIntegrationEvents", "summary": "List all integration events", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Paginated list of integration events", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationEvent" } } } } ] } } } } } } }, "/integrations/{integrationName}/events/{eventId}": { "get": { "operationId": "getIntegrationEvent", "summary": "Get an integration event by its ID", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/integrationEventId" } ], "responses": { "200": { "description": "Integration event", "content": { "application/json": { "schema": { "type": "object", "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/IntegrationEvent" }, "trace": { "$ref": "#/components/schemas/IntegrationEventTrace" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/integrations/{integrationName}/spaces": { "get": { "operationId": "listIntegrationSpaceInstallations", "summary": "List all integration space installations", "tags": [ "integrations" ], "security": [ { "integration": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "externalId", "in": "query", "description": "External Id to filter by", "schema": { "type": "string" } }, { "name": "extended", "in": "query", "description": "If true, returns the space object in each items. If false, returns the space ID in each items.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSpaceInstallation" } } } } ] } } } } } } }, "/integrations/{integrationName}/sites": { "get": { "operationId": "listIntegrationSiteInstallations", "summary": "List all integration site installations", "tags": [ "integrations" ], "security": [ { "integration": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "externalId", "in": "query", "description": "External ID to filter by", "schema": { "type": "string" } }, { "name": "extended", "in": "query", "description": "If true, returns the site object in each items. If false, returns the site ID in each items.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationSiteInstallation" } } } } ] } } } } } } }, "/integrations/{integrationName}/dev": { "put": { "operationId": "setIntegrationDevelopmentMode", "summary": "Enable integration dev mode", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tunnelUrl": { "type": "string", "description": "URL of the tunnel to dispatch integration events to", "minLength": 1, "maxLength": 256 }, "all": { "type": "boolean", "default": false, "description": "If set to true, all requests will be forwarded to the tunnel, not just from the owning organization.\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": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { "description": "Integration installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationInstallation" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateIntegrationInstallation", "summary": "Update an integration installation", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { "description": "The installation has been updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationInstallation" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIntegrationInstallation" } } } } }, "delete": { "operationId": "uninstallIntegration", "summary": "Uninstall an integration", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/integrationName" }, { "$ref": "#/components/parameters/installationId" } ], "responses": { "204": { "description": "Integration installation did not exist" }, "205": { "description": "Integration uninstalled successfully" } } } }, "/integrations/{integrationName}/installations/{installationId}/tokens": { "post": { "operationId": "createIntegrationInstallationToken", "summary": "Create an integration installation API token", "description": "Creates a temporary API token of an integration's installation that has access to the installation and it's scopes. You must be authenticated as the integration to obtain this token.\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", "tags": [ "organizations", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } }, "required": [ "items" ] } ] } } } } } } }, "/orgs/{organizationId}": { "get": { "operationId": "getOrganizationById", "summary": "Get an organization by its ID", "tags": [ "organizations", "critical" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "404": { "description": "No matching organization found for given id", "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateOrganizationById", "summary": "Update an organization", "tags": [ "organizations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/OrganizationTitle" }, "emailDomains": { "$ref": "#/components/schemas/OrganizationEmailDomains" }, "hostname": { "$ref": "#/components/schemas/OrganizationHostname" }, "defaultRole": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "defaultContent": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationDefaultContent" }, { "type": "null" } ] }, "logo": { "oneOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "null" } ] }, "sso": { "type": "boolean" }, "ai": { "type": "boolean" }, "inviteLinks": { "type": "boolean" }, "mergeRules": { "$ref": "#/components/schemas/MergeRulesStandaloneConfiguration" } } } } } }, "responses": { "200": { "description": "The organization has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid default content space or collection provided", "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/members": { "get": { "operationId": "listMembersInOrganizationById", "summary": "List all organization members", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" }, { "name": "role", "description": "The Role to filter the member list by", "in": "query", "schema": { "oneOf": [ { "$ref": "#/components/schemas/MemberRole" }, { "type": "string", "enum": [ "guest" ] } ] } }, { "name": "search", "in": "query", "description": "A query to filter the member list (displayName and email)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "The property to sort the results by. When sorting by lastSeenAt, only active members will be listed.", "schema": { "type": "string", "default": "joinedAt", "enum": [ "joinedAt", "lastSeenAt" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMember" } } } } ] } } } } } } }, "/orgs/{organizationId}/members/{userId}": { "get": { "operationId": "getMemberInOrganizationById", "summary": "Get an organization member by its ID", "tags": [ "organization-members", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMember" } } } } } }, "patch": { "operationId": "updateMemberInOrganizationById", "summary": "Update an organization member", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "200": { "description": "The member has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMember" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } } } } } } }, "delete": { "operationId": "removeMemberFromOrganizationById", "summary": "Delete an organization member", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Member did not exist in the organization." }, "205": { "description": "The member was deleted from the organization." } } } }, "/orgs/{organizationId}/ping": { "post": { "operationId": "updateOrganizationMemberLastSeenAt", "summary": "Update an organization member last seen at", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "Organization member has been updated. Optionally returns a JWT token to attach to the user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gitbookVisitorClaims": { "description": "A JTW token containing the claims to attach to this user.", "type": "string" } } } } } } } } }, "/orgs/{organizationId}/members/{userId}/sso": { "post": { "operationId": "setUserAsSSOMemberForOrganization", "summary": "Set a user as an SSO member of an organization", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "200": { "description": "The user has been added as an SSO member of the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMember" } } } } } } }, "/orgs/{organizationId}/members/{userId}/spaces": { "get": { "operationId": "listSpacesForOrganizationMember", "summary": "List an organization member space permissions", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/listOrder" } ], "responses": { "200": { "description": "Listing of spaces that can be accessed by the user in the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemberContentPermission" } } } } ] } } } } } } }, "/orgs/{organizationId}/members/{userId}/teams": { "get": { "operationId": "listTeamsForOrganizationMember", "summary": "List all organization member teams", "tags": [ "organization-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "in": "query", "name": "title", "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "team", "member" ], "properties": { "team": { "$ref": "#/components/schemas/OrganizationTeam" }, "member": { "$ref": "#/components/schemas/TeamMember" } } } } } } ] } } } } } } }, "/orgs/{organizationId}/teams": { "get": { "operationId": "listTeamsInOrganizationById", "summary": "List all teams", "tags": [ "teams" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "in": "query", "name": "owner", "description": "The unique identifier of a member of the organization. Only teams they can manage will be returned.", "schema": { "type": "string" } }, { "in": "query", "name": "title", "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationTeam" } } } } ] } } } } } }, "put": { "operationId": "createOrganizationTeam", "summary": "Create a team", "tags": [ "teams" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "201": { "description": "Team has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationTeam" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/OrganizationTeamTitle" }, "members": { "description": "A list of organization member identifiers", "type": "array", "items": { "type": "string" } } }, "required": [ "title" ] } } } } } }, "/orgs/{organizationId}/teams/{teamId}": { "get": { "operationId": "getTeamInOrganizationById", "summary": "Get a team", "tags": [ "teams" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationTeam" } } } } } }, "patch": { "operationId": "updateTeamInOrganizationById", "summary": "Update a team", "tags": [ "teams" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "The team has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationTeam" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/OrganizationTeamTitle" } }, "required": [ "title" ] } } } } }, "delete": { "operationId": "removeTeamFromOrganizationById", "summary": "Delete a team", "tags": [ "teams" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "204": { "description": "The team did not exist in the organization." }, "205": { "description": "The team was deleted from the organization." } } } }, "/orgs/{organizationId}/teams/{teamId}/members": { "put": { "operationId": "updateMembersInOrganizationTeam", "summary": "Updates members of a team", "description": "Updates members of an organization team, either adding or removing them. If a the same user is included as both an add and a remove, they will be removed from the team.\n", "tags": [ "team-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMembersInOrganizationTeam" } } } }, "responses": { "204": { "description": "Members have been updated" } } }, "get": { "operationId": "listTeamMembersInOrganizationById", "summary": "List all team members", "description": "Lists members, and their roles, for the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationTeamMember" } } } } ] } } } } } } }, "/orgs/{organizationId}/teams/{teamId}/members/{userId}": { "put": { "operationId": "addMemberToOrganizationTeamById", "summary": "Add a team member", "description": "Add or updates member in the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/TeamMemberRole" } } } } } }, "responses": { "204": { "description": "Member has been added to the team" } } }, "delete": { "operationId": "deleteMemberFromOrganizationTeamById", "summary": "Delete a team member", "description": "Deletes member from the specified organization team.\n", "tags": [ "team-members" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Member was not part of the team" }, "205": { "description": "Member has been deleted from the team" } } } }, "/orgs/{organizationId}/invites": { "post": { "operationId": "inviteUsersToOrganization", "summary": "Invite users in an organization", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "string", "description": "The unique identifiers of the users who were added to the organization" } }, "invited": { "type": "number", "description": "The number of users who were added to the organization" }, "failedSSOEmails": { "type": "array", "items": { "type": "string", "description": "A list of emails who were invited to the organization, but who were not added as SSO users as they are members of another org" } } }, "required": [ "users", "invited" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersToOrganization" } } } } } }, "/orgs/{organizationId}/invites/{inviteId}": { "post": { "operationId": "joinOrganizationWithInvite", "summary": "Join an organization with an invite", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/orgs/{organizationId}/link-invites": { "get": { "operationId": "listOrganizationInviteLinks", "summary": "List organization invites", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "List of invite links in the organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InviteLinkToOrganization" } } } } ] } } } } } }, "post": { "operationId": "createOrganizationInvite", "summary": "Create an organization invite", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInvite" } } } }, "responses": { "201": { "description": "The organization invite has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } } }, "/orgs/{organizationId}/link-invites/{inviteId}": { "get": { "operationId": "getOrganizationInviteLink", "summary": "Get an organization by its ID", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "responses": { "200": { "description": "Invite link in the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } }, "patch": { "operationId": "updateOrganizationInviteById", "summary": "Update an organization invite", "tags": [ "organization-invites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Update role of an organization invite", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "required": [ "role" ] }, { "type": "object", "description": "Update level of an organization content invite", "properties": { "level": { "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "required": [ "level" ] } ] } } } }, "responses": { "200": { "description": "The organization invite has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInviteLink" } } } } } }, "delete": { "operationId": "deleteOrganizationInviteById", "summary": "Deletes an organization invite.", "tags": [ "organizations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/inviteId" } ], "responses": { "204": { "description": "Organization invite did not exist" }, "205": { "description": "The organization invite has been deleted" } } } }, "/orgs/{organizationId}/join": { "post": { "operationId": "joinOrganization", "summary": "Join an organization", "description": "Join an organization if the user's verified email domain matches one of the organization's allowed email domains.\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", "tags": [ "organizations" ], "security": [ { "user": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 } }, { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchSpaceResult" } } } } ] } } } } } } }, "/orgs/{organizationId}/change-requests": { "get": { "operationId": "listChangeRequestsForOrganization", "summary": "List all change requests in an organization", "tags": [ "change-requests" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/organizationId" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "array", "description": "If defined, only change requests matching the statuses will be returned.", "items": { "$ref": "#/components/schemas/ChangeRequestStatus" }, "default": [ "open" ] } }, { "name": "creator", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests created by this user will be returned." }, { "name": "contributor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests with contributions from this user will be returned." }, { "name": "requestedReviewer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "If defined, only change requests with a requested reviewer for this user will be returned." }, { "name": "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": "orderBy", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ChangeRequestOrderBy" } } ], "responses": { "200": { "description": "List of the organization's change requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequest" } } } } ] } } } } } } }, "/orgs/{organizationId}/spaces": { "get": { "operationId": "listSpacesInOrganizationById", "summary": "List all spaces", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Space" } } } } ] } } } } } }, "post": { "operationId": "createSpace", "summary": "Create a space", "tags": [ "spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpace" } } } }, "responses": { "201": { "description": "Space created", "headers": { "Location": { "description": "API URL for the newly created space", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Space" } } } } } } }, "/orgs/{organizationId}/collections": { "get": { "operationId": "listCollectionsInOrganizationById", "summary": "List all collections", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "nested", "in": "query", "description": "If true, all nested collections will be listed", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ] } } } } } }, "post": { "operationId": "createCollection", "summary": "Create a collection", "tags": [ "collections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 50 }, "parent": { "type": "string", "description": "ID of a parent collection" } } } } } }, "responses": { "201": { "description": "Collection created", "headers": { "Location": { "description": "API URL for the newly created collection", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } } } } }, "/orgs/{organizationId}/integrations": { "get": { "operationId": "listOrganizationIntegrations", "summary": "List all public integrations along with private ones trusted by the specific org.", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/integrationSearchQuery" }, { "$ref": "#/components/parameters/integrationSearchCategory" }, { "$ref": "#/components/parameters/integrationSearchBlockDomain" }, { "$ref": "#/components/parameters/integrationSearchBlocks" }, { "$ref": "#/components/parameters/integrationSearchContentSources" }, { "$ref": "#/components/parameters/integrationSearchOwner" }, { "$ref": "#/components/parameters/integrationSearchScope" }, { "$ref": "#/components/parameters/integrationSearchTarget" } ], "responses": { "200": { "description": "List of integrations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } ] } } } } } } }, "/orgs/{organizationId}/integrations/{integrationName}/installation_status": { "get": { "operationId": "getOrganizationIntegrationStatus", "summary": "Get the status of an integration", "tags": [ "integrations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/integrationName" } ], "responses": { "200": { "description": "Integration installation status", "content": { "application/json": { "schema": { "properties": { "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" } }, "required": [ "status" ] } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/installations": { "get": { "operationId": "listOrganizationInstallations", "summary": "List all integration installations", "tags": [ "integrations" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/integrationSearchQuery" } ], "responses": { "200": { "description": "List of integrations with the associated installations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "installation": { "$ref": "#/components/schemas/IntegrationInstallation" }, "integration": { "$ref": "#/components/schemas/Integration" } }, "required": [ "integration", "installation" ] } } } } ] } } } } } } }, "/orgs/{organizationId}/integrations/installations-status": { "get": { "operationId": "listOrganizationIntegrationsStatus", "summary": "List all integration statuses", "tags": [ "integrations", "critical" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "target", "in": "query", "description": "Filter installations by their target (organization, space, or site). When not provided, defaults to organization-level installations for backwards compatibility", "schema": { "type": "string", "default": "organization", "enum": [ "organization", "space", "site" ] } } ], "responses": { "200": { "description": "List of installed integrations and their statuses", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledIntegration" } } } } ] } } } } } } }, "/orgs/{organizationId}/saml": { "get": { "operationId": "listSAMLProvidersInOrganizationById", "summary": "List all SAML providers", "description": "Lists SAML providers configured for the specified organization.\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": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/documentFormat" }, { "name": "details", "in": "query", "description": "Return query details in the result", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchAIQuery" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "$ref": "#/components/schemas/SearchAIAnswer" } } } } } } } } }, "/orgs/{organizationId}/ask/questions": { "get": { "operationId": "getRecommendedQuestionsInOrganization", "summary": "List recommended questions to ask in an organization", "tags": [ "organization-ask" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "security": [ { "user": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchAIRecommendedQuestions" } } } } } } }, "/orgs/{organizationId}/ask/questions/stream": { "get": { "operationId": "streamRecommendedQuestionsInOrganization", "summary": "List recommended questions to ask in an organization (streamed)", "tags": [ "organization-ask" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "security": [ { "user": [] } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" } } } } } } }, "/orgs/{organizationId}/ask/stream": { "get": { "operationId": "streamAskInOrganization", "summary": "Ask a question in an organization (streamed)", "description": "Ask a question to an AI across spaces that is accessible by the currently authenticated target and stream the answer as a Server-Sent Events URL.", "tags": [ "organization-ask" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/documentFormat" }, { "name": "details", "in": "query", "description": "Return query details in the result", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SearchAIAnswerStream" } } } } } } }, "/orgs/{organizationId}/openapi": { "get": { "operationId": "listOpenAPISpecs", "summary": "List all OpenAPI spec", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAPISpec" } } } } ] } } } } } }, "post": { "operationId": "createOpenAPISpec", "summary": "Create an OpenAPI spec", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "$ref": "#/components/schemas/OpenAPISpecSlug" }, "source": { "$ref": "#/components/schemas/OpenAPISpecSource" } }, "required": [ "source", "slug" ] } } } }, "responses": { "201": { "description": "OpenAPI specification has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpec" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/openapi/{specSlug}": { "get": { "operationId": "getOpenAPISpecBySlug", "summary": "Get an OpenAPI spec by its slug", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpec" } } } }, "404": { "description": "No matching OpenAPI specification found", "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "createOrUpdateOpenAPISpecBySlug", "summary": "Create or update an OpenAPI spec", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/OpenAPISpecSource" } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "OpenAPI specification has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpec" } } } }, "201": { "description": "OpenAPI specification has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpec" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "patch": { "operationId": "updateOpenAPISpecBySlug", "summary": "Update OpenAPI spec visibility", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "$ref": "#/components/schemas/OpenAPISpecVisibility" } }, "required": [ "visibility" ] } } } }, "responses": { "200": { "description": "OpenAPI specification visibility has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpec" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching OpenAPI specification found", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "deleteOpenAPISpecBySlug", "summary": "Delete an OpenAPI spec", "tags": [ "openapi" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "responses": { "204": { "description": "Specification did not exist" }, "205": { "description": "OpenAPI specification has been deleted" } } } }, "/orgs/{organizationId}/openapi/{specSlug}/versions": { "get": { "operationId": "listOpenAPISpecVersions", "summary": "List all OpenAPI spec versions", "tags": [ "openapi-versions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAPISpecVersion" } } } } ] } } } }, "404": { "description": "No matching OpenAPI specification found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/openapi/{specSlug}/versions/latest": { "get": { "operationId": "getLatestOpenAPISpecVersion", "summary": "Get the latest OpenAPI spec version", "tags": [ "openapi-versions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpecVersion" } } } }, "404": { "description": "No matching OpenAPI specification version found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content": { "get": { "operationId": "getLatestOpenAPISpecVersionContent", "summary": "Get the latest OpenAPI spec version content", "tags": [ "openapi-versions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpecContent" } } } }, "404": { "description": "No matching OpenAPI specification version found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}": { "get": { "operationId": "getOpenAPISpecVersionById", "summary": "Get an OpenAPI spec version by its ID", "tags": [ "openapi-versions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" }, { "$ref": "#/components/parameters/openapiSpecVersionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpecVersion" } } } }, "404": { "description": "No matching OpenAPI specification version found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/openapi/{specSlug}/versions/{versionId}/content": { "get": { "operationId": "getOpenAPISpecVersionContentById", "summary": "Get an OpenAPI spec version content by its ID", "tags": [ "openapi-versions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/openapiSpecSlug" }, { "$ref": "#/components/parameters/openapiSpecVersionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAPISpecContent" } } } }, "404": { "description": "No matching OpenAPI specification version found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/agent-instructions": { "get": { "operationId": "getOrganizationAgentInstructions", "summary": "Get Docs agent instructions for an organization", "tags": [ "organizations", "agents" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationAgentInstructions" } } } } } }, "put": { "operationId": "updateOrganizationAgentInstructions", "summary": "Update Docs agent instructions for an organization", "tags": [ "organizations", "agents" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "instructions" ], "properties": { "instructions": { "$ref": "#/components/schemas/JSONDocument", "description": "Document describing the Docs agent instructions." } } } } } }, "responses": { "200": { "description": "Updated instructions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationAgentInstructions" } } } } } } }, "/orgs/{organizationId}/translations": { "get": { "operationId": "listTranslations", "summary": "List all the translations", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } } } } ] } } } } } }, "post": { "operationId": "createTranslation", "summary": "Create a translation", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/TranslationSource" }, "language": { "$ref": "#/components/schemas/TranslationLanguage" }, "instructions": { "$ref": "#/components/schemas/JSONDocument" } }, "required": [ "language", "source" ] } } } }, "responses": { "201": { "description": "Translation has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/translations/{translationId}": { "get": { "operationId": "getTranslation", "summary": "Get a translation by its ID", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/translationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "404": { "description": "No matching translation found", "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "updateTranslation", "summary": "Update a translation", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/translationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "instructions" ], "properties": { "instructions": { "$ref": "#/components/schemas/JSONDocument" } } } } } }, "responses": { "200": { "description": "Translation has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Translation" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "delete": { "operationId": "deleteTranslation", "summary": "Delete a translation", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/translationId" } ], "responses": { "204": { "description": "Translation did not exist" }, "205": { "description": "Translation has been deleted" } } } }, "/orgs/{organizationId}/translations/{translationId}/run": { "post": { "operationId": "runTranslation", "summary": "Run a translation again", "tags": [ "translations" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/translationId" } ], "responses": { "204": { "description": "Translation run triggered" }, "404": { "description": "No matching translation found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/translations-glossary": { "get": { "operationId": "listGlossaryEntries", "summary": "List glossary entries", "tags": [ "glossary" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "orderBy", "in": "query", "description": "Sort results by language key", "schema": { "$ref": "#/components/schemas/TranslationLanguage" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GlossaryEntry" } } } } ] } } } } } }, "put": { "operationId": "updateGlossaryEntries", "summary": "Update glossary entries", "tags": [ "glossary" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/GlossaryBatchOperation" } } }, "required": [ "operations" ] } } } }, "responses": { "204": { "description": "Glossary entries updated" }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/translations-glossary/{glossaryEntryId}": { "get": { "operationId": "getGlossaryEntry", "summary": "Get a glossary entry by its ID", "tags": [ "glossary" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/glossaryEntryId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlossaryEntry" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/storage/upload": { "post": { "operationId": "generateStorageUploadURL", "summary": "Create a signed URL to upload a file", "description": "Generate a pre-signed URL that can be used to upload a file to storage", "tags": [ "storage" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file", "kind" ], "properties": { "file": { "$ref": "#/components/schemas/StorageFileMetadata" }, "kind": { "$ref": "#/components/schemas/StorageUploadKind" } } } } } }, "responses": { "201": { "description": "Successfully generated signed URL for file upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageUploadURL" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/fonts": { "get": { "operationId": "listCustomFonts", "summary": "List all custom fonts", "tags": [ "custom-fonts" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomizationFontDefinition" } } } } ] } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "createCustomFont", "summary": "Create a custom font", "tags": [ "custom-fonts" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Defines a custom font and associated font faces with storage references.", "properties": { "fontFamily": { "$ref": "#/components/schemas/FontFamily" }, "fontFaces": { "type": "array", "description": "Array of font faces specifying weights and their corresponding storage keys.\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": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/ContentImportSource" }, "target": { "$ref": "#/components/schemas/ContentImportTarget" }, "enhance": { "description": "Enhance the imported content with AI", "default": true, "type": "boolean" } }, "required": [ "source", "target" ] } } } }, "responses": { "201": { "description": "Import run created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentImportRun" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/org/{organizationId}/imports/{importRunId}/cancel": { "post": { "operationId": "cancelImportRun", "summary": "Cancel an import run", "tags": [ "imports" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/importRunId" } ], "responses": { "201": { "description": "Import run canceled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentImportRun" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites": { "get": { "operationId": "listSites", "summary": "List all sites", "tags": [ "sites", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "space", "in": "query", "description": "Identifier of the space to filter the sites by", "required": false, "schema": { "type": "string" } }, { "name": "title", "in": "query", "description": "Filter sites by their title", "required": false, "schema": { "type": "string" } }, { "name": "published", "in": "query", "description": "Filter sites by their published status", "required": false, "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "description": "Filter by site type", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteType" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } ] } } } } } }, "post": { "operationId": "createSite", "summary": "Create a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "The type of the site, defaults to Basic", "$ref": "#/components/schemas/SiteType" }, "title": { "$ref": "#/components/schemas/SiteTitle" }, "visibility": { "$ref": "#/components/schemas/SiteVisibility" }, "spaces": { "type": "array", "description": "ID of spaces to be added to the site", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Site created", "headers": { "Location": { "description": "API URL for the newly created site", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}": { "get": { "operationId": "getSiteById", "summary": "Get a site by its ID", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "404": { "description": "No matching site found", "$ref": "#/components/responses/NotFoundError" } } }, "patch": { "operationId": "updateSiteById", "summary": "Update a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/SiteTitle" }, "visibility": { "$ref": "#/components/schemas/SiteVisibility" }, "basename": { "$ref": "#/components/schemas/SiteBasename" }, "adaptiveContent": { "$ref": "#/components/schemas/SiteAdaptiveContent" }, "permissionsModel": { "$ref": "#/components/schemas/SitePermissionsModel" }, "defaultLevel": { "$ref": "#/components/schemas/DefaultLevel" }, "defaultSiteSpace": { "type": "string", "description": "ID of the site-space to be used as the default at the root level. If site has sections, this will mark the default site space in the site's default section." }, "defaultSiteSection": { "type": "string", "description": "ID of the site-section to be used as the default." }, "proxy": { "description": "Configure a proxy URL for a site. For example, you can use it to host the site on a subdirectory of your domain like `https://company.com/docs`.\nUse `null` to remove the proxy.\n", "oneOf": [ { "$ref": "#/components/schemas/SiteProxyOrigin" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } } } }, "delete": { "operationId": "deleteSiteById", "summary": "Delete a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "204": { "description": "Site did not exist" }, "205": { "description": "Site has been deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/adaptive-schema": { "get": { "operationId": "getSiteAdaptiveSchema", "summary": "Get the JSON schema describing the attributes expected for an Adaptive content site visitor.", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "The JSON schema that defines the attributes expected from a visitor of the Adaptive content site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAdaptiveSchema" } } } }, "404": { "description": "No visitor attributes schema found for the site.", "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, "put": { "operationId": "updateSiteAdaptiveSchema", "summary": "Update the JSON schema of the attributes expected for an Adaptive content site visitor.", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonSchema": { "description": "The JSON schema to set on the site.", "$ref": "#/components/schemas/SiteAdaptiveJSONSchema" } }, "required": [ "jsonSchema" ] } } } }, "responses": { "200": { "description": "The site adaptive schema has been updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAdaptiveSchema" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/orgs/{organizationId}/sites/{siteId}/adaptive-schema/template-conditions": { "get": { "operationId": "listSiteAdaptiveTemplateConditions", "summary": "List templates of conditions generated based on the site visitor schema that can be used in adaptive content expressions.", "tags": [ "sites" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "List of template conditions generated based on the site visitor schema.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteAdaptiveTemplateCondition" } } }, "required": [ "items" ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/published": { "get": { "operationId": "getPublishedContentSite", "summary": "Get a published site", "description": "Get the complete profile of a site in an organization to provide the published experience. It includes site, customization, structure, integration scripts etc.", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteShareKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedContentSite" } } } }, "404": { "description": "No matching site found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/publish": { "post": { "operationId": "publishSite", "summary": "Publish a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "Site published successfully", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Site" }, { "type": "object", "description": "User needs to checkout in order to publish the site.", "properties": { "type": { "type": "string", "enum": [ "checkout" ] }, "sessionId": { "type": "string", "description": "Stripe payment session ID" } }, "required": [ "type", "sessionId" ] } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/unpublish": { "post": { "operationId": "unpublishSite", "summary": "Unpublish a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "Site unpublished successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/share-links": { "get": { "operationId": "listSiteShareLinks", "summary": "List all share links", "tags": [ "site-share-links" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "search", "in": "query", "description": "Search share links by name or key", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } } } } ] } } } } } }, "post": { "operationId": "createSiteShareLink", "summary": "Create a share link", "tags": [ "site-share-links" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/ShareLinkName" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "The share link has been created", "headers": { "Location": { "description": "API URL for the newly created share link", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}": { "patch": { "operationId": "updateSiteShareLinkById", "summary": "Update a share link", "tags": [ "site-share-links" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/shareLinkId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "active": { "type": "boolean" }, "name": { "$ref": "#/components/schemas/ShareLinkName" } } } } } }, "responses": { "200": { "description": "The site share link has been updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareLink" } } } } } }, "delete": { "operationId": "deleteSiteShareLinkById", "summary": "Deletes a share link", "tags": [ "site-share-links" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/shareLinkId" } ], "responses": { "204": { "description": "Site share link did not exist" }, "205": { "description": "Site share link has been deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/structure": { "get": { "operationId": "getSiteStructure", "summary": "Get a site structure", "description": "Get the complete structure of a site that includes all its site-sections and site-spaces.", "tags": [ "site-structure" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteShareKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteStructure" } } } }, "404": { "description": "No matching site found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/structure/sort": { "patch": { "operationId": "sortSiteStructure", "summary": "Move a site space, site section or site section group to a new position in the site structure.", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "description": "pointer to the item (site space, site section or site section group) being moved.", "$ref": "#/components/schemas/SiteStructureItemPointer" }, "position": { "description": "The position to move the item to. When not provided the item is moved to the end of the site structure.", "$ref": "#/components/schemas/SiteStructureItemMovePosition" } }, "required": [ "item", "position" ] } } } }, "responses": { "200": { "description": "Item successfully moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteStructureItem" } } } }, "400": { "description": "Invalid move position provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching item found", "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/orgs/{organizationId}/sites/{siteId}/publishing/auth": { "get": { "operationId": "getSitePublishingAuthById", "summary": "Get a site auth config", "tags": [ "site-publishing-auth" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePublishingAuth" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "patch": { "operationId": "updateSitePublishingAuthById", "summary": "Update a site auth config", "tags": [ "site-publishing-auth" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePublishingAuthUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePublishingAuth" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate": { "post": { "operationId": "regenerateSitePublishingAuthById", "summary": "Regenerate a site auth", "description": "Regenerate the publishing authentication settings for a site. This will re-generate the private key.", "tags": [ "site-publishing-auth" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePublishingAuth" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/publishing/preview": { "get": { "operationId": "getSitePublishingPreviewById", "summary": "Get a site preview URL", "description": "Generate a URL to preview the published content of a site. The URL will be valid for 1 hour.", "tags": [ "site-preview" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "siteSpace", "in": "query", "description": "ID of the site-space to preview. If not provided, the default site-space will be used.", "schema": { "type": "string" } }, { "name": "claims", "in": "query", "description": "Rison encoded string of attributes/assertions about the visitor for which we want to preview the site.", "schema": { "type": "string" } }, { "name": "draft", "in": "query", "description": "Whether to include draft content in the preview. Defaults to true", "schema": { "type": "boolean", "default": true } }, { "name": "target", "in": "query", "description": "Target URL of the preview. If not provided, the default site preview URL will be used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/URL" } }, "required": [ "url" ] } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/customization": { "get": { "operationId": "getSiteCustomizationById", "summary": "Get a site customization settings", "tags": [ "site-customization" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteCustomizationUnmasked" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCustomizationSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "put": { "operationId": "updateSiteCustomizationById", "summary": "Update a site customization settings", "tags": [ "site-customization" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCustomizationSettingsInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCustomizationSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/integration-scripts": { "get": { "operationId": "listSiteIntegrationScripts", "summary": "List the scripts to embed in published content for a site.", "tags": [ "integrations", "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteIntegrationScript" } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/integrations": { "get": { "operationId": "listSiteIntegrations", "summary": "List integrations enabled in a site.", "tags": [ "integrations", "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/integrationSearchQuery" } ], "responses": { "200": { "description": "Listing of integrations enabled in the site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/site-spaces": { "post": { "operationId": "addSpaceToSite", "summary": "Add a space to a site", "tags": [ "site-spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "description": "ID of the space" }, "sectionId": { "type": "string", "description": "ID of the section to add the space to. If not provided, the space will be added to the default section or at the root level if the site has no sections." }, "draft": { "type": "boolean", "default": false, "description": "Whether the site space should be created as draft. Defaults to false." } }, "required": [ "spaceId" ] } } } }, "responses": { "201": { "description": "Space added to the site", "headers": { "Location": { "description": "API URL for the newly created site-space relationship", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSpace" } } } } } }, "get": { "operationId": "listSiteSpaces", "summary": "List all the site spaces", "tags": [ "site-spaces", "critical" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteShareKey" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "default", "in": "query", "description": "If true, only the default site space will be returned. If false, only the non-default site spaces are returned. If undefined, all site spaces are returned.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSpace" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/section-groups": { "get": { "operationId": "listSiteSectionGroups", "summary": "List all site section groups", "tags": [ "site-section-groups" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSectionGroup" } } } } ] } } } } } }, "post": { "operationId": "addSectionGroupToSite", "summary": "Add a section group to a site", "tags": [ "site-section-groups" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/SiteSectionGroupTitle" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/Icon" }, { "type": "null" } ] }, "sections": { "type": "array", "items": { "type": "string" }, "description": "IDs of the sections to be added to the section group" }, "parent": { "type": "string", "description": "ID of the parent section group to nest this group under. If not provided, the section group will be added at the root of the site." }, "draft": { "type": "boolean", "description": "Whether the section group should be created in draft mode." } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Section group added to the site", "headers": { "Location": { "description": "API URL for the newly created site-section-group relationship", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSectionGroup" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}": { "patch": { "operationId": "updateSiteSectionGroupById", "summary": "Update a site section group", "tags": [ "site-section-groups" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionGroupId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/SiteSectionGroupTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/Icon" }, { "type": "null" } ] }, "draft": { "type": "boolean", "description": "Whether the site section group is draft and not live." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSectionGroup" } } } } } }, "delete": { "operationId": "deleteSiteSectionGroupById", "summary": "Delete a site section group", "tags": [ "site-section-groups" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionGroupId" } ], "responses": { "204": { "description": "Site section group did not exist" }, "205": { "description": "Site section group has been deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/sections": { "post": { "operationId": "addSectionToSite", "summary": "Add a section to a site", "tags": [ "site-sections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "description": "ID of the space to be added to the section as a site space variant" }, "title": { "oneOf": [ { "$ref": "#/components/schemas/SiteSectionTitle" }, { "type": "null" } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/Icon" }, { "type": "null" } ] }, "draft": { "type": "boolean", "description": "Whether the section should be created in draft mode." }, "siteSectionGroupId": { "type": "string", "description": "ID of the section group to create the section in" } }, "required": [ "spaceId" ] } } } }, "responses": { "201": { "description": "Section added to the site", "headers": { "Location": { "description": "API URL for the newly created site-section relationship", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSection" } } } } } }, "get": { "operationId": "listSiteSections", "summary": "List all site sections", "tags": [ "site-sections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteShareKey" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSection" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}": { "patch": { "operationId": "updateSiteSectionById", "summary": "Update a site section", "tags": [ "site-sections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/SiteSectionTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "path": { "$ref": "#/components/schemas/SiteSectionPath" }, "defaultSiteSpace": { "type": "string", "description": "ID of the site-space to be used as the default in this section." }, "condition": { "description": "Conditional expression used to evaluate whether the site section should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.", "oneOf": [ { "$ref": "#/components/schemas/Expression" }, { "type": "null" } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/Icon" }, { "type": "null" } ] }, "draft": { "type": "boolean", "description": "Whether the site section is draft and not live." }, "description": { "oneOf": [ { "$ref": "#/components/schemas/SiteSectionDescription" }, { "type": "null" } ] }, "localizedDescription": { "$ref": "#/components/schemas/LocalizedString256" }, "siteSectionGroupId": { "description": "ID of the section group to move the section into. Set to null to move the section to the root of the site.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSection" } } } } } }, "delete": { "operationId": "deleteSiteSectionById", "summary": "Delete a site section", "tags": [ "site-sections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionId" } ], "responses": { "204": { "description": "Site section did not exist" }, "205": { "description": "Site section has been deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/search": { "post": { "operationId": "searchSiteContent", "summary": "Search in a site", "tags": [ "sites" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 512 } } }, { "oneOf": [ { "type": "object", "required": [ "scope" ], "properties": { "scope": { "description": "Define the scope of the search.", "$ref": "#/components/schemas/SiteSearchScope" } } }, { "type": "object", "properties": { "mode": { "description": "Search only in the site spaces provided. Deprecated, use scope instead.", "deprecated": true, "type": "string", "enum": [ "specific" ] }, "siteSpaceIds": { "type": "array", "minLength": 1, "items": { "type": "string" } } }, "required": [ "siteSpaceIds" ] }, { "type": "object", "properties": { "mode": { "description": "Search in the current site space and all section's defaults. Deprecated, use scope instead.", "deprecated": true, "type": "string", "enum": [ "current" ] }, "siteSpaceId": { "type": "string" } }, "required": [ "mode", "siteSpaceId" ] }, { "type": "object", "properties": { "mode": { "description": "Search in all site-spaces. Deprecated, use scope instead.", "deprecated": true, "type": "string", "enum": [ "all" ] } }, "required": [ "mode" ] } ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchSpaceResult" }, { "$ref": "#/components/schemas/SearchRecordResult" } ], "discriminator": { "propertyName": "type" } } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/ask": { "post": { "operationId": "streamAskInSite", "summary": "Ask a question in a site", "description": "The response is streamed.", "tags": [ "site-ask" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/documentFormat" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question", "scope" ], "properties": { "question": { "type": "string", "maxLength": 512 }, "context": { "type": "object", "description": "You may optionally provide additional information about the context of the question. This doesn't affect the scope of the search, but GitBook may use this information to provide a better answer. Generally speaking, you should provide as much context as possible.\n", "properties": { "siteSpaceId": { "type": "string" } } }, "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": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "siteSpaceId", "in": "query", "description": "The ID of the site space to filter the recommended questions for.", "schema": { "type": "string" } }, { "name": "spaceId", "in": "query", "description": "The ID of the space to filter the recommended questions for.", "deprecated": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/context-records": { "get": { "operationId": "listSiteContextRecords", "summary": "List all context records", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "type", "in": "query", "description": "Filter context records by type.", "schema": { "$ref": "#/components/schemas/ContextRecordType" } }, { "name": "connector", "in": "query", "description": "Filter context records by connector type.", "schema": { "$ref": "#/components/schemas/ContextConnector" } }, { "name": "connection", "in": "query", "description": "Filter context records by connection id.", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "description": "Filter context records by associated site topic ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRecord" } } } } ] } } } } } }, "put": { "operationId": "upsertSiteContextRecords", "summary": "Create or update context records", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRecordInput" } } } } }, "responses": { "204": { "description": "The context records have been created or updated" } } } }, "/orgs/{organizationId}/sites/{siteId}/context-records/{siteContextRecordId}": { "get": { "operationId": "getSiteContextRecordById", "summary": "Get a context record", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteContextRecordId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextRecord" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/scans": { "get": { "operationId": "listSiteScans", "summary": "List all site scans", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "topic", "in": "query", "description": "Filter scans by associated site topic ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter scans by status.", "schema": { "$ref": "#/components/schemas/SiteScanStatus" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteScan" } } } } ] } } } } } }, "post": { "operationId": "createSiteScan", "summary": "Enqueue a new site scan", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "topic" ], "properties": { "topic": { "type": "string", "description": "The site topic ID to scan." } } } } } }, "responses": { "202": { "description": "Site scan has been enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteScan" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/scans/{siteScanId}": { "get": { "operationId": "getSiteScanById", "summary": "Get a site scan by ID", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteScanId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteScan" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings": { "get": { "operationId": "listSiteFindings", "summary": "List all site context findings", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "topic", "in": "query", "description": "Filter findings by associated site topic ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter findings by status.", "schema": { "$ref": "#/components/schemas/SiteFindingStatus" } }, { "name": "type", "in": "query", "description": "Filter findings by type.", "schema": { "$ref": "#/components/schemas/SiteFindingType" } }, { "name": "severity", "in": "query", "description": "Filter findings by estimated severity.", "schema": { "$ref": "#/components/schemas/SiteFindingSeverity" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteFinding" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}": { "get": { "operationId": "getSiteFindingById", "summary": "Get a site finding by ID", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteFinding" } } } } } }, "patch": { "operationId": "updateSiteFindingById", "summary": "Update a site finding", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "canceled" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteFinding" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/change-requests": { "get": { "operationId": "listChangeRequestsForSiteFinding", "summary": "List change requests linked to a site finding", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "200": { "description": "List of change requests linked to the site finding", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequest" } } } } ] } } } } } }, "post": { "operationId": "triggerChangeRequestsForSiteFinding", "summary": "Process a site finding into change requests", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "202": { "description": "Site finding processing has been started" } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/pages": { "get": { "operationId": "listPagesForSiteFinding", "summary": "List pages linked to a site finding", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "200": { "description": "List of pages linked to the site finding", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteFindingPage" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/questions": { "get": { "operationId": "listQuestionsForSiteFinding", "summary": "List questions linked to a site finding", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "200": { "description": "List of questions linked to the site finding", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestion" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/findings/{siteFindingId}/records": { "get": { "operationId": "listRecordsForSiteFinding", "summary": "List records linked to a site finding", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteFindingId" } ], "responses": { "200": { "description": "List of records linked to the site finding", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContextRecord" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/context-connections": { "get": { "operationId": "listSiteContextConnections", "summary": "List all context connections", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContextConnection" } } } } ] } } } } } }, "post": { "operationId": "createSiteContextConnection", "summary": "Create a context connection", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ContextConnectorSetup" }, { "type": "object", "properties": { "usageSettings": { "$ref": "#/components/schemas/ContextUsageSettings" } } } ] } } } }, "responses": { "201": { "description": "Created connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextConnection" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}": { "get": { "operationId": "getSiteContextConnectionById", "summary": "Get a context connection", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteContextConnectionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextConnection" } } } } } }, "patch": { "operationId": "updateSiteContextConnectionById", "summary": "Update a context connection", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteContextConnectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContextConnectorSetup" }, { "type": "object", "properties": { "usageSettings": { "$ref": "#/components/schemas/ContextUsageSettings" }, "label": { "$ref": "#/components/schemas/ContextConnectionLabel" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextConnection" } } } } } }, "delete": { "operationId": "deleteSiteContextConnectionById", "summary": "Delete a context connection", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteContextConnectionId" } ], "responses": { "204": { "description": "Context connection did not exist" }, "205": { "description": "Context connection deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/context-connections/{siteContextConnectionId}/sync": { "post": { "operationId": "syncSiteContextConnection", "summary": "Trigger a sync for a context connection", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteContextConnectionId" } ], "responses": { "204": { "description": "Sync started" }, "400": { "description": "Connection was synced less than an hour ago or invalid connector", "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/topics": { "get": { "operationId": "listSiteTopics", "summary": "List all topics", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "from", "in": "query", "description": "Filter stats to answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter stats to answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteTopic" } } } } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}": { "get": { "operationId": "getSiteTopicById", "summary": "Get a topic", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteTopicId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteTopic" } } } } } }, "patch": { "operationId": "updateSiteTopicById", "summary": "Update a topic", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteTopicId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usageSettings": { "$ref": "#/components/schemas/SiteTopicUsageSettings" } }, "required": [ "usageSettings" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteTopic" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/topics/{siteTopicId}/findings": { "delete": { "operationId": "deleteSiteTopicFindings", "summary": "Delete all findings for a topic", "tags": [ "site-context" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteTopicId" } ], "responses": { "204": { "description": "Topic had no findings or did not exist" }, "205": { "description": "Topic findings deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/questions": { "get": { "operationId": "listSiteQuestions", "summary": "List all questions in a site", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "from", "in": "query", "description": "Filter stats to answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter stats to answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "type", "in": "query", "description": "Filter questions by question type.", "schema": { "$ref": "#/components/schemas/SiteQuestionType" } }, { "name": "relevance", "in": "query", "description": "Filter questions by question relevance.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" } } }, { "name": "answered", "in": "query", "description": "Filter questions by answer resolution.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" } } }, { "name": "topic", "in": "query", "description": "Filter questions by associated site topic IDs.", "schema": { "type": "array", "items": { "type": "string" } } }, { "$ref": "#/components/parameters/listOrder" }, { "name": "sort", "in": "query", "description": "Sort questions by latest ask activity, answered rate, or positive feedback rate. If omitted, ordering stays on canonical question creation date to preserve current behavior.", "schema": { "type": "string", "enum": [ "askedAt", "stats.answered", "stats.feedback", "stats.answers" ] } }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestion" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/questions/{siteQuestionId}": { "get": { "operationId": "getSiteQuestionById", "summary": "Get a site question by ID", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteQuestionId" }, { "name": "from", "in": "query", "description": "Filter stats to answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter stats to answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "relevance", "in": "query", "description": "Filter stats by question relevance.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" } } }, { "name": "answered", "in": "query", "description": "Filter stats by answer resolution.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteQuestion" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/questions/{siteQuestionId}/sources": { "get": { "operationId": "listSiteQuestionSources", "summary": "List sources for a question", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteQuestionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "from", "in": "query", "description": "Filter sources to answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter sources to answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "relevance", "in": "query", "description": "Filter answer sources by question relevance.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" } } }, { "name": "answered", "in": "query", "description": "Filter answer sources by answer resolution.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerSource" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/question-stats": { "get": { "operationId": "getSiteQuestionStats", "summary": "Get question stats for a site", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "from", "in": "query", "description": "Filter stats to answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter stats to answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "topic", "in": "query", "description": "Filter stats by associated site topic IDs.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "relevance", "in": "query", "description": "Filter stats by question relevance.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" } } }, { "name": "answered", "in": "query", "description": "Filter stats by answer resolution.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteQuestionStats" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/answers": { "get": { "operationId": "listSiteQuestionAnswers", "summary": "List all answers for a site", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "name": "question", "in": "query", "description": "Filter answers to a specific site question ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Filter answers created at or after this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "to", "in": "query", "description": "Filter answers created at or before this timestamp.", "schema": { "$ref": "#/components/schemas/Timestamp" } }, { "name": "language", "in": "query", "description": "Filter answers by ISO language code.", "schema": { "type": "string" } }, { "name": "answered", "in": "query", "description": "Filter answers by answered resolution.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" } } }, { "name": "helpfulness", "in": "query", "description": "Filter answers by answered helpfulness.", "schema": { "$ref": "#/components/schemas/SiteQuestionAnswerHelpfulness" } }, { "name": "relevance", "in": "query", "description": "Filter answers by question relevance.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" } } }, { "name": "question.type", "in": "query", "description": "Filter answers by question type.", "schema": { "$ref": "#/components/schemas/SiteQuestionType" } }, { "name": "topic", "in": "query", "description": "Filter answers by associated site topic ID.", "schema": { "type": "string" } }, { "name": "thread", "in": "query", "description": "Filter answers by thread root answer ID. Includes the root answer itself.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswer" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}": { "get": { "operationId": "getSiteQuestionAnswerById", "summary": "Get a site answer by ID", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteQuestionAnswerId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteQuestionAnswerWithResponse" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}/thread": { "get": { "operationId": "getSiteQuestionAnswerThreadById", "summary": "Get a site answer thread by answer ID", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteQuestionAnswerId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerWithResponse" } } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/answers/{siteQuestionAnswerId}/sources": { "get": { "operationId": "listSiteQuestionAnswerSources", "summary": "List the sources for an answer", "tags": [ "site-questions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteQuestionAnswerId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteQuestionAnswerSource" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}": { "patch": { "operationId": "updateSiteSpaceById", "summary": "Update a site space", "tags": [ "site-spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "$ref": "#/components/schemas/SiteSpacePath" }, "condition": { "description": "Conditional expression used to evaluate whether the site space should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.", "oneOf": [ { "$ref": "#/components/schemas/Expression" }, { "type": "null" } ] }, "spaceId": { "type": "string", "description": "The content that this site space points to. If not set, the space will remain unchanged." }, "hidden": { "type": "boolean", "description": "Whether the site space is hidden. If true, the site space will not be shown in the site's navigation. If not set, the hidden state will remain unchanged. If set to false, the site space will be shown in site navigation." }, "draft": { "type": "boolean", "description": "Whether the site space should be kept in draft mode. Setting it to false makes the site space live." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSpace" } } } } } }, "delete": { "operationId": "deleteSiteSpaceById", "summary": "Delete a site space", "tags": [ "site-spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" } ], "responses": { "204": { "description": "Site space did not exist" }, "205": { "description": "Site space has been deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization": { "get": { "operationId": "getSiteSpaceCustomizationById", "summary": "Get a site space customization settings", "tags": [ "site-customization" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" }, { "$ref": "#/components/parameters/siteCustomizationUnmasked" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCustomizationSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "patch": { "operationId": "overrideSiteSpaceCustomizationById", "summary": "Override a site space customization settings", "tags": [ "site-customization" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "The settings that overrides the site customization settings.", "type": "object", "properties": { "title": { "description": "Title to use for the published site variant. If not defined, the title will not be changed. If set to null, the title will be unset and will fallback to the content title.", "oneOf": [ { "$ref": "#/components/schemas/SiteTitle" }, { "type": "null" } ] }, "localizedTitle": { "description": "Localized titles for the site variant, keyed by locale. If not defined, the localized title will not be changed. If set to null, all localized titles will be removed.", "oneOf": [ { "$ref": "#/components/schemas/LocalizedString128" }, { "type": "null" } ] }, "styling": { "type": "object", "properties": { "theme": { "description": "The site theme. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationTheme" }, { "type": "null" } ] }, "primaryColor": { "description": "The primary color used for links and UI text. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "infoColor": { "description": "Used for informational messages and neutral alerts. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "successColor": { "description": "Used for showing positive actions or achievements. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "warningColor": { "description": "Used for showing important information or non-critical warnings. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "dangerColor": { "description": "Used for destructive actions or raising attention to critical information. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "tint": { "description": "The tint will color the site’s UI beyond links and buttons, such as header, sidebar and background. By default, the tint colour is the same as your Primary colour, but you can set a custom one too.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationTint" }, { "type": "null" } ] }, "corners": { "description": "The style of the corners to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationCorners" }, { "type": "null" } ] }, "depth": { "description": "The depth of elements on the site. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationDepth" }, { "type": "null" } ] }, "links": { "description": "The style for links to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationLinksStyle" }, { "type": "null" } ] }, "icons": { "description": "The icons style to use for the content. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationIconsStyle" }, { "type": "null" } ] }, "sidebar": { "description": "Various styles for the sidebar. Each can be Set to null to reset the override.", "type": "object", "properties": { "background": { "oneOf": [ { "$ref": "#/components/schemas/CustomizationSidebarBackgroundStyle" }, { "type": "null" } ] }, "list": { "oneOf": [ { "$ref": "#/components/schemas/CustomizationSidebarListStyle" }, { "type": "null" } ] } } }, "search": { "description": "Styling for the search button at the top of the site.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationSearchStyle" }, { "type": "null" } ] }, "background": { "description": "The style of background to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationBackground" }, { "type": "null" } ] }, "codeTheme": { "description": "The code theme to use. Set to null to reset the override.", "type": "object", "properties": { "default": { "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedCodeTheme" }, { "type": "null" } ] }, "openapi": { "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedCodeTheme" }, { "type": "null" } ] } } } } }, "internationalization": { "type": "object", "deprecated": true, "properties": { "locale": { "description": "The locale to use for the non-custom elements of the UI. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationLocale" }, { "type": "null" } ] } }, "required": [ "locale" ] }, "favicon": { "description": "The favicon to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationFavicon" }, { "type": "null" } ] }, "announcement": { "$ref": "#/components/schemas/CustomizationAnnouncement" }, "header": { "type": "object", "properties": { "preset": { "description": "The theme preset to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationHeaderPreset" }, { "type": "null" } ] }, "logo": { "description": "The header logo to use. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedURL" }, { "type": "null" } ] }, "primaryLink": { "description": "The destination to open when visitors click the site title/logo in the header. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/ContentRef" }, { "type": "null" } ] }, "backgroundColor": { "description": "The background color used in the header. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "linkColor": { "description": "The color used by the links in the header. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedColor" }, { "type": "null" } ] }, "links": { "type": [ "array", "null" ], "description": "The links that are displayed in the header. Set to null to reset the override.", "items": { "$ref": "#/components/schemas/CustomizationHeaderItem" } } } }, "footer": { "type": "object", "properties": { "logo": { "description": "The logo displayed in the footer. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationThemedURL" }, { "type": "null" } ] }, "groups": { "type": [ "array", "null" ], "description": "The links groups that are displayed in the footer. Set to null to reset the override.", "items": { "$ref": "#/components/schemas/CustomizationFooterGroup" } }, "copyright": { "type": [ "string", "null" ], "description": "The copyright text that is displayed in the footer. Set to null to reset the override.", "maxLength": 300 } } }, "themes": { "type": "object", "properties": { "default": { "description": "The theme mode default value. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/CustomizationDefaultThemeMode" }, { "type": "null" } ] }, "toggeable": { "description": "Should the reader be able to switch between dark and light mode. Set to null to reset the override.", "type": [ "boolean", "null" ] } } }, "pdf": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "If true, PDF export is enabled for the published site. Set to null to reset the override." } }, "required": [ "enabled" ] }, "feedback": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "If true, feedback gathering is enabled. Set to null to reset the override." } }, "required": [ "enabled" ] }, "git": { "type": "object", "properties": { "showEditLink": { "type": [ "boolean", "null" ], "description": "Whether the published site should show a link to edit the content on the git provider set up in the Git Sync. Set to null to reset the override." } }, "required": [ "showEditLink" ] }, "externalLinks": { "type": "object", "properties": { "target": { "description": "How external links should open. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/SiteExternalLinksTarget" }, { "type": "null" } ] } }, "required": [ "target" ] }, "pagination": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether the pagination navigation should be displayed on pages. Set to null to reset the override." } }, "required": [ "enabled" ] }, "trademark": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ], "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible. Set to null to reset the override." } }, "required": [ "enabled" ] }, "privacyPolicy": { "type": "object", "properties": { "url": { "description": "The custom link to the privacy policy. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "null" } ] } } }, "socialPreview": { "type": "object", "properties": { "url": { "description": "The URL for the social preview image. Set to null to reset the override.", "oneOf": [ { "$ref": "#/components/schemas/URL" }, { "type": "null" } ] } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCustomizationSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "delete": { "operationId": "deleteSiteSpaceCustomizationById", "summary": "Delete a site space customization settings", "tags": [ "site-customization" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" } ], "responses": { "204": { "description": "Customization settings did not exist" }, "205": { "description": "Site space customization removed" }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/move": { "post": { "operationId": "moveSiteSectionGroup", "deprecated": true, "summary": "Move a site section group to a new position. (Deprecated) use sortSiteStructure instead.", "tags": [ "site-section-groups" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionGroupId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "description": "The position where to move the site section group. When not provided the site section group is moved at the end of the site.", "$ref": "#/components/schemas/SiteSectionGroupMovePosition" } } } } } }, "responses": { "200": { "description": "Site section group moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSectionGroup" } } } }, "400": { "description": "Invalid move site section group position provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching site section group found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move": { "post": { "operationId": "moveSiteSection", "deprecated": true, "summary": "Move a site section to a new position. (Deprecated) use sortSiteStructure instead.", "tags": [ "site-sections" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSectionId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "description": "The position where to move the site section. When not provided the site section is moved at the end of the site.", "$ref": "#/components/schemas/SiteSectionMovePosition" } } } } } }, "responses": { "200": { "description": "Site section moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSection" } } } }, "400": { "description": "Invalid move site section position provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching Site section found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move": { "post": { "operationId": "moveSiteSpace", "deprecated": true, "summary": "Move a site space to a new position. (Deprecated) use sortSiteStructure instead.", "tags": [ "site-spaces" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteSpaceId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "description": "The position where to move the site space. When not provided the site space is moved at the end of the site.", "$ref": "#/components/schemas/SiteSpaceMovePosition" } } } } } }, "responses": { "200": { "description": "Site space moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSpace" } } } }, "400": { "description": "Invalid move site space position provided", "$ref": "#/components/responses/BadRequestError" }, "404": { "description": "No matching Site space found", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions": { "post": { "operationId": "inviteToSite", "summary": "Invite a user or a team to a site", "tags": [ "site-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "204": { "description": "OK" }, "404": { "description": "No team or user with the provided Id", "$ref": "#/components/responses/NotFoundError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteSiteUsersAndTeams" } } } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions/aggregate": { "get": { "operationId": "listPermissionsAggregateInSite", "summary": "List all sites users permissions", "tags": [ "site-users" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of users who can access the site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserSitePermission" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions/users": { "get": { "operationId": "listUserPermissionsInSite", "summary": "List site user permissions", "tags": [ "site-users" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of users who have been added to a site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserSitePermissionOverride" } } } } ] } } } }, "404": { "description": "No site was found with the given Id", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions/users/{userId}": { "patch": { "operationId": "updateUserPermissionInSite", "summary": "Update site user permissions", "tags": [ "site-users" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRole" } } } } } }, "responses": { "204": { "description": "User permission was updated" }, "404": { "description": "No user found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeUserFromSite", "summary": "Remove a site user", "tags": [ "site-users" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "The user was not found in the site" }, "205": { "description": "The user has been removed from the site" } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions/teams": { "get": { "operationId": "listTeamPermissionsInSite", "summary": "List an org team's permission in a site", "tags": [ "site-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Listing of teams who have been added to a site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamSitePermissionOverride" } } } } ] } } } }, "404": { "description": "No site was found with the given Id", "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/permissions/teams/{teamId}": { "patch": { "operationId": "updateTeamPermissionInSite", "summary": "Update an org team's permission in a site", "tags": [ "site-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/MemberRole" } } } } } }, "responses": { "204": { "description": "Team permission was updated" }, "404": { "description": "No team found with the given ID", "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeTeamFromSite", "summary": "Remove an org team from a site", "tags": [ "site-permissions" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/teamId" } ], "responses": { "204": { "description": "The team was not found in the site" }, "205": { "description": "The team has been removed from the site" } } } }, "/orgs/{organizationId}/sites/{siteId}/ai/response": { "post": { "operationId": "streamAIResponseInSite", "summary": "Generate an AI response in a site", "description": "Generate an AI response in a conversation.\n", "tags": [ "site-ai" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "previousResponseId": { "type": "string", "description": "The ID of the previous response to continue from" }, "input": { "type": "array", "description": "The messages to send to the AI agent.", "items": { "$ref": "#/components/schemas/AIMessageInput" } }, "model": { "$ref": "#/components/schemas/AIModel" }, "tools": { "type": "array", "description": "Custom tools to provide to the AI agent.", "items": { "$ref": "#/components/schemas/AIToolDefinition" } }, "toolCall": { "$ref": "#/components/schemas/AIToolCallResult" }, "session": { "$ref": "#/components/schemas/SiteInsightsSession" }, "channel": { "type": "object", "description": "The channel from which the question was asked, if applicable.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/SiteCoreChannelType" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/AIStreamResponse" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/agent-settings": { "get": { "operationId": "getSiteAgentSettingsById", "summary": "Get site agent settings", "tags": [ "site-agent-settings" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAgentSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } }, "put": { "operationId": "updateSiteAgentSettingsById", "summary": "Update site agent settings", "tags": [ "site-agent-settings" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAgentSettingsInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteAgentSettings" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/orgs/{organizationId}/sites/{siteId}/insights/events": { "post": { "operationId": "trackEventsInSiteById", "summary": "Track site events", "tags": [ "site-insights" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "204": { "description": "Events have been tracked." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/SiteInsightsEvent" } } }, "required": [ "events" ] } } } } } }, "/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate": { "post": { "operationId": "aggregateSiteEvents", "summary": "Query site events", "security": [ { "user": [] } ], "tags": [ "site-insights" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteInsightsQueryEventsAggregation" } } } }, "responses": { "200": { "description": "Aggregated events in the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteInsightsQueryEventsAggregationResult" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments": { "get": { "operationId": "listSiteVisitorSegments", "summary": "List a site visitor segments", "tags": [ "site-insights" ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { "description": "List of visitor segments in the site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteInsightsVisitorSegment" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/ads": { "post": { "operationId": "updateSiteAdsById", "summary": "Update a site ads settings", "tags": [ "site-ads" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in-review", "disabled" ] }, "topic": { "$ref": "#/components/schemas/SiteAdsTopic" } } } } } }, "responses": { "204": { "description": "OK" } } } }, "/orgs/{organizationId}/sites/{siteId}/redirects": { "post": { "operationId": "createSiteRedirect", "summary": "Create a site redirect", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/SiteRedirectSourcePath" }, "captureWildcard": { "type": "boolean", "default": false, "description": "Capture and append the wildcard-matched suffix to the destination URL." }, "draft": { "type": "boolean", "default": false, "description": "Whether the redirect is draft and not live." }, "destination": { "$ref": "#/components/schemas/SiteRedirectInputDestination" } }, "required": [ "source", "destination" ] } } } }, "responses": { "201": { "description": "The redirect was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteRedirect" } } } } } }, "put": { "operationId": "bulkUpsertSiteRedirects", "summary": "Create or update site redirects in bulk", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirects": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "oneOf": [ { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/SiteRedirectSourcePath" }, "intent": { "type": "string", "enum": [ "publish" ], "description": "Publish a draft redirect to live and remove the draft redirect.\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 site redirects", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "name": "search", "in": "query", "description": "Search for a redirect by path", "schema": { "type": "string" } }, { "name": "draft", "in": "query", "description": "Filter redirects by draft mode.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The list of redirects for the site.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteRedirect" } } } } ] } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}": { "patch": { "operationId": "updateSiteRedirectById", "summary": "Update a site redirect", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteRedirectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/SiteRedirectSourcePath" }, "captureWildcard": { "type": "boolean", "description": "Capture and append the wildcard-matched suffix to the destination URL." }, "draft": { "type": "boolean", "description": "When true, it can be used to promote a draft redirect to live." }, "destination": { "$ref": "#/components/schemas/SiteRedirectDestination" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteRedirect" } } } } } }, "delete": { "operationId": "deleteSiteRedirectById", "summary": "Delete a site redirect", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteRedirectId" } ], "responses": { "204": { "description": "Site redirect did not exist" }, "205": { "description": "Site redirect deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/redirect": { "get": { "operationId": "getSiteRedirectBySource", "summary": "Get a site redirect by its source", "tags": [ "site-redirects" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteShareKey" }, { "name": "source", "in": "query", "required": true, "description": "The source path of the redirect.", "schema": { "$ref": "#/components/schemas/SiteRedirectSourcePath" } } ], "responses": { "200": { "description": "The redirect was resolved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect": { "$ref": "#/components/schemas/SiteRedirect" }, "target": { "type": "string", "description": "URL of the destination of the redirect." } }, "required": [ "redirect", "target" ] } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/orgs/{organizationId}/sites/{siteId}/mcp-servers": { "get": { "operationId": "listSiteMcpServers", "summary": "List all MCP servers for a site", "tags": [ "site-mcp-servers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteMcpServer" } } } } ] } } } } } }, "post": { "operationId": "createSiteMcpServer", "summary": "Create a new MCP server", "tags": [ "site-mcp-servers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/SiteMcpServerName" }, "url": { "$ref": "#/components/schemas/URL" }, "headers": { "$ref": "#/components/schemas/SiteMcpServerHeaders" }, "condition": { "description": "Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If set to null, the condition will be removed.", "oneOf": [ { "$ref": "#/components/schemas/Expression" }, { "type": "null" } ] } }, "required": [ "name", "url", "headers" ] } } } }, "responses": { "201": { "description": "MCP server created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMcpServer" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/mcp-servers/{siteMcpServerId}": { "get": { "operationId": "getSiteMcpServerById", "summary": "Get a site MCP server", "tags": [ "site-mcp-servers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteMcpServerId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMcpServer" } } } } } }, "patch": { "operationId": "updateSiteMcpServerById", "summary": "Update a site MCP server", "tags": [ "site-mcp-servers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteMcpServerId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/SiteMcpServerName" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "headers": { "$ref": "#/components/schemas/SiteMcpServerHeaders" }, "condition": { "description": "Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.", "oneOf": [ { "$ref": "#/components/schemas/Expression" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteMcpServer" } } } } } }, "delete": { "operationId": "deleteSiteMcpServerById", "summary": "Delete a site MCP server", "tags": [ "site-mcp-servers" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteMcpServerId" } ], "responses": { "204": { "description": "MCP server did not exist" }, "205": { "description": "MCP server deleted" } } } }, "/orgs/{organizationId}/sites/{siteId}/channels": { "get": { "operationId": "listSiteChannels", "summary": "List all site channels for a site", "tags": [ "site-channels" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SiteChannel" } } } } ] } } } } } }, "post": { "operationId": "createSiteChannel", "summary": "Create a site channel", "tags": [ "site-channels" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteChannelSetup" }, { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/SiteChannelRole" } } } ] } } } }, "responses": { "201": { "description": "Site channel created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteChannel" } } } } } } }, "/orgs/{organizationId}/sites/{siteId}/channels/{siteChannelId}": { "get": { "operationId": "getSiteChannelById", "summary": "Get a site channel", "tags": [ "site-channels" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteChannelId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteChannel" } } } } } }, "patch": { "operationId": "updateSiteChannelById", "summary": "Update a site channel", "tags": [ "site-channels" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteChannelId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SiteChannelSetup" }, { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/SiteChannelRole" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteChannel" } } } } } }, "delete": { "operationId": "deleteSiteChannelById", "summary": "Delete a site channel", "tags": [ "site-channels" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/siteChannelId" } ], "responses": { "204": { "description": "Site channel did not exist" }, "205": { "description": "Site channel deleted" } } } }, "/subdomains/{subdomain}": { "get": { "operationId": "getSubdomain", "summary": "Get a subdomain", "tags": [ "subdomains" ], "security": [ { "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/subdomain" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subdomain" } } } } } } }, "/custom-hostnames/{hostname}": { "get": { "operationId": "getCustomHostname", "summary": "Get a custom hostname", "tags": [ "custom-hostnames" ], "security": [ { "user-internal-or-staff": [] } ], "parameters": [ { "$ref": "#/components/parameters/hostname" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomHostname" } } } } } }, "patch": { "operationId": "dnsRevalidateCustomHostname", "summary": "Revalidate a custom hostname DNS", "description": "Revalidate DNS records and status.", "tags": [ "custom-hostnames" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/hostname" } ], "responses": { "204": { "description": "DNS validation has been retriggered" }, "400": { "description": "The current custom hostname is inactive and cannot be revalidated", "$ref": "#/components/responses/ConflictError" }, "409": { "description": "The current custom hostname status does not allow DNS revalidation", "$ref": "#/components/responses/ConflictError" } } }, "delete": { "operationId": "removeCustomHostname", "summary": "Remove a custom hostname", "description": "The custom hostname will continue to point to the content or organization unless it is used for another one.", "tags": [ "custom-hostnames" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/hostname" } ], "responses": { "204": { "description": "Custom hostname did not exist" }, "205": { "description": "Custom hostname has been removed" } } } }, "/email-domains/{emailDomain}/orgs": { "get": { "operationId": "getOrganizationsForEmailDomain", "summary": "Get all organizations by email domain", "tags": [ "organizations" ], "security": [ { "user-internal": [] } ], "parameters": [ { "$ref": "#/components/parameters/emailDomain" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } }, "required": [ "organizations" ] } } } } } } }, "/ads/sites": { "get": { "operationId": "adsListSites", "summary": "List all the sites with ads configured", "tags": [ "site-ads" ], "parameters": [ { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" }, { "$ref": "#/components/parameters/xGitBookPartnerKey" }, { "name": "status", "in": "query", "description": "Filter sites by their ads review status", "required": false, "schema": { "type": "string", "default": "in-review", "enum": [ "in-review", "live", "rejected" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "id", "url", "email", "topic" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "email": { "type": "string" }, "topic": { "$ref": "#/components/schemas/SiteAdsTopic" } } }, { "oneOf": [ { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "in-review" ] } } }, { "type": "object", "required": [ "status", "zoneId" ], "properties": { "status": { "type": "string", "enum": [ "live" ] }, "zoneId": { "type": "string", "description": "The ad network zone ID" } } }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "rejected" ] }, "reason": { "type": "string", "description": "Reason for the rejection" } } } ] } ] } } } } ] } } } } } } }, "/ads/sites/{siteId}": { "patch": { "operationId": "adsUpdateSite", "summary": "Update the Ads configuration for a site", "tags": [ "site-ads" ], "parameters": [ { "$ref": "#/components/parameters/siteId" }, { "$ref": "#/components/parameters/xGitBookPartnerKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "status", "zoneId", "reportingId" ], "properties": { "status": { "type": "string", "enum": [ "live" ] }, "zoneId": { "type": "string", "description": "ID of the zone" }, "reportingId": { "type": "string", "description": "ID to fetch reporting data" } } }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "rejected" ] }, "reason": { "type": "string", "description": "Reason for the rejection", "maxLength": 512 } } }, { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending" ] } } } ] } } } }, "responses": { "204": { "description": "OK" } } } }, "/urls/content": { "get": { "operationId": "getContentByUrl", "summary": "Resolve a URL to a content (space, collection, page)", "tags": [ "urls" ], "security": [ { "user": [] } ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "URL to resolve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "URL resolved to a collection", "properties": { "collection": { "$ref": "#/components/schemas/Collection" } }, "required": [ "collection" ] }, { "type": "object", "description": "URL resolved to the content of a space", "properties": { "space": { "$ref": "#/components/schemas/Space" }, "changeRequest": { "$ref": "#/components/schemas/ChangeRequest" }, "page": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocument" }, { "$ref": "#/components/schemas/RevisionPageGroup" } ] } }, "required": [ "space" ] } ] } } } } } } }, "/urls/embed": { "get": { "operationId": "getEmbedByUrl", "summary": "Resolve a URL to an embed", "tags": [ "urls" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "URL to resolve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Embed" } } } } } } }, "/urls/published": { "get": { "operationId": "getPublishedContentByUrl", "summary": "Resolve a URL of a published content.", "deprecated": true, "tags": [ "urls" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "URL to resolve", "schema": { "$ref": "#/components/schemas/URL" } }, { "name": "visitorAuthToken", "in": "query", "required": false, "description": "JWT token generated for a authenticated access session", "schema": { "type": "string" } }, { "name": "redirectOnError", "in": "query", "required": false, "description": "When true redirects the user to the authentication/fallback URL if the access token is invalid", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedSiteContentLookup" } } } }, "404": { "description": "No content found for the URL.", "$ref": "#/components/responses/NotFoundError" } } }, "post": { "operationId": "resolvePublishedContentByUrl", "summary": "Resolve a URL of a published content.", "tags": [ "urls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "URL to resolve", "$ref": "#/components/schemas/URL" }, "redirectOnError": { "type": "boolean", "description": "When true redirects the user to the authentication/fallback URL if the access token is invalid", "default": false }, "visitor": { "$ref": "#/components/schemas/SiteVisitorPayload" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedSiteContentLookup" } } } }, "404": { "description": "No content found for the URL.", "$ref": "#/components/responses/NotFoundError" } } } }, "/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" }, "user-internal-or-staff": { "type": "http", "scheme": "bearer" }, "integration": { "type": "http", "scheme": "bearer" }, "integration-installation": { "type": "http", "scheme": "bearer" } }, "parameters": { "listPage": { "name": "page", "in": "query", "description": "Identifier of the page results to fetch.", "schema": { "type": "string" } }, "listLimit": { "name": "limit", "in": "query", "description": "The number of results per page", "schema": { "type": "number", "minimum": 0, "maximum": 1000 } }, "tokenId": { "name": "tokenId", "in": "path", "required": true, "description": "The id of the API token", "schema": { "type": "string" } }, "userId": { "name": "userId", "in": "path", "required": true, "description": "The unique ID of the User", "schema": { "type": "string" } }, "spaceId": { "name": "spaceId", "in": "path", "required": true, "description": "The unique id of the space", "schema": { "$ref": "#/components/schemas/EntityId" } }, "siteShareKey": { "name": "shareKey", "in": "query", "description": "For sites published via share-links, the share key is useful to resolve published URLs.", "schema": { "type": "string" } }, "teamId": { "name": "teamId", "in": "path", "required": true, "description": "The unique ID of the Team", "schema": { "$ref": "#/components/schemas/EntityId" } }, "revisionMetadata": { "name": "metadata", "in": "query", "description": "If `false` is passed, \"git\" mutable metadata will not returned. Passing `false` can optimize performances of the lookup.", "schema": { "type": "boolean", "default": true } }, "revisionComputed": { "name": "computed", "in": "query", "description": "If `false` is passed, content will not be computed", "schema": { "type": "boolean", "default": true } }, "fileId": { "name": "fileId", "in": "path", "required": true, "description": "The unique id of the file", "schema": { "$ref": "#/components/schemas/EntityId" } }, "pageId": { "name": "pageId", "in": "path", "required": true, "description": "The unique id of the page", "schema": { "$ref": "#/components/schemas/EntityId" } }, "documentFormat": { "name": "format", "in": "query", "description": "Output format for the content.", "schema": { "type": "string", "enum": [ "document", "markdown" ] } }, "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" } }, "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" } }, "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" } }, "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" }, "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" } }, "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" } }, "required": [ "view", "records", "definition" ] }, "fragments": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentFragment" } } }, "required": [ "object", "type", "data", "isVoid", "fragments" ] }, "DocumentBlockListItem": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "list-item" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockTable" } ] } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": { "checked": { "type": "boolean" } } } }, "required": [ "object", "type", "nodes" ] }, "DocumentBlockListOrdered": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "list-ordered" ] }, "key": { "type": "string" }, "data": { "type": "object", "properties": { "start": { "type": "number", "description": "An integer to start counting from for the list items." } } }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlockListItem" } ] } }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "data", "nodes" ] }, "DocumentBlockListUnordered": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "list-unordered" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlockListItem" } ] } }, "data": { "type": "object", "additionalProperties": false }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "nodes" ] }, "DocumentBlockListTasks": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "list-tasks" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlockListItem" } ] } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "object", "type", "nodes" ] }, "DocumentBlockDivider": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "divider" ] }, "key": { "type": "string" }, "isVoid": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "object", "type", "isVoid", "data" ] }, "DocumentBlocksTopLevels": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockExpandable" }, { "$ref": "#/components/schemas/DocumentBlockTabs" }, { "$ref": "#/components/schemas/DocumentBlockTable" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPI" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPIOperation" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPISchemas" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPIWebhook" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" }, { "$ref": "#/components/schemas/DocumentBlockReusableContent" }, { "$ref": "#/components/schemas/DocumentBlockStepper" }, { "$ref": "#/components/schemas/DocumentBlockIf" }, { "$ref": "#/components/schemas/DocumentBlockColumns" }, { "$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 ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "DocumentBlockExpandable": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "expandable" ] }, "key": { "type": "string" }, "isVoid": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "defaultExpanded": { "type": "boolean" } }, "additionalProperties": false }, "fragments": { "type": "array", "items": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/DocumentFragment" }, { "type": "object", "properties": { "fragment": { "type": "string", "enum": [ "expandable-title" ] }, "type": { "type": "string", "enum": [ "expandable-title" ] }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlockParagraph" }, "minItems": 1, "maxItems": 1 } }, "required": [ "nodes", "fragment", "type" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/DocumentFragment" }, { "type": "object", "properties": { "fragment": { "type": "string", "enum": [ "expandable-body" ] }, "type": { "type": "string", "enum": [ "expandable-body" ] }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockTable" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockReusableContent" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" } ] }, "minItems": 1 } }, "required": [ "nodes", "fragment", "type" ] } ] } ] } }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] } }, "required": [ "object", "type", "isVoid", "fragments", "data" ] }, "DocumentBlockContentRef": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "content-ref" ] }, "key": { "type": "string" }, "data": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRef" } }, "required": [ "ref" ] }, "isVoid": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "DocumentBlockTabsItem": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "tabs-item" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" } ] } }, "data": { "type": "object", "properties": { "title": { "type": "string" } } }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "nodes", "data" ] }, "DocumentBlockTabs": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "tabs" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlockTabsItem" } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": { "fullWidth": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "object", "type", "nodes" ] }, "OpenAPIOperationPointer": { "type": "object", "description": "Pointer to an operation in the OpenAPI spec.", "properties": { "path": { "type": "string", "description": "Path of the operation in the OpenAPI spec." }, "method": { "type": "string", "description": "HTTP method of the operation in the OpenAPI spec." } }, "required": [ "path", "method" ] }, "DocumentBlockOpenAPI": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "swagger" ] }, "key": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OpenAPIOperationPointer" }, { "type": "object", "properties": { "ref": { "oneOf": [ { "$ref": "#/components/schemas/ContentRefFile" }, { "$ref": "#/components/schemas/ContentRefURL" } ] }, "expanded": { "type": "boolean", "description": "If true, the block is opened by default." }, "fullWidth": { "type": "boolean" } }, "required": [ "ref" ] } ] }, "isVoid": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "DocumentBlockOpenAPIOperation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "openapi-operation" ] }, "key": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OpenAPIOperationPointer" }, { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRefOpenAPI" } }, "required": [ "ref" ] } ] }, "isVoid": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "OpenAPISchemasPointer": { "type": "object", "description": "Pointer to schemas in the OpenAPI spec.", "properties": { "grouped": { "type": "boolean", "description": "Whether the schemas are grouped or not.", "default": true }, "schemas": { "type": "array", "description": "List of schemas name from the OpenAPI spec.", "items": { "type": "string" } }, "title": { "type": "string", "description": "Custom title for the schemas block. When not provided, defaults to \"The object\"." } }, "required": [ "schemas" ] }, "DocumentBlockOpenAPISchemas": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "openapi-schemas" ] }, "key": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OpenAPISchemasPointer" }, { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRefOpenAPI" } }, "required": [ "ref" ] } ], "required": [ "ref" ] }, "isVoid": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "OpenAPIWebhookPointer": { "type": "object", "description": "Pointer to a webhook in the OpenAPI spec.", "properties": { "name": { "type": "string", "description": "Name of the webhook in the OpenAPI spec." }, "method": { "type": "string", "description": "HTTP method of the webhook in the OpenAPI spec." } }, "required": [ "name", "method" ] }, "DocumentBlockOpenAPIWebhook": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "openapi-webhook" ] }, "key": { "type": "string" }, "data": { "allOf": [ { "$ref": "#/components/schemas/OpenAPIWebhookPointer" }, { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRefOpenAPI" } }, "required": [ "ref" ] } ] }, "isVoid": { "type": "boolean", "enum": [ true ] }, "meta": { "type": "object", "properties": { "id": { "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, "required": [ "id" ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "DocumentBlockStepperStep": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "stepper-step" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" }, { "$ref": "#/components/schemas/DocumentBlockExpandable" } ] } }, "data": { "type": "object", "properties": { "icon": { "type": "string" } } }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "nodes", "data" ] }, "DocumentBlockStepper": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "stepper" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlockStepperStep" } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "object", "type", "nodes" ] }, "DocumentBlockColumn": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "column" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockTable" }, { "$ref": "#/components/schemas/DocumentBlockExpandable" }, { "$ref": "#/components/schemas/DocumentBlockStepper" } ] } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": { "width": { "$ref": "#/components/schemas/Length" }, "verticalAlignment": { "$ref": "#/components/schemas/VerticalAlignment" } }, "additionalProperties": false } }, "required": [ "object", "type", "nodes", "data" ] }, "DocumentBlockColumns": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "columns" ] }, "key": { "type": "string" }, "data": { "type": "object", "properties": { "fullWidth": { "type": "boolean" } } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlockColumn" } }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "data", "nodes", "isVoid" ] }, "DocumentBlockUpdate": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "update" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlocksEssentials" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" }, { "$ref": "#/components/schemas/DocumentBlockTabs" }, { "$ref": "#/components/schemas/DocumentBlockExpandable" } ] } }, "data": { "type": "object", "properties": { "date": { "$ref": "#/components/schemas/Timestamp" }, "tags": { "type": "array", "description": "Array of tags. Each tag is id'ed by its slug.", "items": { "$ref": "#/components/schemas/ContentRefTag" } } }, "required": [ "date" ] }, "isVoid": { "type": "boolean", "enum": [ false ] } }, "required": [ "object", "type", "nodes", "data" ] }, "DocumentBlockUpdates": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "block" ] }, "type": { "type": "string", "enum": [ "updates" ] }, "key": { "type": "string" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlockUpdate" } }, "isVoid": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "numeric", "full", "short" ], "default": "full" } }, "required": [ "format" ], "additionalProperties": false } }, "required": [ "object", "type", "nodes", "data" ] }, "DocumentBlock": { "oneOf": [ { "$ref": "#/components/schemas/DocumentBlockParagraph" }, { "$ref": "#/components/schemas/DocumentBlockHeading" }, { "$ref": "#/components/schemas/DocumentBlockListOrdered" }, { "$ref": "#/components/schemas/DocumentBlockListUnordered" }, { "$ref": "#/components/schemas/DocumentBlockListTasks" }, { "$ref": "#/components/schemas/DocumentBlockListItem" }, { "$ref": "#/components/schemas/DocumentBlockDivider" }, { "$ref": "#/components/schemas/DocumentBlockQuote" }, { "$ref": "#/components/schemas/DocumentBlockHint" }, { "$ref": "#/components/schemas/DocumentBlockIf" }, { "$ref": "#/components/schemas/DocumentBlockImages" }, { "$ref": "#/components/schemas/DocumentBlockImage" }, { "$ref": "#/components/schemas/DocumentBlockFile" }, { "$ref": "#/components/schemas/DocumentBlockDrawing" }, { "$ref": "#/components/schemas/DocumentBlockEmbed" }, { "$ref": "#/components/schemas/DocumentBlockCode" }, { "$ref": "#/components/schemas/DocumentBlockCodeLine" }, { "$ref": "#/components/schemas/DocumentBlockMath" }, { "$ref": "#/components/schemas/DocumentBlockExpandable" }, { "$ref": "#/components/schemas/DocumentBlockTabs" }, { "$ref": "#/components/schemas/DocumentBlockTabsItem" }, { "$ref": "#/components/schemas/DocumentBlockTable" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPI" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPIOperation" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPISchemas" }, { "$ref": "#/components/schemas/DocumentBlockOpenAPIWebhook" }, { "$ref": "#/components/schemas/DocumentBlockContentRef" }, { "$ref": "#/components/schemas/DocumentBlockIntegration" }, { "$ref": "#/components/schemas/DocumentBlockReusableContent" }, { "$ref": "#/components/schemas/DocumentBlockStepper" }, { "$ref": "#/components/schemas/DocumentBlockStepperStep" }, { "$ref": "#/components/schemas/DocumentBlockColumns" }, { "$ref": "#/components/schemas/DocumentBlockColumn" }, { "$ref": "#/components/schemas/DocumentBlockUpdates" }, { "$ref": "#/components/schemas/DocumentBlockUpdate" } ] }, "DocumentInlineMention": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "inline" ] }, "type": { "type": "string", "enum": [ "mention" ] }, "key": { "type": "string" }, "data": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRef" } }, "required": [ "ref" ] }, "isVoid": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "DocumentAction": { "type": "object", "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "search" ] }, "query": { "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "ask" ] }, "query": { "type": "string" } }, "required": [ "action" ], "additionalProperties": false } ] }, "DocumentInlineButton": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "inline" ] }, "type": { "type": "string", "enum": [ "button" ] }, "key": { "type": "string" }, "data": { "allOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "primary", "secondary" ] }, "icon": { "$ref": "#/components/schemas/Icon" } }, "required": [ "label", "kind" ] }, { "oneOf": [ { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRef" } }, "required": [ "ref" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/DocumentAction" } }, "required": [ "action" ], "additionalProperties": false } ] } ] }, "isVoid": { "type": "boolean", "enum": [ true ] } }, "required": [ "object", "type", "data", "isVoid" ] }, "JSONDocument": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "document" ] }, "data": { "type": "object", "properties": { "schemaVersion": { "description": "The schema version of the document. If undefined, the document is considered to be of the latest schema version.", "type": "integer" } }, "additionalProperties": true }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentBlocksTopLevels" } }, "meta": { "type": "object", "properties": { "token": { "description": "A content token that can be used to fetch the content referenced in this document from the API.", "type": "string" } } } }, "required": [ "object", "data", "nodes" ] }, "Document": { "oneOf": [ { "$ref": "#/components/schemas/MarkdownDocument", "title": "Markdown" }, { "type": "object", "title": "JSON Document", "properties": { "document": { "$ref": "#/components/schemas/JSONDocument" } }, "required": [ "document" ] }, { "type": "object", "title": "Empty", "properties": {}, "additionalProperties": false } ] }, "RevisionPageSlug": { "type": "string", "description": "Page's slug in its direct parent", "minLength": 0, "maxLength": 100 }, "RevisionPageDocument": { "allOf": [ { "$ref": "#/components/schemas/RevisionPageBase" }, { "$ref": "#/components/schemas/Document" }, { "type": "object", "properties": { "kind": { "type": "string", "deprecated": true, "enum": [ "sheet" ] }, "type": { "type": "string", "enum": [ "document" ] }, "urls": { "required": [ "app" ], "properties": { "app": { "description": "Location of the page in the app", "$ref": "#/components/schemas/URL" } } }, "slug": { "$ref": "#/components/schemas/RevisionPageSlug" }, "path": { "description": "Complete path to access the page in the revision.", "type": "string" }, "description": { "type": "string" }, "pages": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocument" }, { "$ref": "#/components/schemas/RevisionPageLink" }, { "$ref": "#/components/schemas/RevisionPageComputed" } ] } }, "git": { "$ref": "#/components/schemas/GitSyncBlob" }, "layout": { "$ref": "#/components/schemas/RevisionPageLayoutOptions" }, "cover": { "$ref": "#/components/schemas/RevisionPageDocumentCover" }, "variables": { "$ref": "#/components/schemas/Variables" }, "hidden": { "type": "boolean", "description": "If true, the page is not displayed in the navigation, while still being accessible.", "default": false }, "noIndex": { "type": "boolean", "description": "If true, the page is not indexable in the search and ask features.", "default": false }, "noRobotsIndex": { "type": "boolean", "description": "If true, the page is not indexable by search engine robots.", "default": false }, "metaLinks": { "description": "Meta links associated with the page.", "$ref": "#/components/schemas/RevisionPageMetaLinks" }, "tags": { "type": "array", "description": "A list of all the tags added to this page", "items": { "$ref": "#/components/schemas/RevisionPageTag" } } }, "required": [ "kind", "type", "urls", "slug", "path", "pages", "layout", "tags" ] }, { "oneOf": [ { "type": "object", "description": "Defined when the page was generated by a computed content.", "properties": { "computed": { "$ref": "#/components/schemas/ComputedContentSourceDocument" }, "computedSeed": { "type": "string", "description": "Seed to use for the generation of IDs." } }, "required": [ "computed", "computedSeed" ] }, { "type": "object", "properties": { "documentId": { "type": "string", "description": "ID of the document with the page body. If undefined, the page is empty." } } } ] } ] }, "RevisionPageLink": { "allOf": [ { "$ref": "#/components/schemas/RevisionPageBase" }, { "type": "object", "properties": { "kind": { "type": "string", "deprecated": true, "enum": [ "link" ] }, "type": { "type": "string", "enum": [ "link" ] }, "target": { "$ref": "#/components/schemas/ContentRef" }, "href": { "type": "string" }, "hidden": { "type": "boolean", "description": "If true, the page is not displayed in the navigation, while still being accessible.", "default": false } }, "required": [ "kind", "type", "target" ] } ] }, "OpenAPISpecVisibility": { "type": "string", "description": "The visibility setting of the OpenAPI spec.\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." } }, "required": [ "models" ] } } } ] }, "TranslationRef": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "translation" ] }, "translation": { "type": "string", "description": "ID of the translation sync" } }, "required": [ "kind", "translation" ] }, "TranslationResult": { "type": "object", "description": "Result of a translation.", "properties": { "space": { "type": "string", "description": "ID of the space containing the result of the translation" }, "revision": { "type": "string", "description": "ID of the revision generated by the translation" } }, "required": [ "space", "revision" ] }, "ComputedContentDependencyTranslation": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/TranslationRef" }, "value": { "oneOf": [ { "$ref": "#/components/schemas/TranslationResult" }, { "type": "null", "description": "Translation has not been run yet" } ] } }, "required": [ "ref", "value" ] }, "ComputedContentSourceRevisionTranslation": { "type": "object", "description": "Parameters for a translation computed content source", "properties": { "type": { "type": "string", "enum": [ "builtin:translation" ] }, "props": { "type": "object", "additionalProperties": false, "properties": {} }, "dependencies": { "type": "object", "required": [ "translation" ], "properties": { "translation": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "ref" ], "properties": { "ref": { "$ref": "#/components/schemas/TranslationRef" } } }, { "$ref": "#/components/schemas/ComputedContentDependencyTranslation" } ] } } } }, "required": [ "type", "props", "dependencies" ] }, "ComputedContentDependency": { "type": "object", "description": "Dependency for a computation, before its resolution.", "additionalProperties": false, "properties": { "ref": { "oneOf": [ { "$ref": "#/components/schemas/ContentRefSpace" }, { "$ref": "#/components/schemas/ContentRefOpenAPI" }, { "$ref": "#/components/schemas/TranslationRef" } ] } }, "required": [ "ref" ] }, "ComputedContentDependencySpace": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRefSpace" }, "value": { "type": [ "object", "null" ], "description": "See `Space` schema component.", "properties": { "object": { "type": "string", "enum": [ "space" ] }, "id": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "object", "id", "revision" ] } }, "required": [ "ref", "value" ] }, "ComputedContentDependencyResolved": { "description": "Dependency for a computation, with its resolved value.", "oneOf": [ { "$ref": "#/components/schemas/ComputedContentDependencySpace" }, { "$ref": "#/components/schemas/ComputedContentDependencyOpenAPI" }, { "$ref": "#/components/schemas/ComputedContentDependencyTranslation" } ] }, "ComputedContentSourceIntegration": { "type": "object", "description": "Parameters for a computed content managed by an integration", "properties": { "type": { "type": "string", "description": "Type of the computed source", "pattern": "^integration:[^:]+:[^:]+$", "x-typescript": "`integration:${string}:${string}`" }, "props": { "description": "Properties to be passed to the computation", "$ref": "#/components/schemas/PlainObject" }, "dependencies": { "type": "object", "description": "Dependencies the computation depends on.\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?" } }, "required": [ "width", "cover", "coverSize", "title", "description", "tableOfContents", "outline", "pagination", "metadata", "tags" ] }, "RevisionPageDocumentCover": { "type": "object", "properties": { "ref": { "description": "Content reference pointing to the source image.", "oneOf": [ { "$ref": "#/components/schemas/ContentRefFile" }, { "$ref": "#/components/schemas/ContentRefURL" } ] }, "refDark": { "description": "Content reference pointing to the source image for dark mode.", "oneOf": [ { "$ref": "#/components/schemas/ContentRefFile" }, { "$ref": "#/components/schemas/ContentRefURL" } ] }, "yPos": { "description": "Vertical position of the cover image.", "type": "number", "default": 0 }, "height": { "description": "Height of the cover image in pixels.", "type": "number", "minimum": 10, "maximum": 700, "default": 240 } }, "required": [ "yPos" ] }, "VariableValue": { "oneOf": [ { "type": "string", "maxLength": 256 }, { "type": "number" }, { "type": "boolean" } ] }, "Variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/VariableValue" } }, "RevisionPageMetaLinkTarget": { "oneOf": [ { "$ref": "#/components/schemas/ContentRefPage" }, { "$ref": "#/components/schemas/ContentRefURL" } ] }, "RevisionPageMetaLinks": { "type": "object", "properties": { "canonical": { "$ref": "#/components/schemas/RevisionPageMetaLinkTarget" }, "alternates": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPageMetaLinkTarget" } } } }, "RevisionPageTag": { "type": "object", "description": "A reference to a tag with optional primary flag for page-level tags.", "properties": { "tag": { "$ref": "#/components/schemas/ContentRefTag" }, "primary": { "type": "boolean", "description": "Whether this is the primary tag for display in table of contents." } }, "required": [ "tag" ] }, "ComputedContentSourceDocumentOpenAPI": { "allOf": [ { "$ref": "#/components/schemas/ComputedContentSourceOpenAPIBase" }, { "type": "object", "description": "Parameters for an OpenAPI computed document", "required": [ "props" ], "properties": { "props": { "oneOf": [ { "type": "object", "required": [ "doc" ], "properties": { "doc": { "type": "string", "enum": [ "models" ] } } }, { "type": "object", "required": [ "doc", "page" ], "properties": { "doc": { "type": "string", "enum": [ "operations", "info" ] }, "page": { "type": "string", "minLength": 1 } } } ] } } } ] }, "ComputedContentSourceDocumentTranslation": { "type": "object", "description": "Parameters for a document translation computed content source", "required": [ "type", "props" ], "properties": { "type": { "type": "string", "enum": [ "builtin:translation" ] }, "props": { "type": "object", "required": [ "space", "document" ], "properties": { "space": { "type": "string" }, "document": { "type": "string" } } } } }, "ComputedContentSourceDocument": { "oneOf": [ { "$ref": "#/components/schemas/ComputedContentSourceDocumentOpenAPI" }, { "$ref": "#/components/schemas/ComputedContentSourceDocumentTranslation" }, { "$ref": "#/components/schemas/ComputedContentSourceIntegration" } ] }, "RevisionPageGroup": { "allOf": [ { "$ref": "#/components/schemas/RevisionPageBase" }, { "type": "object", "properties": { "kind": { "type": "string", "deprecated": true, "enum": [ "group" ] }, "type": { "type": "string", "enum": [ "group" ] }, "slug": { "description": "Page's slug in its direct parent", "type": "string" }, "path": { "description": "Complete path to access the page in the revision.", "type": "string" }, "hidden": { "type": "boolean", "description": "If true, the page is not displayed in the navigation, while still being accessible.", "default": false }, "noIndex": { "type": "boolean", "description": "If true, the page is not indexable in the search and ask features.", "default": false }, "noRobotsIndex": { "type": "boolean", "description": "If true, the page is not indexable by search engine robots.", "default": false }, "pages": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocument" }, { "$ref": "#/components/schemas/RevisionPageLink" }, { "$ref": "#/components/schemas/RevisionPageComputed" } ] } } }, "required": [ "kind", "type", "slug", "path", "pages" ] } ] }, "RevisionPage": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocument" }, { "$ref": "#/components/schemas/RevisionPageGroup" }, { "$ref": "#/components/schemas/RevisionPageLink" }, { "$ref": "#/components/schemas/RevisionPageComputed" } ], "discriminator": { "propertyName": "type" } }, "RevisionFile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "downloadURL": { "type": "string" }, "size": { "type": "number" }, "dimensions": { "type": "object", "description": "For images, it contains the dimensions of it.", "properties": { "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "width", "height" ] }, "git": { "$ref": "#/components/schemas/GitSyncBlob" } }, "required": [ "id", "name", "contentType", "downloadURL", "size" ] }, "RevisionReusableContent": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "git": { "$ref": "#/components/schemas/GitSyncBlob" } }, "required": [ "id", "title" ] }, { "oneOf": [ { "type": "object", "description": "Defined when the reusable content was generated by a computed content.", "properties": { "computed": { "$ref": "#/components/schemas/ComputedContentSourceDocument" }, "computedSeed": { "type": "string", "description": "Seed to use for the generation of IDs." } }, "required": [ "computed", "computedSeed" ] }, { "type": "object", "properties": { "document": { "type": "string", "description": "ID of the document with the content body. If undefined, the reusable content is empty." } } } ] } ] }, "RevisionTag": { "allOf": [ { "type": "object", "description": "A reusable tag that different types of content can be associated to (e.g. pages, update entries)", "properties": { "slug": { "type": "string", "description": "The slug identifier for the tag, immutable after creation." }, "label": { "type": "string", "description": "Display label for the tag. Can be renamed and differ from the slug." }, "color": { "$ref": "#/components/schemas/DocumentTextColor" } }, "required": [ "slug", "label", "color" ] }, { "oneOf": [ { "type": "object", "properties": { "emoji": { "$ref": "#/components/schemas/Emoji" } }, "required": [ "emoji" ] }, { "type": "object", "properties": { "icon": { "$ref": "#/components/schemas/Icon" } } } ] } ] }, "GitSyncCommit": { "type": "object", "properties": { "oid": { "type": "string", "description": "SHA for the commit" }, "message": { "type": "string", "description": "Message describing the purpose of the commit" }, "createdByGitBook": { "type": "boolean", "description": "If true, the Git commit was generated by an export from GitBook" }, "url": { "type": "string", "description": "URL of the commit in the GitSync provider" }, "ref": { "type": "string", "description": "Original name of the ref where the commit originated from" } }, "required": [ "oid", "message", "createdByGitBook" ] }, "RevisionBase": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"revision\"", "enum": [ "revision" ] }, "id": { "description": "Unique identifier for the revision", "type": "string" }, "parents": { "description": "IDs of the parent revisions", "type": "array", "items": { "type": "string" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionPage" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionFile" } }, "reusableContents": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionReusableContent" } }, "tags": { "type": "array", "description": "List of available tags within this revision", "items": { "$ref": "#/components/schemas/RevisionTag" } }, "variables": { "$ref": "#/components/schemas/Variables" }, "createdAt": { "description": "When the revision was created.", "$ref": "#/components/schemas/Timestamp" }, "git": { "description": "Metadata about a potential associated git commit.", "$ref": "#/components/schemas/GitSyncCommit" }, "urls": { "type": "object", "properties": { "app": { "type": "string", "format": "uri", "description": "URL in the application for the revision" }, "published": { "type": "string", "description": "URL of the published version of the revision. Only defined when the space visibility is not \"private.\"", "format": "uri" }, "public": { "type": "string", "description": "URL of the public version of the revision. Only defined when the space visibility is \"public\".", "format": "uri" } }, "required": [ "app" ] } }, "required": [ "object", "id", "parents", "pages", "files", "reusableContents", "tags", "urls", "createdAt" ] }, "RevisionTypeEdits": { "allOf": [ { "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { "type": { "type": "string", "description": "Revision created by editing the content.", "enum": [ "edits" ] } }, "required": [ "type" ] } ] }, "ChangeRequestStatus": { "type": "string", "enum": [ "draft", "open", "archived", "merged" ] }, "ChangeRequestSubject": { "type": "string", "description": "Subject of the change request", "minLength": 0, "maxLength": 100 }, "ChangeRequestLinkTitle": { "type": "string", "description": "Optional title to display for the link.", "maxLength": 128 }, "ChangeRequestLink": { "type": "object", "properties": { "ref": { "$ref": "#/components/schemas/ContentRefURL" }, "title": { "$ref": "#/components/schemas/ChangeRequestLinkTitle" } }, "required": [ "ref" ] }, "ChangeRequestLinks": { "type": "array", "description": "External links associated with the change request.", "items": { "$ref": "#/components/schemas/ChangeRequestLink" }, "maxItems": 10 }, "ChangeRequest": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"change-request\"", "enum": [ "change-request" ] }, "id": { "type": "string", "description": "Unique identifier for the change request" }, "number": { "type": "number", "description": "Incremental identifier of the change request" }, "status": { "$ref": "#/components/schemas/ChangeRequestStatus" }, "subject": { "$ref": "#/components/schemas/ChangeRequestSubject" }, "description": { "$ref": "#/components/schemas/JSONDocument" }, "createdBy": { "$ref": "#/components/schemas/User" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "space": { "type": "string", "description": "ID of the space in which the change request was created." }, "revision": { "type": "string", "description": "ID of the active revision in the change request." }, "revisionInitial": { "type": "string", "description": "ID of the initial revision in the space from which the change request was created." }, "revisionMergedAncestor": { "type": "string", "description": "ID of the latest revision when updating from main space content." }, "revisionMerged": { "type": "string", "description": "When merged, ID of the revision resulting from the merge." }, "comments": { "type": "number", "description": "Count of opened comments on the change request." }, "siteTopic": { "type": "object", "description": "Site context associated with the change request when it was created from a site topic or finding.", "properties": { "site": { "type": "string", "description": "ID of the site associated with the change request." }, "topic": { "type": "string", "description": "ID of the site topic associated with the change request." }, "finding": { "type": "string", "description": "ID of the site finding associated with the change request, when applicable." } }, "required": [ "site", "topic" ] }, "outdated": { "type": "boolean", "description": "If true, the change request is not up-to-date with latest changes in the main content." }, "links": { "$ref": "#/components/schemas/ChangeRequestLinks" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "app": { "type": "string", "description": "URL of the space in the application", "format": "uri" }, "location": { "type": "string", "description": "URL of the user in the API", "format": "uri" } }, "required": [ "app", "location" ] } }, "required": [ "object", "id", "number", "status", "subject", "createdBy", "createdAt", "updatedAt", "space", "revision", "revisionInitial", "comments", "outdated", "urls" ] }, "RevisionTypeMerge": { "allOf": [ { "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { "type": { "type": "string", "description": "Revision created when merging a change request with primary.", "enum": [ "merge" ] }, "mergedFrom": { "$ref": "#/components/schemas/ChangeRequest" } }, "required": [ "type", "mergedFrom" ] } ] }, "RevisionTypeRollback": { "allOf": [ { "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { "type": { "type": "string", "description": "Revision created as a rollback of a previous revision.", "enum": [ "rollback" ] } }, "required": [ "type" ] } ] }, "RevisionTypeUpdate": { "allOf": [ { "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { "type": { "type": "string", "description": "Revision created when updating a change request with changes from primary.", "enum": [ "update" ] } }, "required": [ "type" ] } ] }, "RevisionTypeComputed": { "allOf": [ { "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { "type": { "type": "string", "description": "Virtual revision, computed from a source revision", "enum": [ "computed" ] }, "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" } }, "required": [ "interval", "endDate", "hasPaymentFailed", "canCheckout", "isScheduledToCancel", "pricing", "usageAddons" ] }, "BillingTrialStatus": { "type": "string", "description": "- notapplicable, no trial can be started for this organization. - none, no trial has been started yet. - active, trial is active. - ended, the trial has ended and the user has choosen to stay on the free plan or has upgraded to a paid plan. - expired, the trial has ended but the user hasn't deciced yet what to do.\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" ] } ] } ] }, "PostCommentSchema": { "type": "object", "properties": { "node": { "description": "The node to which the comment is posted, if any.", "type": "string" }, "page": { "description": "The page to which the comment is posted, if any.", "type": "string" }, "body": { "description": "The content of the comment.", "$ref": "#/components/schemas/Document" }, "tableCell": { "$ref": "#/components/schemas/TableCellTarget" } }, "required": [ "body" ] }, "UpdateCommentSchema": { "type": "object", "properties": { "resolved": { "type": "boolean", "description": "Whether the comment is resolved or not." }, "body": { "description": "Content of the comment.", "$ref": "#/components/schemas/Document" }, "addedReactions": { "type": "array", "description": "Reactions to add to the comment.", "items": { "type": "string" } }, "removedReactions": { "type": "array", "description": "Reactions to remove from the comment.", "items": { "type": "string" } } } }, "CommentReply": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"comment-reply\"", "enum": [ "comment-reply" ] }, "id": { "type": "string", "description": "Unique identifier for the reply." }, "postedBy": { "$ref": "#/components/schemas/User" }, "postedAt": { "$ref": "#/components/schemas/Timestamp" }, "editedAt": { "description": "Date when the reply was edited, if it has been edited.", "$ref": "#/components/schemas/Timestamp" }, "reactions": { "$ref": "#/components/schemas/EmojiReactions" }, "body": { "$ref": "#/components/schemas/Document" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "location": { "type": "string", "description": "URL of the comment reply in the API", "format": "uri" } }, "required": [ "location" ] }, "permissions": { "type": "object", "description": "The set of permissions for the comment reply", "properties": { "view": { "type": "boolean", "description": "Can the user view the comment reply." }, "edit": { "type": "boolean", "description": "Can the user edit the comment reply." }, "reply": { "type": "boolean", "description": "Can the user react or reply to the comment reply." }, "delete": { "type": "boolean", "description": "Can the user delete the comment reply." } }, "required": [ "view", "edit", "delete" ] } }, "required": [ "object", "id", "body", "postedBy", "postedAt", "reactions", "urls", "permissions" ] }, "PostCommentReplySchema": { "type": "object", "properties": { "body": { "description": "The content of the comment.", "$ref": "#/components/schemas/Document" } }, "required": [ "body" ] }, "ChangeRequestUserContributor": { "allOf": [ { "$ref": "#/components/schemas/UserContributor" }, { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "edit", "comment" ] } }, "required": [ "actionType" ] } ] }, "RevisionPageType": { "type": "string", "enum": [ "document", "group", "link", "computed" ] }, "ChangedRevisionPage": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/RevisionPageType" }, "title": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "type", "title" ] }, "RevisionSemanticChangePageCreated": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page_created" ] }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "type", "page" ] }, "ChangeAttributeString": { "type": "object", "properties": { "before": { "type": "string" }, "after": { "type": "string" } } }, "ChangeAttributeRevisionPageDocumentCover": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/RevisionPageDocumentCover" }, "after": { "$ref": "#/components/schemas/RevisionPageDocumentCover" } } }, "RevisionPageLayoutPreset": { "type": "string", "description": "The core layout presets for a page.", "enum": [ "docs", "editorial", "landing" ] }, "RevisionPageLayout": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageLayoutPreset" }, { "$ref": "#/components/schemas/RevisionPageLayoutOptions" } ] }, "ChangeAttributeRevisionPageLayout": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/RevisionPageLayout" }, "after": { "$ref": "#/components/schemas/RevisionPageLayout" } } }, "ChangeAttributeVariables": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/Variables" }, "after": { "$ref": "#/components/schemas/Variables" } } }, "RevisionPageDocumentChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "title": { "$ref": "#/components/schemas/ChangeAttributeString" }, "description": { "$ref": "#/components/schemas/ChangeAttributeString" }, "slug": { "$ref": "#/components/schemas/ChangeAttributeString" }, "document": { "$ref": "#/components/schemas/ChangeAttributeString" }, "cover": { "$ref": "#/components/schemas/ChangeAttributeRevisionPageDocumentCover" }, "emoji": { "$ref": "#/components/schemas/ChangeAttributeString" }, "layout": { "$ref": "#/components/schemas/ChangeAttributeRevisionPageLayout" }, "variables": { "$ref": "#/components/schemas/ChangeAttributeVariables" } } }, "RevisionPageGroupChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "title": { "$ref": "#/components/schemas/ChangeAttributeString" }, "emoji": { "$ref": "#/components/schemas/ChangeAttributeString" }, "slug": { "$ref": "#/components/schemas/ChangeAttributeString" } } }, "ChangeAttributeContentReference": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/ContentRef" }, "after": { "$ref": "#/components/schemas/ContentRef" } } }, "RevisionPageLinkChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "title": { "$ref": "#/components/schemas/ChangeAttributeString" }, "emoji": { "$ref": "#/components/schemas/ChangeAttributeString" }, "target": { "$ref": "#/components/schemas/ChangeAttributeContentReference" } } }, "RevisionSemanticChangePageEdited": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page_edited" ] }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" }, "attributes": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocumentChangeAttributes" }, { "$ref": "#/components/schemas/RevisionPageGroupChangeAttributes" }, { "$ref": "#/components/schemas/RevisionPageLinkChangeAttributes" } ] } }, "required": [ "type", "page", "attributes" ] }, "RevisionSemanticChangePageDeleted": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page_deleted" ] }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "type", "page" ] }, "RevisionSemanticChangePageMoved": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page_moved" ] }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" }, "parent": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/ChangedRevisionPage" }, "after": { "$ref": "#/components/schemas/ChangedRevisionPage" } } } }, "required": [ "type", "page", "parent" ] }, "ChangedRevisionFile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "downloadURL": { "type": "string" } }, "required": [ "id", "name", "contentType", "downloadURL" ] }, "RevisionSemanticChangeFileCreated": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_created" ] }, "file": { "$ref": "#/components/schemas/ChangedRevisionFile" } }, "required": [ "type", "file" ] }, "ChangeAttributeNumber": { "type": "object", "properties": { "before": { "type": "number" }, "after": { "type": "number" } } }, "RevisionFileImageDimensions": { "type": "object", "properties": { "height": { "type": "number" }, "width": { "type": "number" } }, "required": [ "height", "width" ] }, "ChangeAttributeRevisionFileImageDimensions": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/RevisionFileImageDimensions" }, "after": { "$ref": "#/components/schemas/RevisionFileImageDimensions" } } }, "RevisionFileChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "name": { "$ref": "#/components/schemas/ChangeAttributeString" }, "downloadURL": { "$ref": "#/components/schemas/ChangeAttributeString" }, "size": { "$ref": "#/components/schemas/ChangeAttributeNumber" }, "contentType": { "$ref": "#/components/schemas/ChangeAttributeString" }, "dimensions": { "$ref": "#/components/schemas/ChangeAttributeRevisionFileImageDimensions" } } }, "RevisionSemanticChangeFileEdited": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_edited" ] }, "file": { "$ref": "#/components/schemas/ChangedRevisionFile" }, "attributes": { "$ref": "#/components/schemas/RevisionFileChangeAttributes" } }, "required": [ "type", "file", "attributes" ] }, "RevisionSemanticChangeFileDeleted": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file_deleted" ] }, "file": { "$ref": "#/components/schemas/ChangedRevisionFile" } }, "required": [ "type", "file" ] }, "ChangeAttributeVariable": { "type": "object", "properties": { "before": { "$ref": "#/components/schemas/VariableValue" }, "after": { "$ref": "#/components/schemas/VariableValue" } } }, "RevisionSemanticChangeVariablesEdited": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variables_edited" ] }, "variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChangeAttributeVariable" } } }, "required": [ "type", "variables" ] }, "ChangedRevisionReusableContent": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "document": { "type": "string" } }, "required": [ "id", "title" ] }, "RevisionSemanticChangeReusableContentCreated": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reusable_content_created" ] }, "reusableContent": { "$ref": "#/components/schemas/ChangedRevisionReusableContent" } }, "required": [ "type", "reusableContent" ] }, "RevisionSemanticChangeReusableContentDeleted": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reusable_content_deleted" ] }, "reusableContent": { "$ref": "#/components/schemas/ChangedRevisionReusableContent" } }, "required": [ "type", "reusableContent" ] }, "RevisionReusableContentChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "title": { "$ref": "#/components/schemas/ChangeAttributeString" }, "document": { "$ref": "#/components/schemas/ChangeAttributeString" } } }, "RevisionSemanticChangeReusableContentEdited": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reusable_content_edited" ] }, "reusableContent": { "$ref": "#/components/schemas/ChangedRevisionReusableContent" }, "attributes": { "$ref": "#/components/schemas/RevisionReusableContentChangeAttributes" } }, "required": [ "type", "reusableContent", "attributes" ] }, "ChangedRevisionTag": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" } }, "required": [ "slug", "label" ] }, "RevisionSemanticChangeTagCreated": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tag_created" ] }, "tag": { "$ref": "#/components/schemas/ChangedRevisionTag" } }, "required": [ "type", "tag" ] }, "RevisionSemanticChangeTagDeleted": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tag_deleted" ] }, "tag": { "$ref": "#/components/schemas/ChangedRevisionTag" } }, "required": [ "type", "tag" ] }, "RevisionTagChangeAttributes": { "type": "object", "minProperties": 1, "properties": { "label": { "$ref": "#/components/schemas/ChangeAttributeString" } } }, "RevisionSemanticChangeTagEdited": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tag_edited" ] }, "tag": { "$ref": "#/components/schemas/ChangedRevisionTag" }, "attributes": { "$ref": "#/components/schemas/RevisionTagChangeAttributes" } }, "required": [ "type", "tag", "attributes" ] }, "RevisionSemanticChange": { "oneOf": [ { "$ref": "#/components/schemas/RevisionSemanticChangePageCreated" }, { "$ref": "#/components/schemas/RevisionSemanticChangePageEdited" }, { "$ref": "#/components/schemas/RevisionSemanticChangePageDeleted" }, { "$ref": "#/components/schemas/RevisionSemanticChangePageMoved" }, { "$ref": "#/components/schemas/RevisionSemanticChangeFileCreated" }, { "$ref": "#/components/schemas/RevisionSemanticChangeFileEdited" }, { "$ref": "#/components/schemas/RevisionSemanticChangeFileDeleted" }, { "$ref": "#/components/schemas/RevisionSemanticChangeVariablesEdited" }, { "$ref": "#/components/schemas/RevisionSemanticChangeReusableContentCreated" }, { "$ref": "#/components/schemas/RevisionSemanticChangeReusableContentDeleted" }, { "$ref": "#/components/schemas/RevisionSemanticChangeReusableContentEdited" }, { "$ref": "#/components/schemas/RevisionSemanticChangeTagCreated" }, { "$ref": "#/components/schemas/RevisionSemanticChangeTagDeleted" }, { "$ref": "#/components/schemas/RevisionSemanticChangeTagEdited" } ] }, "RevisionSemanticChanges": { "type": "object", "properties": { "mergedFrom": { "description": "The change request object that initiated the changes in the case of a merge revision.", "$ref": "#/components/schemas/ChangeRequest" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionSemanticChange" } }, "more": { "type": "number", "description": "How many changes were omitted because above the result limit" } }, "required": [ "changes" ] }, "UpdateCommentReplySchema": { "type": "object", "properties": { "body": { "description": "Content of the comment.", "$ref": "#/components/schemas/Document" }, "addedReactions": { "type": "array", "description": "Reactions to add to the comment.", "items": { "type": "string" } }, "removedReactions": { "type": "array", "description": "Reactions to remove from the comment.", "items": { "type": "string" } } } }, "OrganizationMember": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"member\"", "enum": [ "member" ] }, "id": { "type": "string", "description": "Unique identifier for the user." }, "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "user": { "$ref": "#/components/schemas/User" }, "disabled": { "type": "boolean", "description": "Whatever the membership of this user is disabled and prevent them from accessing content." }, "joinedAt": { "description": "Date at which the user joined the organization.", "$ref": "#/components/schemas/Timestamp" }, "lastSeenAt": { "description": "Date at which the user was last seen active in the organization.", "$ref": "#/components/schemas/Timestamp" }, "sso": { "type": "boolean", "description": "Whether the user can login with SSO." }, "spaces": { "type": "number" }, "teams": { "type": "number" } }, "required": [ "object", "id", "role", "user", "disabled", "joinedAt", "sso", "spaces", "teams" ] }, "IntegrationTitle": { "type": "string", "description": "Title of the integration", "minLength": 2, "maxLength": 30 }, "IntegrationDescription": { "type": "string", "description": "Description of the integration", "maxLength": 100 }, "IntegrationSummary": { "type": "string", "description": "Long form markdown summary of the integration", "maxLength": 2048 }, "IntegrationTarget": { "type": "string", "description": "The target on which the integration can operate and needs to be configured for", "enum": [ "all", "site", "space", "organization" ] }, "IntegrationVisibility": { "type": "string", "enum": [ "public", "private", "unlisted" ] }, "IntegrationScope": { "type": "string", "enum": [ "space:content:read", "space:content:write", "space:metadata:read", "space:metadata:write", "space:git:sync", "page:feedback:read", "site:metadata:read", "site:views:read", "site:script:inject", "site:script:cookies", "site:visitor:auth", "site:adaptive:read", "site:adaptive:write", "conversations:ingest", "openapi:read", "openapi:write" ] }, "IntegrationScopes": { "type": "array", "description": "Permissions that should be granted to the integration", "items": { "$ref": "#/components/schemas/IntegrationScope" } }, "IntegrationCategory": { "type": "string", "enum": [ "analytics", "collaboration", "content", "gitsync", "marketing", "visitor-auth", "other" ] }, "IntegrationCategories": { "type": "array", "description": "Categories for which the integration is listed in the marketplace", "items": { "$ref": "#/components/schemas/IntegrationCategory" } }, "IntegrationBlocks": { "type": "array", "description": "Custom blocks defined by this integration.", "items": { "$ref": "#/components/schemas/IntegrationBlock" } }, "IntegrationConfigurationComponent": { "type": "object", "description": "ContentKit component for configuration", "properties": { "componentId": { "type": "string", "description": "ID of the ContentKit component defined in the integration" } }, "required": [ "componentId" ] }, "IntegrationContentSource": { "type": "object", "description": "Definition of a content source provided by the integration.", "properties": { "id": { "type": "string", "description": "Unique ID in the integration for the source." }, "title": { "type": "string", "description": "Short descriptive title for the source.", "minLength": 2, "maxLength": 40 }, "description": { "type": "string", "description": "Long descriptive text for the source.", "minLength": 0, "maxLength": 150 }, "icon": { "type": "string", "description": "URL of the icon to represent this source." }, "configuration": { "$ref": "#/components/schemas/IntegrationConfigurationComponent" } }, "required": [ "id", "title", "configuration" ] }, "IntegrationPropertyTitle": { "type": "string", "description": "Property title for an integration configuration property", "minLength": 2, "maxLength": 50 }, "IntegrationConfigurationSchema": { "type": "object", "description": "Schema for a configuration", "properties": { "properties": { "type": "object", "additionalProperties": { "allOf": [ { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/IntegrationPropertyTitle" }, "description": { "type": "string", "maxLength": 100 } } }, { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string" ] }, "default": { "type": "string" }, "completion_url": { "description": "If specified, this URL will be called to fetch suggestions for auto-completing the property.", "type": "string" }, "enum": { "type": "array", "description": "If specified, only values from this array are allowed as inputs.", "items": { "type": "string" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "number" ] }, "default": { "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "boolean" ] }, "default": { "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "button" ] }, "callback_url": { "type": "string" }, "button_text": { "type": "string" } }, "required": [ "type", "callback_url", "button_text" ] } ] } ] } }, "required": { "type": "array", "uniqueItems": true, "items": { "type": "string" } } }, "required": [ "properties" ] }, "IntegrationConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/IntegrationConfigurationSchema" }, { "$ref": "#/components/schemas/IntegrationConfigurationComponent" } ] }, "IntegrationConfigurations": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/IntegrationConfiguration" }, "space": { "$ref": "#/components/schemas/IntegrationConfiguration" }, "site": { "$ref": "#/components/schemas/IntegrationConfiguration" } } }, "IntegrationExternalLinks": { "type": "array", "description": "External urls configured by the developer of the integration", "maxItems": 5, "items": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/URL" }, "label": { "type": "string" } }, "required": [ "url", "label" ] } }, "IntegrationContentSecurityPolicy": { "description": "Security policy to validate the content of the integrations scripts and Contentkit. Will be sent as \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" } }, "required": [ "location", "app", "assets", "publicEndpoint" ] }, "permissions": { "type": "object", "description": "The set of permissions for the integration", "properties": { "admin": { "type": "boolean" } }, "required": [ "admin" ] }, "contentSecurityPolicy": { "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" } }, "required": [ "object", "name", "version", "title", "scopes", "categories", "visibility", "target", "verified", "previewImages", "externalLinks", "owner", "permissions", "urls" ] }, "SpaceIntegrationBlocks": { "type": "array", "items": { "type": "object", "required": [ "name", "blocks" ], "properties": { "name": { "type": "string", "description": "Unique named identifier for the integration" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationBlock" } } } } }, "IntegrationSecrets": { "type": "object", "description": "Secrets stored on the integration and passed at runtime.", "properties": {}, "maxProperties": 20, "additionalProperties": { "type": "string" } }, "PublishIntegration": { "type": "object", "properties": { "runtime": { "type": "string", "description": "The runtime version to use for the integration. If not specified, the integration will use the default runtime.", "default": "v1", "enum": [ "v1", "v2" ] }, "icon": { "type": "string", "format": "byte", "description": "Base64 content of the icon" }, "title": { "$ref": "#/components/schemas/IntegrationTitle" }, "description": { "$ref": "#/components/schemas/IntegrationDescription" }, "summary": { "$ref": "#/components/schemas/IntegrationSummary" }, "previewImages": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "byte", "description": "Base64 content of the image" } }, "visibility": { "$ref": "#/components/schemas/IntegrationVisibility" }, "target": { "description": "Allowed installation target for the integration. If not specified, the integration can be installed at `all` targets (org, spaces etc)", "$ref": "#/components/schemas/IntegrationTarget" }, "scopes": { "$ref": "#/components/schemas/IntegrationScopes" }, "categories": { "$ref": "#/components/schemas/IntegrationCategories" }, "blocks": { "$ref": "#/components/schemas/IntegrationBlocks" }, "contentSources": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationContentSource" } }, "externalLinks": { "$ref": "#/components/schemas/IntegrationExternalLinks" }, "configurations": { "$ref": "#/components/schemas/IntegrationConfigurations" }, "script": { "type": "string", "description": "Content of the script to use" }, "organization": { "type": "string", "description": "The ID or subdomain of the organization under which the integration should be published" }, "secrets": { "$ref": "#/components/schemas/IntegrationSecrets" }, "contentSecurityPolicy": { "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" } }, "required": [ "organization", "title", "description", "script", "scopes" ] }, "IntegrationInstallationStatus": { "type": "string", "enum": [ "active", "pending", "paused" ] }, "IntegrationInstallationSpaceSelection": { "type": "string", "description": "Describe whether all spaces have been selected or there's a selection involved", "enum": [ "all", "selected" ] }, "IntegrationInstallationSiteSelection": { "type": "string", "description": "Describe whether all sites have been selected or there's a selection involved", "enum": [ "all", "selected" ] }, "IntegrationInstallationConfiguration": { "type": "object", "description": "Configuration of the integration at the account level", "additionalProperties": true }, "IntegrationInstallationExternalIds": { "type": "array", "description": "External IDs assigned by the integration.", "maxItems": 5, "items": { "type": "string" } }, "OrganizationTarget": { "type": "object", "required": [ "organization" ], "properties": { "organization": { "type": "string" } } }, "IntegrationInstallationTarget": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationTarget" } ] }, "IntegrationNetwork": { "type": "object", "description": "Network configuration for the installation", "properties": { "proxy": { "type": "boolean", "description": "Whether the installation is proxied through the backend" } } }, "IntegrationInstallation": { "type": "object", "description": "Installation of an integration on an account", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "space_selection": { "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" }, "site_selection": { "$ref": "#/components/schemas/IntegrationInstallationSiteSelection" }, "spaces": { "type": "number", "description": "Count of spaces, the installation is managing" }, "configuration": { "$ref": "#/components/schemas/IntegrationInstallationConfiguration" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "location": { "type": "string", "description": "URL of the installation in the API", "format": "uri" }, "app": { "type": "string", "description": "URL of the integration's installation in the application", "format": "uri" }, "publicEndpoint": { "type": "string", "description": "Public HTTP endpoint for the integration's installation", "format": "uri" } }, "required": [ "location", "app", "publicEndpoint" ] }, "externalIds": { "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, "target": { "$ref": "#/components/schemas/IntegrationInstallationTarget", "description": "Target of the integration installation" }, "network": { "$ref": "#/components/schemas/IntegrationNetwork", "description": "Network configuration for the installation" } }, "required": [ "id", "status", "space_selection", "site_selection", "spaces", "configuration", "urls", "externalIds", "target", "createdAt", "updatedAt" ] }, "BaseEvent": { "description": "Common properties for all events.", "type": "object", "properties": { "eventId": { "description": "Unique identifier for the event.", "type": "string" }, "type": { "description": "Type of the event.", "type": "string" } }, "required": [ "eventId", "type" ] }, "InstallationEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseEvent" }, { "type": "object", "description": "Common properties for all events related to an installation", "properties": { "installationId": { "type": "string", "description": "ID of the integration installation" } }, "required": [ "installationId" ] } ] }, "InstallationSetupEvent": { "allOf": [ { "$ref": "#/components/schemas/InstallationEvent" }, { "type": "object", "description": "Event received when integration has been installed or updated.", "properties": { "type": { "type": "string", "enum": [ "installation_setup" ] }, "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "previous": { "type": "object", "description": "The state of the installation at the account level before it was updated.", "properties": { "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "configuration": { "type": "object", "description": "The previous configuration of the installation at the account level." } }, "required": [ "status" ] } }, "required": [ "type", "status" ] } ] }, "InstallationDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/InstallationEvent" }, { "type": "object", "description": "Event received when integration has been uninstalled from an organization.", "properties": { "type": { "type": "string", "enum": [ "installation_deleted" ] }, "previous": { "type": "object", "description": "The state of the installation before it was deleted.", "properties": { "configuration": { "type": "object", "description": "The previous configuration of the installation." } } } }, "required": [ "type", "previous" ] } ] }, "SpaceEvent": { "allOf": [ { "$ref": "#/components/schemas/InstallationEvent" }, { "type": "object", "description": "Common properties for all events related to a specific space.", "properties": { "spaceId": { "type": "string", "description": "ID of the space" } }, "required": [ "spaceId" ] } ] }, "SpaceInstallationSetupEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event received when integration has been installed or updated on a space.", "properties": { "type": { "type": "string", "enum": [ "space_installation_setup" ] }, "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "previous": { "type": "object", "description": "The state of the Space installation before it was updated.", "properties": { "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "configuration": { "type": "object", "description": "The previous configuration of the Space installation." } }, "required": [ "status" ] } }, "required": [ "type", "status" ] } ] }, "SpaceInstallationDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event received when integration has been uninstalled from a space.", "properties": { "type": { "type": "string", "enum": [ "space_installation_deleted" ] }, "previous": { "type": "object", "description": "The state of the Space installation before it was deleted.", "properties": { "configuration": { "type": "object", "description": "The previous configuration of the Space installation." } } } }, "required": [ "type", "previous" ] } ] }, "SiteEvent": { "allOf": [ { "$ref": "#/components/schemas/InstallationEvent" }, { "type": "object", "description": "Common properties for all events related to a specific site.", "properties": { "siteId": { "type": "string", "description": "ID of the site" } }, "required": [ "siteId" ] } ] }, "SiteInstallationSetupEvent": { "allOf": [ { "$ref": "#/components/schemas/SiteEvent" }, { "type": "object", "description": "Event received when integration has been installed or updated on a site.", "properties": { "type": { "type": "string", "enum": [ "site_installation_setup" ] }, "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "previous": { "type": "object", "description": "The state of the site installation before it was updated.", "properties": { "status": { "$ref": "#/components/schemas/IntegrationInstallationStatus" }, "configuration": { "type": "object", "description": "The previous configuration of the site installation." } }, "required": [ "status" ] } }, "required": [ "type", "status" ] } ] }, "SiteInstallationDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/SiteEvent" }, { "type": "object", "description": "Event received when integration has been uninstalled from a site.", "properties": { "type": { "type": "string", "enum": [ "site_installation_deleted" ] }, "previous": { "type": "object", "description": "The state of the site installation before it was deleted.", "properties": { "configuration": { "type": "object", "description": "The previous configuration of the site installation." } } } }, "required": [ "type", "previous" ] } ] }, "EventVisitor": { "type": "object", "description": "Analytics info on the GitBook's content visitor.", "properties": { "anonymousId": { "type": "string", "description": "GitBook's unique identifier of the visitor." }, "cookies": { "type": "object", "description": "The visitors cookies.", "additionalProperties": { "type": "string" } }, "userAgent": { "type": "string", "description": "User-agent of the visitor." }, "ip": { "type": "string", "description": "IP address of the visitor." }, "language": { "type": "string", "description": "Language of the visitor." } }, "required": [ "anonymousId", "cookies", "userAgent", "ip" ] }, "SiteViewEvent": { "allOf": [ { "$ref": "#/components/schemas/SiteEvent" }, { "type": "object", "description": "Event received when a page has been visited on a site.", "properties": { "type": { "type": "string", "enum": [ "site_view" ] }, "spaceId": { "type": "string", "description": "Unique identifier of the visited space in the site.", "deprecated": true }, "siteSpaceId": { "description": "The site-space that was viewed", "type": "string" }, "pageId": { "type": "string", "description": "Unique identifier of the visited page." }, "visitor": { "$ref": "#/components/schemas/EventVisitor" }, "url": { "type": "string", "description": "The GitBook content's URL visited (including URL params)." }, "referrer": { "type": "string", "description": "The URL of referrer that linked to the page." } }, "required": [ "type", "visitor", "url", "referrer" ] } ] }, "SpaceContentUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event when the primary content of a space has been updated.", "properties": { "type": { "type": "string", "enum": [ "space_content_updated" ] }, "revisionId": { "type": "string", "description": "Unique identifier of the new content revision" } }, "required": [ "type", "revisionId" ] } ] }, "SpaceGitSyncCompletedEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event when a GitSync operation has been completed.", "properties": { "type": { "type": "string", "enum": [ "space_gitsync_completed" ] }, "state": { "type": "string", "enum": [ "success", "failure" ] }, "revisionId": { "type": "string", "description": "Unique identifier of the new content revision" }, "commitId": { "type": "string", "description": "Unique identifier for the commit (sha)" } }, "required": [ "type", "state", "revisionId", "commitId" ] } ] }, "SpaceGitSyncStartedEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event when a GitSync operation has been started.", "properties": { "type": { "type": "string", "enum": [ "space_gitsync_started" ] }, "revisionId": { "type": "string", "description": "Unique identifier of the new content revision" }, "commitId": { "type": "string", "description": "Unique identifier for the commit (sha)" } }, "required": [ "type", "revisionId", "commitId" ] } ] }, "SpaceVisibilityUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Event when the visibility of the space has been changed.", "properties": { "type": { "type": "string", "enum": [ "space_visibility_updated" ] }, "previousVisibility": { "$ref": "#/components/schemas/ContentVisibility" }, "visibility": { "$ref": "#/components/schemas/ContentVisibility" } }, "required": [ "type", "previousVisibility", "visibility" ] } ] }, "TaskEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseEvent" }, { "type": "object", "description": "Event representing a background task trigger for an integration.", "properties": { "type": { "type": "string", "enum": [ "task" ] }, "task": { "type": "object", "description": "Payload associated with the integration task." } }, "required": [ "type", "task" ] } ] }, "FetchRequest": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "post", "get", "put", "delete" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "method", "url", "headers" ] }, "FetchEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseEvent" }, { "type": "object", "description": "Event representing an incoming HTTP request.", "properties": { "spaceId": { "type": "string", "description": "The space ID, if requests are specific to a single space" }, "siteId": { "type": "string", "description": "The site ID, if requests are specific to a single site" }, "installationId": { "type": "string", "description": "The installation ID, if requests are specific to a single installation" }, "auth": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user's ID." } }, "required": [ "userId" ] }, "type": { "type": "string", "enum": [ "fetch" ] }, "request": { "$ref": "#/components/schemas/FetchRequest" } }, "required": [ "type", "request" ] } ] }, "FetchPublishedScriptEvent": { "allOf": [ { "$ref": "#/components/schemas/SiteEvent" }, { "type": "object", "description": "Common properties for all events related to fetching a published script from an installation", "properties": { "type": { "type": "string", "enum": [ "fetch_published_script" ] } }, "required": [ "type" ] } ] }, "FetchVisitorAuthenticationEvent": { "allOf": [ { "$ref": "#/components/schemas/SiteEvent" }, { "type": "object", "description": "Common properties for all events related to authenticated access from an installation", "properties": { "type": { "type": "string", "enum": [ "fetch_visitor_authentication" ] }, "location": { "type": "string" } }, "required": [ "type" ] } ] }, "ContentKitContextBase": { "type": "object", "description": "Common properties for ContentKit context.", "properties": { "theme": { "type": "string", "enum": [ "dark", "light" ] } }, "required": [ "theme" ] }, "ContentKitContextConfigurationAccount": { "allOf": [ { "$ref": "#/components/schemas/ContentKitContextBase" }, { "type": "object", "description": "Context while rendering in an account installation's configuration.", "properties": { "type": { "type": "string", "enum": [ "configuration_account" ] }, "organizationId": { "type": "string", "description": "ID of the organization the account installation configuration is in." } }, "required": [ "type", "organizationId" ] } ] }, "ContentKitContextConfigurationSpace": { "allOf": [ { "$ref": "#/components/schemas/ContentKitContextBase" }, { "type": "object", "description": "Context while rendering in a space-installation's configuration.", "properties": { "type": { "type": "string", "enum": [ "configuration_space" ] }, "spaceId": { "type": "string", "description": "ID of the space the space-installation configuration is in." } }, "required": [ "type", "spaceId" ] } ] }, "ContentKitContextConfigurationSite": { "allOf": [ { "$ref": "#/components/schemas/ContentKitContextBase" }, { "type": "object", "description": "Context while rendering in a site-installation's configuration.", "properties": { "type": { "type": "string", "enum": [ "configuration_site" ] }, "siteId": { "type": "string", "description": "ID of the site the site-installation configuration is in." } }, "required": [ "type", "siteId" ] } ] }, "ContentKitContextConfigurationContentSource": { "allOf": [ { "$ref": "#/components/schemas/ContentKitContextBase" }, { "type": "object", "description": "Context while rendering the configuration flow of a content source.", "properties": { "type": { "type": "string", "enum": [ "configuration_contentsource" ] }, "organizationId": { "type": "string", "description": "ID of the organization the content source installation configuration is in." }, "spaceId": { "type": "string", "description": "Optional ID of the space the content source installation configuration is in." } }, "required": [ "type", "organizationId" ] } ] }, "ContentKitContextDocument": { "allOf": [ { "$ref": "#/components/schemas/ContentKitContextBase" }, { "type": "object", "description": "Context while rendering in a document.", "properties": { "type": { "type": "string", "enum": [ "document" ] }, "spaceId": { "type": "string", "description": "ID of the space content the document is in." }, "editable": { "type": "boolean" } }, "required": [ "type", "spaceId", "editable" ] } ] }, "ContentKitContext": { "description": "Object representing the context in which a ContentKit component is rendered.", "oneOf": [ { "$ref": "#/components/schemas/ContentKitContextConfigurationAccount" }, { "$ref": "#/components/schemas/ContentKitContextConfigurationSpace" }, { "$ref": "#/components/schemas/ContentKitContextConfigurationSite" }, { "$ref": "#/components/schemas/ContentKitContextConfigurationContentSource" }, { "$ref": "#/components/schemas/ContentKitContextDocument" } ] }, "UIRenderEvent": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "$ref": "#/components/schemas/SiteEvent" }, { "$ref": "#/components/schemas/InstallationEvent" } ] }, { "type": "object", "description": "Event generated when rendering a UI", "properties": { "auth": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user's ID." } }, "required": [ "userId" ] }, "type": { "type": "string", "enum": [ "ui_render" ] }, "componentId": { "type": "string" }, "props": { "description": "Properties to render the UI.", "type": "object" }, "state": { "description": "State of the UI.", "type": "object" }, "context": { "$ref": "#/components/schemas/ContentKitContext" }, "action": { "type": "object" } }, "required": [ "type", "componentId", "props", "context" ] } ] }, "ContentComputeEvent": { "allOf": [ { "$ref": "#/components/schemas/SpaceEvent" }, { "type": "object", "description": "Generic event when computing the content of a space", "properties": { "sourceId": { "type": "string" }, "props": { "description": "Properties passed to the rendering.", "$ref": "#/components/schemas/PlainObject" }, "dependencies": { "description": "Dependencies of the computation.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComputedContentDependencyResolved" } } }, "required": [ "sourceId", "props", "dependencies" ] } ] }, "ContentComputeDocumentEvent": { "allOf": [ { "$ref": "#/components/schemas/ContentComputeEvent" }, { "type": "object", "description": "Event generated when computing the document of a pages.\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" } }, "required": [ "location", "publicEndpoint" ] } }, "required": [ "integration", "installation", "status", "configuration", "externalIds", "urls" ] }, "IntegrationSpaceInstallation": { "allOf": [ { "$ref": "#/components/schemas/IntegrationContentInstallationBase" }, { "type": "object", "properties": { "space": { "description": "The space the integration is installed on. Using the string value is deprecated in favor of space.id", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Space" } ] } }, "required": [ "space" ] } ] }, "SiteType": { "type": "string", "description": "The type of the site", "enum": [ "basic", "premium", "ultimate", "sponsored", "legacy-basic", "legacy-premium" ] }, "SiteTitle": { "type": "string", "description": "Title of the site", "minLength": 2, "maxLength": 128 }, "CustomizationThemedURL": { "type": "object", "properties": { "light": { "$ref": "#/components/schemas/URL" }, "dark": { "$ref": "#/components/schemas/URL" } }, "required": [ "light", "dark" ] }, "CustomizationFavicon": { "oneOf": [ { "type": "object", "properties": { "icon": { "$ref": "#/components/schemas/CustomizationThemedURL" } }, "required": [ "icon" ] }, { "type": "object", "properties": { "emoji": { "$ref": "#/components/schemas/Emoji" } }, "required": [ "emoji" ] }, { "type": "object", "properties": {}, "additionalProperties": false } ] }, "SiteHostname": { "type": "string", "description": "Custom hostname for the site, for e.g. docs.mycompany.com", "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?[.]){2,}[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$", "maxLength": 512 }, "SiteBasename": { "type": "string", "description": "Basename for the site. For e.g. api", "minLength": 1, "maxLength": 100 }, "SiteProxyOrigin": { "type": "string", "description": "Proxy URL for the site, for e.g. company.com/docs or www.company.com/developer/docs etc.", "pattern": "^([\\w-]+\\.)*[\\w-]+\\.[a-zA-Z]{2,}(\\/[\\w-]+)+$", "maxLength": 512 }, "SiteProxy": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/SiteProxyOrigin" }, "target": { "type": "string", "description": "The target URL to which the requests at the origin URL should be proxied to." } }, "required": [ "origin", "target" ] }, "SiteVisibility": { "type": "string", "description": "The visibility setting of the site determines the audience of the site.\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-connections", "sites-channels", "sites-embed", "sites-api-playground", "sites-basic-customization", "sites-custom-domain", "sites-custom-fonts", "sites-custom-subdirectory", "sites-full-text-search", "sites-multivariant-site", "sites-no-custom-domain", "sites-page-feedback", "sites-page-traffic-insights", "sites-pdf-export", "sites-preview-deployments", "sites-public-visibility", "sites-redirects", "sites-search-insights", "sites-sections", "sites-seo", "sites-share-links", "sites-unlisted-visibility", "sites-user-contribution", "sites-visitor-authentication", "sites-visitors" ] }, "SiteCustomizationFeature": { "type": "string", "description": "A list of all premium customizations.", "enum": [ "header-logo", "header-primary-link", "theme-preset", "premium-fonts", "custom-icons", "footer-logo", "footer-links", "footer-copyright", "semantic-colors" ] }, "SiteFeature": { "type": "object", "description": "A site feature and the plan it is available on.", "properties": { "id": { "$ref": "#/components/schemas/SiteFeatureKey" }, "plan": { "$ref": "#/components/schemas/SiteType" }, "frozen": { "description": "A frozen feature is still enabled but cannot be changed or modified.", "type": "boolean" }, "customizations": { "description": "A list of the actual advanced customizations used (only applicable for sites-advanced-customization)", "type": "array", "items": { "$ref": "#/components/schemas/SiteCustomizationFeature" } } }, "required": [ "id", "plan", "frozen" ] }, "Site": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site" ] }, "id": { "type": "string", "description": "Unique identifier of the site" }, "type": { "$ref": "#/components/schemas/SiteType" }, "appliedType": { "$ref": "#/components/schemas/SiteType", "description": "The currently applied type of the site. For example, frozen sites will have this set to Basic." }, "title": { "$ref": "#/components/schemas/SiteTitle" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/CustomizationFavicon" }, { "type": "null" } ] }, "hostname": { "$ref": "#/components/schemas/SiteHostname" }, "basename": { "$ref": "#/components/schemas/SiteBasename" }, "proxy": { "$ref": "#/components/schemas/SiteProxy" }, "visibility": { "$ref": "#/components/schemas/SiteVisibility" }, "permissionsModel": { "$ref": "#/components/schemas/SitePermissionsModel" }, "defaultLevel": { "$ref": "#/components/schemas/DefaultLevel" }, "published": { "type": "boolean", "description": "Whether the site is live or not. If true, the site is accessible to the audience defined by the visibility setting." }, "siteSpaces": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "adaptiveContent": { "$ref": "#/components/schemas/SiteAdaptiveContent" }, "ads": { "$ref": "#/components/schemas/SiteAds" }, "features": { "description": "A list of all premium features enabled on this site. For each feature we list the plan they belong to and whether the feature is frozen. A frozen feature is still enabled but cannot be changed or modified.\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" } }, "required": [ "app", "location", "preview" ] } }, "required": [ "object", "id", "type", "appliedType", "title", "visibility", "permissionsModel", "defaultLevel", "published", "createdAt", "siteSpaces", "features", "urls" ] }, "IntegrationSiteInstallation": { "allOf": [ { "$ref": "#/components/schemas/IntegrationContentInstallationBase" }, { "type": "object", "properties": { "site": { "description": "The site the integration is installed on. Using the string value is deprecated in favor of site.id", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Site" } ] } }, "required": [ "site" ] } ] }, "ContentKitIcon": { "type": "string", "enum": [ "close", "edit", "github", "gitlab", "maximize", "email", "settings", "search", "delete", "star", "warning", "link", "link-external", "eye", "eye-off", "lock", "check", "check-circle" ] }, "ContentKitConfirm": { "type": "object", "description": "A confirm object that defines an optional confirmation dialog after the input is clicked.", "properties": { "title": { "type": "string", "description": "A text value that defines the dialog's title.", "maxLength": 100 }, "text": { "type": "string", "description": "A text value that defines the explanatory text that appears in the confirm dialog.", "maxLength": 300 }, "confirm": { "type": "string", "description": "A text value to define the text of the button that confirms the action.", "maxLength": 30 }, "style": { "type": "string", "enum": [ "primary", "danger" ] } }, "required": [ "title", "text", "confirm" ] }, "ContentKitButton": { "type": "object", "description": "Pressable button triggering an action.", "properties": { "type": { "type": "string", "enum": [ "button" ] }, "style": { "type": "string", "enum": [ "primary", "secondary", "danger" ] }, "onPress": { "$ref": "#/components/schemas/ContentKitAction" }, "icon": { "$ref": "#/components/schemas/ContentKitIcon" }, "trailingIcon": { "$ref": "#/components/schemas/ContentKitIcon" }, "label": { "type": "string" }, "tooltip": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/ContentKitConfirm" }, "disabled": { "type": "boolean" } }, "required": [ "type", "onPress" ] }, "ContentKitTextInput": { "type": "object", "description": "Text input to prompt the user.", "properties": { "type": { "type": "string", "enum": [ "textinput" ] }, "disabled": { "type": "boolean" }, "state": { "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "initialValue": { "description": "Text value to initialize the input with.", "type": "string" }, "placeholder": { "description": "Text that appears in the form control when it has no value set", "type": "string" }, "multiline": { "type": "boolean" }, "inputType": { "type": "string", "enum": [ "text", "password", "email" ], "default": "text" } }, "required": [ "type", "state" ] }, "ContentKitDescendantElement": { "description": "Any element that can be used as children.", "oneOf": [ { "$ref": "#/components/schemas/ContentKitButton" }, { "$ref": "#/components/schemas/ContentKitTextInput" }, { "$ref": "#/components/schemas/ContentKitHStack" }, { "$ref": "#/components/schemas/ContentKitVStack" }, { "$ref": "#/components/schemas/ContentKitBox" }, { "$ref": "#/components/schemas/ContentKitDivider" }, { "$ref": "#/components/schemas/ContentKitWebFrame" }, { "$ref": "#/components/schemas/ContentKitCodeBlock" }, { "$ref": "#/components/schemas/ContentKitMarkdown" }, { "$ref": "#/components/schemas/ContentKitCard" }, { "$ref": "#/components/schemas/ContentKitImage" }, { "$ref": "#/components/schemas/ContentKitInput" }, { "$ref": "#/components/schemas/ContentKitSelect" }, { "$ref": "#/components/schemas/ContentKitSwitch" }, { "$ref": "#/components/schemas/ContentKitCheckbox" }, { "$ref": "#/components/schemas/ContentKitRadio" }, { "$ref": "#/components/schemas/ContentKitText" }, { "$ref": "#/components/schemas/ContentKitHint" }, { "$ref": "#/components/schemas/ContentKitLink" }, { "$ref": "#/components/schemas/ContentKitStepperStep" } ], "discriminator": { "propertyName": "type" } }, "ContentKitHStack": { "type": "object", "description": "Horizontal stack of boxes.", "properties": { "type": { "type": "string", "enum": [ "hstack" ] }, "align": { "type": "string", "default": "start", "enum": [ "start", "center", "end" ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } } }, "required": [ "type", "children" ] }, "ContentKitVStack": { "type": "object", "description": "Vertical stack of boxes.", "properties": { "type": { "type": "string", "enum": [ "vstack" ] }, "align": { "type": "string", "default": "start", "enum": [ "start", "center", "end" ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } } }, "required": [ "type", "children" ] }, "ContentKitBox": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "box" ] }, "grow": { "description": "specifies how much of the remaining space in the container should be assigned to the element", "type": "number" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } } }, "required": [ "type", "children" ] }, "ContentKitDivider": { "type": "object", "description": "Divider between 2 boxes in a stack.", "properties": { "type": { "type": "string", "enum": [ "divider" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large" ] } }, "required": [ "type" ] }, "ContentKitDynamicBinding": { "type": "object", "description": "Binding between a property and a state value.", "properties": { "$state": { "type": "string", "description": "Key in the state" } }, "required": [ "$state" ] }, "ContentKitWebFrame": { "type": "object", "description": "Frame for a webpage", "properties": { "type": { "type": "string", "enum": [ "webframe" ] }, "aspectRatio": { "type": "number", "description": "Ratio between width and height. Used to size the webframe." }, "source": { "type": "object", "description": "Content to load in the frame.", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "buttons": { "type": "array", "description": "Controls button shown as an overlay in a corner of the frame.", "items": { "$ref": "#/components/schemas/ContentKitButton" } }, "data": { "type": "object", "description": "Data to communicated to the webframe's content. Each state update will cause the webframe to receive a message.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentKitDynamicBinding" } ] } } }, "required": [ "type", "source" ] }, "ContentKitCodeBlock": { "type": "object", "description": "Code block with syntax highlighting", "properties": { "type": { "type": "string", "enum": [ "codeblock" ] }, "content": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitDynamicBinding" }, { "type": "string", "description": "Code content to display" } ] }, "syntax": { "description": "Syntax to use for highlighting (ex: javascript, python)", "type": "string" }, "lineNumbers": { "oneOf": [ { "type": "boolean" }, { "type": "number", "description": "Line number to start at." } ] }, "buttons": { "type": "array", "description": "Controls button shown as an overlay in a corner of the code block.", "items": { "$ref": "#/components/schemas/ContentKitButton" } }, "state": { "description": "State binding when editable. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "onContentChange": { "$ref": "#/components/schemas/ContentKitAction" }, "header": { "type": "array", "description": "Header displayed before the code lines", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } }, "footer": { "type": "array", "description": "Footer displayed after the code lines", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } } }, "required": [ "type", "content" ] }, "ContentKitMarkdown": { "type": "object", "description": "Block with rich text formatting of a markdown content.", "properties": { "type": { "type": "string", "enum": [ "markdown" ] }, "content": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitDynamicBinding" }, { "type": "string", "description": "Markdown content to display" } ] } }, "required": [ "type", "content" ] }, "ContentKitText": { "type": "object", "description": "Low level text element.", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "style": { "type": "string", "enum": [ "bold", "italic", "code", "strikethrough" ] }, "children": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentKitText" }, { "$ref": "#/components/schemas/ContentKitLink" } ] } } ] } }, "required": [ "type", "children" ] }, "ContentKitURL": { "type": "object", "description": "Specification for an URL in ContentKit.", "properties": { "host": { "type": "string", "description": "Hostname of the URL along with the port number if required.", "example": "api.example.com" }, "pathname": { "type": "string", "description": "Path of the URL prefixed with a `/`.", "example": "/v1/options" }, "query": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentKitDynamicBinding" } ] } } }, "required": [ "host", "pathname" ] }, "ContentKitLink": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "link" ] }, "target": { "type": "object", "properties": { "url": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentKitURL" } ] } }, "required": [ "url" ] }, "children": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "type", "target", "children" ] }, "ContentKitImage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "source": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "aspectRatio": { "type": "number" } }, "required": [ "type", "source", "aspectRatio" ] }, "ContentKitInlineElement": { "description": "Any element that is inline.", "oneOf": [ { "$ref": "#/components/schemas/ContentKitText" }, { "$ref": "#/components/schemas/ContentKitImage" }, { "$ref": "#/components/schemas/ContentKitLink" } ], "discriminator": { "propertyName": "type" } }, "ContentKitCard": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "card" ] }, "title": { "type": "string" }, "hint": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitInlineElement" } } ] }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitIcon" }, { "$ref": "#/components/schemas/ContentKitImage" } ] }, "onPress": { "$ref": "#/components/schemas/ContentKitAction" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } }, "buttons": { "type": "array", "description": "Buttons displayed in the top right corner of the card.", "items": { "$ref": "#/components/schemas/ContentKitButton" } } }, "required": [ "type" ] }, "ContentKitBuiltInSource": { "type": "object", "description": "Built-in sources that can be used to provide a ContentKitSelect.", "properties": { "source": { "type": "string", "enum": [ "openapi" ] } }, "required": [ "source" ] }, "ContentKitSelectOption": { "type": "object", "description": "An individual option in a select element", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "icon": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitIcon" }, { "$ref": "#/components/schemas/ContentKitImage" } ] } }, "required": [ "id", "label" ] }, "ContentKitSelect": { "type": "object", "description": "Creates a drop down menu with a list of options for a user to choose.", "properties": { "type": { "type": "string", "enum": [ "select" ] }, "disabled": { "type": "boolean" }, "state": { "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "initialValue": { "description": "Value to initialize the select with.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "onValueChange": { "$ref": "#/components/schemas/ContentKitAction" }, "placeholder": { "description": "Text that appears in the form control when it has no value set", "type": "string" }, "multiple": { "description": "Should the select accept the selection of multiple options. If true, the state will be an array.", "type": "boolean" }, "acceptInput": { "description": "Should the filter input be allowed to be selected as an option.", "type": "boolean" }, "options": { "description": "Options to be displayed in the select.", "oneOf": [ { "$ref": "#/components/schemas/ContentKitBuiltInSource" }, { "type": "array", "description": "Static list of options", "items": { "$ref": "#/components/schemas/ContentKitSelectOption" } }, { "type": "object", "properties": { "url": { "oneOf": [ { "type": "string", "description": "External source of options. The URL should respond with an array of options." }, { "$ref": "#/components/schemas/ContentKitURL" } ] } }, "required": [ "url" ] } ] } }, "required": [ "type", "state", "options" ] }, "ContentKitSwitch": { "type": "object", "description": "Renders a boolean input.", "properties": { "type": { "type": "string", "enum": [ "switch" ] }, "disabled": { "type": "boolean" }, "state": { "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "initialValue": { "description": "Value to initialize the switch with.", "type": "boolean" }, "onValueChange": { "$ref": "#/components/schemas/ContentKitAction" }, "confirm": { "$ref": "#/components/schemas/ContentKitConfirm" } }, "required": [ "type", "state" ] }, "ContentKitRadio": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "radio" ] }, "disabled": { "type": "boolean" }, "state": { "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "value": { "description": "Value to store in th state when the checkbox is selected.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "confirm": { "$ref": "#/components/schemas/ContentKitConfirm" } }, "required": [ "type", "state", "value" ] }, "ContentKitCheckbox": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "checkbox" ] }, "state": { "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", "type": "string" }, "value": { "description": "Value to store in a state array when the checkbox is selected.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "confirm": { "$ref": "#/components/schemas/ContentKitConfirm" } }, "required": [ "type", "state", "value" ] }, "ContentKitInput": { "type": "object", "description": "Field for an input.", "properties": { "type": { "type": "string", "enum": [ "input" ] }, "label": { "type": "string", "description": "Text label displayed next to the input." }, "hint": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentKitInlineElement" } ] }, "element": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitTextInput" }, { "$ref": "#/components/schemas/ContentKitSelect" }, { "$ref": "#/components/schemas/ContentKitSwitch" }, { "$ref": "#/components/schemas/ContentKitRadio" }, { "$ref": "#/components/schemas/ContentKitCheckbox" }, { "$ref": "#/components/schemas/ContentKitButton" }, { "$ref": "#/components/schemas/ContentKitCodeBlock" } ] } }, "required": [ "type", "label", "element" ] }, "ContentKitHint": { "type": "object", "description": "Element used to contextualize other elements or info.", "properties": { "type": { "type": "string", "enum": [ "hint" ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitInlineElement" } } }, "required": [ "type", "children" ] }, "ContentKitStepperStep": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "step" ] }, "id": { "description": "unique identifier for the step", "type": "string" }, "title": { "description": "title of the step", "type": "string", "maxLength": 50 }, "next": { "description": "indicates if the user can progress to the next step based on some internal validation or condition", "type": "boolean", "default": false }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" }, "minItems": 1 } }, "required": [ "type", "id", "children" ] }, "ContentKitBlockControl": { "type": "object", "description": "Control menu item displayed for the block.", "properties": { "icon": { "$ref": "#/components/schemas/ContentKitIcon" }, "label": { "type": "string" }, "onPress": { "$ref": "#/components/schemas/ContentKitAction" }, "confirm": { "$ref": "#/components/schemas/ContentKitConfirm" } }, "required": [ "label", "onPress" ] }, "ContentKitBlock": { "type": "object", "description": "Higher level element to represent a custom block.", "properties": { "type": { "type": "string", "enum": [ "block" ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } }, "controls": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ContentKitBlockControl" }, { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitBlockControl" } } ] } } }, "required": [ "type", "children" ] }, "ContentKitModal": { "type": "object", "description": "Overlay modal.", "properties": { "type": { "type": "string", "enum": [ "modal" ] }, "title": { "type": "string" }, "subtitle": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitInlineElement" } }, "size": { "type": "string", "enum": [ "medium", "xlarge", "fullscreen" ] }, "returnValue": { "description": "Data passed back to the parent view when the modal is closed. These data are accessible in the \"@ui.modal.close\"", "type": "object" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" } }, "submit": { "$ref": "#/components/schemas/ContentKitButton" } }, "required": [ "type", "children" ] }, "ContentKitStepper": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "stepper" ] }, "activeStep": { "type": "string", "description": "id of the currently active step" }, "onStepChange": { "$ref": "#/components/schemas/ContentKitAction" }, "onComplete": { "$ref": "#/components/schemas/ContentKitAction" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitStepperStep" }, "minItems": 1 } }, "required": [ "type", "activeStep", "onStepChange", "onComplete", "children" ] }, "ContentKitConfiguration": { "type": "object", "description": "Higher level element to define a configuration block. Does not add any UI elements or wrappers. Must be used as a top level element for any configuration component.", "properties": { "type": { "type": "string", "enum": [ "configuration" ] }, "children": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitStepper" }, "minItems": 1, "maxItems": 1 }, { "type": "array", "items": { "$ref": "#/components/schemas/ContentKitDescendantElement" }, "minItems": 1 } ] } }, "required": [ "type", "children" ] }, "ContentKitRootElement": { "description": "Element used as root", "oneOf": [ { "$ref": "#/components/schemas/ContentKitBlock" }, { "$ref": "#/components/schemas/ContentKitModal" }, { "$ref": "#/components/schemas/ContentKitConfiguration" } ], "discriminator": { "propertyName": "type" } }, "ContentKitRenderOutputElement": { "type": "object", "description": "Output of type element in the lifecycle of the component.", "properties": { "type": { "type": "string", "enum": [ "element" ] }, "element": { "$ref": "#/components/schemas/ContentKitRootElement" }, "state": { "type": "object" }, "props": { "$ref": "#/components/schemas/PlainObject" } }, "required": [ "element", "state", "props" ] }, "ContentKitRenderOutputComplete": { "type": "object", "description": "Output of completed lifecycle of the component.", "properties": { "type": { "type": "string", "enum": [ "complete" ] }, "returnValue": { "type": "object" } }, "required": [ "type" ] }, "ContentKitRenderOutput": { "type": "object", "description": "Output of the integration when rendering a UI.", "oneOf": [ { "$ref": "#/components/schemas/ContentKitRenderOutputElement" }, { "$ref": "#/components/schemas/ContentKitRenderOutputComplete" } ] }, "RenderIntegrationUI": { "type": "object", "properties": { "componentId": { "type": "string", "description": "ID of the component to render in the integration." }, "props": { "description": "Current properties of the UI.", "$ref": "#/components/schemas/PlainObject" }, "state": { "type": "object", "description": "Current local state of the UI." }, "context": { "$ref": "#/components/schemas/ContentKitContext" }, "action": { "$ref": "#/components/schemas/ContentKitAction" } }, "required": [ "componentId", "props", "context" ] }, "UpdateIntegrationInstallation": { "type": "object", "properties": { "externalIds": { "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, "configuration": { "$ref": "#/components/schemas/IntegrationInstallationConfiguration" }, "space_selection": { "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" }, "site_selection": { "$ref": "#/components/schemas/IntegrationInstallationSiteSelection" } } }, "UpdateIntegrationSpaceInstallation": { "type": "object", "properties": { "externalIds": { "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, "configuration": { "$ref": "#/components/schemas/IntegrationInstallationConfiguration" } } }, "UpdateIntegrationSiteInstallation": { "type": "object", "properties": { "externalIds": { "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, "configuration": { "$ref": "#/components/schemas/IntegrationInstallationConfiguration" } } }, "CreateOrganization": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/OrganizationTitle" }, "emailDomains": { "$ref": "#/components/schemas/OrganizationEmailDomains" }, "type": { "$ref": "#/components/schemas/OrganizationType" }, "useCase": { "$ref": "#/components/schemas/OrganizationUseCase" } }, "required": [ "title" ] }, "SiteSectionTitle": { "type": "string", "description": "Title of the site section", "minLength": 2, "maxLength": 128 }, "LocalizedString128": { "type": "object", "description": "Localized string value with a 128 character limit, keyed by locale. Contains overrides for non-default languages only.", "additionalProperties": { "type": "string", "maxLength": 128 }, "propertyNames": { "$ref": "#/components/schemas/TranslationLanguage" } }, "SiteSectionDescription": { "type": "string", "description": "Description of the site section", "minLength": 0, "maxLength": 256 }, "LocalizedString256": { "type": "object", "description": "Localized string value with a 256 character limit, keyed by locale. Contains overrides for non-default languages only.", "additionalProperties": { "type": "string", "maxLength": 256 }, "propertyNames": { "$ref": "#/components/schemas/TranslationLanguage" } }, "SiteSectionPath": { "type": "string", "description": "Path to the section on the site", "minLength": 1, "maxLength": 100 }, "SiteSpacePath": { "type": "string", "description": "Path to the space on the site", "minLength": 1, "maxLength": 100 }, "SiteSpace": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type, which is always \"site-space\"", "enum": [ "site-space" ] }, "id": { "type": "string", "description": "Unique identifier of the site-space" }, "path": { "$ref": "#/components/schemas/SiteSpacePath" }, "section": { "type": "string", "description": "ID of the section the space belongs to in the site" }, "space": { "$ref": "#/components/schemas/Space" }, "title": { "type": "string" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "default": { "type": "boolean", "description": "Whether this is the default space for the site" }, "condition": { "description": "Conditional expression used to evaluate whether the site space should be shown to the site's visitor.", "$ref": "#/components/schemas/Expression" }, "draft": { "type": "boolean", "description": "Whether the site space is draft and not live." }, "hasAdvancedCustomizationFeature": { "type": "boolean", "description": "Whether the space has advanced customization feature enabled" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "published": { "type": "string", "description": "URL of the published version of the site-space. Only defined when site is published.", "format": "uri" } } }, "hidden": { "type": "boolean", "description": "Whether the site space is hidden. If true, the site space will not be shown in the site's navigation." } }, "required": [ "object", "id", "space", "title", "path", "draft", "urls" ] }, "SiteSection": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type, which is always \"site-section\"", "enum": [ "site-section" ] }, "id": { "type": "string", "description": "Unique identifier of the site section" }, "title": { "$ref": "#/components/schemas/SiteSectionTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "description": { "$ref": "#/components/schemas/SiteSectionDescription" }, "localizedDescription": { "$ref": "#/components/schemas/LocalizedString256" }, "default": { "type": "boolean", "description": "Whether this is the default section for the site" }, "draft": { "type": "boolean", "description": "Whether the site section is draft and not live." }, "path": { "$ref": "#/components/schemas/SiteSectionPath" }, "condition": { "description": "Conditional expression used to evaluate whether the site section should be shown to the site's visitor.", "$ref": "#/components/schemas/Expression" }, "sectionGroup": { "type": "string", "description": "ID of the section group the section belongs to in the site" }, "siteSpaces": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSpace" } }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "published": { "type": "string", "description": "URL of the published version of the site section. Only defined when site is published.", "format": "uri" } } }, "icon": { "$ref": "#/components/schemas/Icon" } }, "required": [ "object", "id", "title", "path", "draft", "siteSpaces", "urls" ] }, "SiteSectionGroupTitle": { "type": "string", "description": "Title of the site section group", "minLength": 1, "maxLength": 100 }, "SiteSectionGroup": { "type": "object", "properties": { "object": { "type": "string", "description": "The object type, which is always \"site-section-group\"", "enum": [ "site-section-group" ] }, "id": { "type": "string", "description": "Unique identifier of the site section group" }, "title": { "$ref": "#/components/schemas/SiteSectionGroupTitle" }, "localizedTitle": { "$ref": "#/components/schemas/LocalizedString128" }, "sections": { "type": "array", "deprecated": true, "description": "List of site section ids that are members of the group. Use `children` instead.", "items": { "$ref": "#/components/schemas/SiteSection" } }, "sectionGroup": { "type": "string", "description": "ID of the parent section group this group belongs to" }, "draft": { "type": "boolean", "description": "Whether the site section group is draft and not live." }, "children": { "type": "array", "description": "List of all child sections and groups nested under this group", "items": { "oneOf": [ { "$ref": "#/components/schemas/SiteSection" }, { "$ref": "#/components/schemas/SiteSectionGroup" } ] } }, "icon": { "$ref": "#/components/schemas/Icon" } }, "required": [ "object", "id", "title", "draft", "sections", "children" ] }, "SiteStructure": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "sections" ] }, "structure": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SiteSection" }, { "$ref": "#/components/schemas/SiteSectionGroup" } ] } } }, "required": [ "type", "structure" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "siteSpaces" ] }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSpace" } } }, "required": [ "type", "structure" ] } ] }, "OrganizationAllSite": { "type": "object", "properties": { "site": { "$ref": "#/components/schemas/Site" }, "structure": { "$ref": "#/components/schemas/SiteStructure" } }, "required": [ "site", "structure" ] }, "OrganizationAllCollection": { "type": "object", "properties": { "collection": { "$ref": "#/components/schemas/Collection" }, "content": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationAllCollection" }, { "$ref": "#/components/schemas/OrganizationAllSpace" } ] } } }, "required": [ "collection", "content" ] }, "OrganizationAllSpace": { "type": "object", "properties": { "space": { "$ref": "#/components/schemas/Space" } }, "required": [ "space" ] }, "OrganizationAllContent": { "type": "object", "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationAllSite" } }, "spaces": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationAllCollection" }, { "$ref": "#/components/schemas/OrganizationAllSpace" } ] } }, "deletedSpaces": { "description": "List of soft-deleted spaces.", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationAllSpace" } } }, "required": [ "sites", "spaces", "deletedSpaces" ] }, "MemberContentPermission": { "type": "object", "description": "Permission of a member in a content.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRole" }, "space": { "$ref": "#/components/schemas/Space" } }, "required": [ "permission", "space" ] }, "TeamMemberRole": { "type": "string", "description": "\"The role of a team member.\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": "[email protected]" }, "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" ] } ] }, "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 }, "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" ] }, "pdf": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, PDF export is enabled for the published site." } }, "required": [ "enabled" ] }, "feedback": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, feedback gathering is enabled" } }, "required": [ "enabled" ] }, "ai": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/CustomizationAIMode" }, "suggestions": { "$ref": "#/components/schemas/CustomizationSuggestedQuestions" } }, "required": [ "mode" ] }, "advancedCustomization": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, Advanced customization is enabled" } }, "required": [ "enabled" ] }, "git": { "type": "object", "properties": { "showEditLink": { "type": "boolean", "description": "Whether the published site should show a link to edit the content on the git provider set up in the Git Sync" } }, "required": [ "showEditLink" ] }, "pageActions": { "type": "object", "properties": { "externalAI": { "type": "boolean", "description": "Whether actions to open ChatGPT, Anthropic, etc. should be available in the page menu." }, "markdown": { "type": "boolean", "description": "Whether the copy and open the markdown version of the page should be available in the page menu." }, "mcp": { "type": "boolean", "description": "Whether an action to connect to the docs using the MCP server should be available in the page menu." } }, "required": [ "externalAI", "markdown", "mcp" ] }, "externalLinks": { "type": "object", "properties": { "target": { "$ref": "#/components/schemas/SiteExternalLinksTarget" } }, "required": [ "target" ] }, "pagination": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the pagination navigation should be displayed on pages." } }, "required": [ "enabled" ] }, "trademark": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible" } }, "required": [ "enabled" ] }, "privacyPolicy": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/URL" } } }, "socialPreview": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/URL" } } }, "socialAccounts": { "$ref": "#/components/schemas/SiteSocialAccounts" }, "insights": { "type": "object", "properties": { "trackingCookie": { "type": "boolean", "description": "Whether GitBook identifies the visitor on the site using a cookie.", "default": true } }, "required": [ "trackingCookie" ] } }, "required": [ "styling", "internationalization", "favicon", "header", "footer", "themes", "pdf", "feedback", "ai", "advancedCustomization", "trademark", "externalLinks", "pagination", "pageActions", "git", "privacyPolicy", "socialPreview", "socialAccounts", "insights" ] }, "SiteCustomizationSettings": { "allOf": [ { "$ref": "#/components/schemas/SiteCustomizationSettingsBase" }, { "type": "object", "properties": { "updatedAt": { "description": "When the customization settings were updated. If missing, customization was not updated.", "$ref": "#/components/schemas/Timestamp" } } } ] }, "SiteIntegrationScript": { "type": "object", "properties": { "script": { "description": "Script URL to load.", "$ref": "#/components/schemas/URL" }, "contentSecurityPolicy": { "description": "Content Security Policy to secure the loading of this script.", "type": "string" }, "cookies": { "type": "boolean", "description": "If true, the script will potentially load use cookies and visitors should be aware." } }, "required": [ "script", "cookies" ] }, "PublishedContentSite": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "published-content-site" ] }, "site": { "$ref": "#/components/schemas/Site" }, "structure": { "$ref": "#/components/schemas/SiteStructure" }, "customizations": { "type": "object", "properties": { "site": { "$ref": "#/components/schemas/SiteCustomizationSettings" }, "siteSpaces": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SiteCustomizationSettings" } } }, "required": [ "site", "siteSpaces" ] }, "scripts": { "type": "array", "items": { "$ref": "#/components/schemas/SiteIntegrationScript" } } }, "required": [ "object", "site", "structure", "customizations", "scripts" ] }, "ShareLinkName": { "type": "string", "description": "Name of the share link", "minLength": 0, "maxLength": 50 }, "ShareLink": { "type": "object", "properties": { "object": { "type": "string", "description": "Type of Object, always equals to \"share-link\"", "enum": [ "share-link" ] }, "id": { "type": "string", "description": "Unique identifier for the share-link" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "name": { "$ref": "#/components/schemas/ShareLinkName" }, "active": { "type": "boolean" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "published": { "type": "string", "description": "URL of the published version of the share-link.", "format": "uri" } } } }, "required": [ "object", "id", "createdAt", "urls" ] }, "SiteStructureItemPointer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site-space", "site-section", "site-section-group" ] }, "id": { "type": "string", "description": "Unique identifier for the site structure item (site space, site section or site section group)." } }, "required": [ "type", "id" ] }, "SiteStructureItemMovePosition": { "type": "object", "description": "Position at which to move the site structure item (site space, site section or site section group).", "properties": { "before": { "$ref": "#/components/schemas/SiteStructureItemPointer" }, "after": { "$ref": "#/components/schemas/SiteStructureItemPointer" } } }, "SiteStructureItem": { "title": "Site Structure Item", "type": "object", "description": "A site structure item can be a site space, a site section or a site section group.\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." }, "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." } } } ] }, "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" ] } ] }, "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" ] } ] }, "ContextConnection": { "allOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "context-connection" ] }, "id": { "type": "string", "description": "The ID of the connection" }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "syncedAt": { "$ref": "#/components/schemas/Timestamp" }, "label": { "$ref": "#/components/schemas/ContextConnectionLabel" }, "status": { "$ref": "#/components/schemas/ContextConnectionStatus" }, "records": { "type": "integer", "description": "Number of records ingested from this connection" }, "failureMessage": { "type": "string", "description": "Failure message when synchronization fails" }, "email": { "type": "object", "description": "Parameters associated with the connection when it is an email connection", "properties": { "ingestionAddress": { "type": "string", "description": "Inbound email address for the connection", "format": "email" } } }, "usageSettings": { "$ref": "#/components/schemas/ContextUsageSettings" }, "urls": { "type": "object", "description": "URLs associated with the connection", "properties": { "location": { "type": "string", "description": "URL of the connection in the API", "format": "uri" } }, "required": [ "location" ] } }, "required": [ "object", "id", "createdAt", "status", "records", "usageSettings", "urls" ] }, { "$ref": "#/components/schemas/ContextConnectorSetup" } ] }, "SiteTopicUsageSettings": { "type": "object", "properties": { "changeRequests": { "type": "boolean", "description": "Whether to use context to propose change requests" } }, "required": [ "changeRequests" ] }, "SiteTopic": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "context-topic" ] }, "id": { "type": "string", "description": "The ID of the topic" }, "label": { "type": "string", "description": "The label of the topic" }, "parent": { "type": "object", "description": "The parent topic when this topic is nested under another one", "properties": { "id": { "type": "string", "description": "The ID of the parent topic" }, "label": { "type": "string", "description": "The label of the parent topic" } }, "required": [ "id", "label" ] }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "icon": { "$ref": "#/components/schemas/Icon" }, "summary": { "$ref": "#/components/schemas/JSONDocument" }, "usageSettings": { "$ref": "#/components/schemas/SiteTopicUsageSettings" }, "pages": { "type": "number", "description": "The number of pages associated with the topic" }, "records": { "type": "number", "description": "The number of records in the topic" }, "findings": { "type": "object", "description": "The number of findings linked to the topic", "properties": { "open": { "type": "number", "description": "The number of open findings linked to the topic" }, "total": { "type": "number", "description": "The total number of findings linked to the topic" } }, "required": [ "open", "total" ] }, "questions": { "$ref": "#/components/schemas/SiteQuestionStats" }, "urls": { "type": "object", "description": "URLs associated with the topic", "properties": { "location": { "type": "string", "description": "URL of the topic in the API", "format": "uri" } }, "required": [ "location" ] } }, "required": [ "object", "id", "label", "summary", "icon", "usageSettings", "pages", "records", "findings", "questions", "createdAt", "updatedAt", "urls" ] }, "SiteQuestionAnswerRelevance": { "type": "string", "description": "Relevance classification of the user question.", "enum": [ "relevant", "spam", "off-topic", "unclear" ] }, "SiteQuestionAnswerResolution": { "type": "string", "description": "Whether the response answered the question.", "enum": [ "no", "partially", "yes" ] }, "SiteQuestionAnswerSourceBase": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site-question-answer-source" ] }, "id": { "type": "string", "description": "The ID of the source." }, "weight": { "type": "number", "description": "Relative weight of this source in the generated answer." }, "title": { "type": "string", "description": "The title of the source." }, "urls": { "type": "object", "description": "URLs associated with the site question answer.", "properties": { "location": { "type": "string", "format": "uri", "description": "URL of the site question answer in the API." } }, "required": [ "location" ] } }, "required": [ "object", "id", "title", "weight", "urls" ] }, "SiteQuestionAnswerSourcePage": { "allOf": [ { "$ref": "#/components/schemas/SiteQuestionAnswerSourceBase" }, { "type": "object", "title": "Page source", "description": "Source data pointing to a page used for a site question answer.", "properties": { "type": { "type": "string", "enum": [ "page" ] }, "space": { "type": "string", "description": "The space ID of the source page." }, "revision": { "type": "string", "description": "The revision ID used for this source page." }, "page": { "type": "string", "description": "The page ID of the source page." } }, "required": [ "type", "space", "revision", "page" ] } ] }, "SiteQuestionAnswerSourceRecord": { "allOf": [ { "$ref": "#/components/schemas/SiteQuestionAnswerSourceBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "record" ] }, "record": { "type": "string", "description": "The site context record ID." }, "connector": { "$ref": "#/components/schemas/ContextConnector" } }, "required": [ "type", "record" ] } ] }, "SiteQuestionAnswerSource": { "oneOf": [ { "$ref": "#/components/schemas/SiteQuestionAnswerSourcePage" }, { "$ref": "#/components/schemas/SiteQuestionAnswerSourceRecord" } ], "discriminator": { "propertyName": "type" } }, "SiteQuestionAnswerHelpfulness": { "type": "string", "description": "Helpfulness of the response for the end user need.", "enum": [ "low", "medium", "high" ] }, "SiteCoreChannelType": { "type": "string", "enum": [ "site", "embed", "api" ] }, "SiteConfigurableChannelType": { "type": "string", "enum": [ "builtin:slack", "builtin:discord", "builtin:github", "builtin:linear" ] }, "SiteQuestionAnswer": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site-question-answer" ] }, "id": { "type": "string", "description": "The ID of the site question answer." }, "question": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the parent site question." }, "type": { "$ref": "#/components/schemas/SiteQuestionType" } }, "required": [ "id", "type" ] }, "topics": { "type": "array", "description": "The IDs of the associated site topics.", "items": { "type": "string" } }, "input": { "type": "object", "required": [ "text", "raw" ], "properties": { "text": { "type": "string", "description": "Normalized question text for this answer." }, "raw": { "type": "string", "description": "Raw question text as asked by the user." } } }, "thread": { "type": "object", "required": [ "id", "previous" ], "properties": { "id": { "type": "string", "description": "The ID of the thread this answer belongs to." }, "previous": { "type": "string", "description": "ID of the previous answer in the same thread." } } }, "session": { "$ref": "#/components/schemas/SiteInsightsSession" }, "feedback": { "type": "object", "required": [ "rating" ], "properties": { "rating": { "type": "integer", "enum": [ -1, 1 ], "description": "Feedback rating provided by the user." } } }, "responseId": { "type": "string", "description": "The response identifier for this answer." }, "language": { "type": "string", "description": "ISO language code of the question." }, "answered": { "$ref": "#/components/schemas/SiteQuestionAnswerResolution" }, "helpfulness": { "$ref": "#/components/schemas/SiteQuestionAnswerHelpfulness" }, "relevance": { "$ref": "#/components/schemas/SiteQuestionAnswerRelevance" }, "channel": { "oneOf": [ { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/SiteCoreChannelType" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/SiteConfigurableChannelType" }, "id": { "type": [ "string", "null" ], "description": "ID of the associated site channel when the answer originates from a configurable channel. Null if the channel has been deleted." } }, "required": [ "type", "id" ] } ] }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "urls": { "type": "object", "description": "URLs associated with the site question answer.", "properties": { "location": { "type": "string", "format": "uri", "description": "URL of the site question answer in the API." } }, "required": [ "location" ] } }, "required": [ "object", "id", "question", "topics", "input", "responseId", "language", "answered", "helpfulness", "relevance", "channel", "createdAt", "urls" ] }, "AIMessageRole": { "type": "string", "enum": [ "user", "assistant", "developer" ] }, "AIToolCallGetPageContent": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getPageContent" ] }, "spaceId": { "type": "string", "description": "The ID of the space being accessed." }, "revisionId": { "type": "string", "description": "The ID of the revision within which the page content is being fetched." }, "page": { "$ref": "#/components/schemas/ChangedRevisionPage" } }, "required": [ "tool", "spaceId", "page", "revisionId" ] }, "AIToolCallGetRecordContent": { "type": "object", "description": "Tool to read the body of an external record.", "properties": { "tool": { "type": "string", "enum": [ "getRecordContent" ] }, "siteId": { "type": "string", "description": "The ID of the site owning the context record." }, "recordId": { "type": "string", "description": "The ID of the context record." }, "title": { "type": "string", "description": "The title of the record." }, "url": { "type": "string", "format": "uri", "description": "URL of the record in the source system." } }, "required": [ "tool", "siteId", "recordId", "title" ] }, "AIToolCallGetPages": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getPages" ] }, "spaceId": { "type": "string", "description": "The ID of the space being accessed." }, "revisionId": { "type": "string", "description": "The revision ID of the space." } }, "required": [ "tool", "spaceId", "revisionId" ] }, "AIToolCallGetReusableContents": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "getReusableContents" ] }, "spaceId": { "type": "string", "description": "The ID of the space being accessed." }, "revisionId": { "type": "string", "description": "The revision ID of the space." } }, "required": [ "tool", "spaceId", "revisionId" ] }, "AIToolCallSearchResultPage": { "type": "object", "title": "Page result", "description": "Result of a search matching a page.", "properties": { "type": { "type": "string", "enum": [ "page" ] }, "spaceId": { "type": "string", "description": "The ID of the space" }, "pageId": { "type": "string", "description": "The ID of the page" }, "revisionId": { "type": "string", "description": "The revision ID of the result" }, "anchor": { "type": "string", "description": "The anchor of the result" }, "title": { "type": "string", "description": "The title of the result" }, "description": { "type": "string", "description": "The description of the result" } }, "required": [ "type", "spaceId", "pageId", "revisionId", "title" ] }, "AIToolCallSearchResultRecord": { "type": "object", "title": "Site context record result", "description": "Result of a search matching a site context record.", "properties": { "type": { "type": "string", "enum": [ "record" ] }, "siteId": { "type": "string", "description": "The ID of the site owning the context record" }, "recordId": { "type": "string", "description": "The ID of the context record" }, "title": { "type": "string", "description": "The title of the record" }, "description": { "type": "string", "description": "The description of the record" }, "url": { "type": "string", "format": "uri", "description": "URL of the record in its original source" } }, "required": [ "type", "siteId", "recordId", "title" ] }, "AIToolCallSearchResult": { "description": "Result of a search", "oneOf": [ { "$ref": "#/components/schemas/AIToolCallSearchResultPage" }, { "$ref": "#/components/schemas/AIToolCallSearchResultRecord" } ], "discriminator": { "propertyName": "type" } }, "AIToolCallSearch": { "type": "object", "description": "Tool to search for content", "properties": { "tool": { "type": "string", "enum": [ "search" ] }, "query": { "type": "string", "description": "The query that has been searched for." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AIToolCallSearchResult" } } }, "required": [ "tool", "query", "results" ] }, "AIToolCallEditPage": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "editPage" ] }, "spaceId": { "type": "string", "description": "The ID of the space being edited." }, "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" ] }, "AIToolCallCreateChangeRequest": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "createChangeRequest" ] }, "spaceId": { "type": "string", "description": "The ID of the space the change request belongs to." }, "action": { "type": "string", "enum": [ "create", "update" ] }, "changeRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the change request." }, "number": { "type": "number", "description": "Incremental identifier of the change request." }, "subject": { "type": "string", "description": "A brief summary of the change request." } }, "required": [ "id", "number", "subject" ] } }, "required": [ "tool", "spaceId", "action", "changeRequest" ] }, "AIToolCallComment": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "comment" ] }, "spaceId": { "type": "string", "description": "The ID of the space being commented." }, "page": { "description": "The page being commented.", "$ref": "#/components/schemas/ChangedRevisionPage" }, "commentId": { "type": "string", "description": "The ID of the comment being posted." } }, "required": [ "tool", "spaceId", "commentId" ] }, "AIToolCallReplyToComment": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "replyToComment" ] }, "spaceId": { "type": "string", "description": "The ID of the space being commented." }, "page": { "description": "The page being commented.", "$ref": "#/components/schemas/ChangedRevisionPage" }, "commentId": { "type": "string", "description": "The ID of the comment being replied to." }, "replyId": { "type": "string", "description": "The ID of the reply being posted." } }, "required": [ "tool", "spaceId", "commentId", "replyId" ] }, "AIToolCallSubmitChangeRequestReview": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "submitChangeRequestReview" ] }, "spaceId": { "type": "string", "description": "The ID of the space where the review was submitted." }, "changeRequestId": { "type": "string", "description": "The ID of the change request being reviewed." }, "status": { "$ref": "#/components/schemas/ChangeRequestReviewStatus", "description": "Result of the review." }, "reviewId": { "type": "string", "description": "Identifier of the review that was created." }, "commentId": { "type": "string", "description": "Identifier of the comment that was created as part of the review." } }, "required": [ "tool", "spaceId", "changeRequestId", "status", "reviewId", "commentId" ] }, "AIToolCallMCP": { "type": "object", "description": "Tool called from an MCP server", "properties": { "tool": { "type": "string", "enum": [ "mcp" ] }, "mcpServerId": { "type": "string", "description": "The ID of the MCP server that has been called." }, "mcpToolName": { "type": "string", "description": "The name of the tool that has been called." }, "mcpToolTitle": { "type": "string", "description": "The title of the tool that has been called." } }, "required": [ "tool", "mcpServerId", "mcpToolName" ] }, "AIToolCallOtherSummary": { "type": "object", "description": "Summary of a generic tool call.", "properties": { "icon": { "$ref": "#/components/schemas/Icon" }, "text": { "type": "string", "description": "Text to display to the user to describe the tool call." } }, "required": [ "icon", "text" ] }, "AIToolCallOther": { "type": "object", "description": "Any tool call that is unknown by GitBook", "properties": { "tool": { "type": "string", "enum": [ "other" ] }, "summary": { "$ref": "#/components/schemas/AIToolCallOtherSummary" } }, "required": [ "tool", "summary" ] }, "AIToolCall": { "oneOf": [ { "$ref": "#/components/schemas/AIToolCallGetPageContent" }, { "$ref": "#/components/schemas/AIToolCallGetRecordContent" }, { "$ref": "#/components/schemas/AIToolCallGetPages" }, { "$ref": "#/components/schemas/AIToolCallGetReusableContents" }, { "$ref": "#/components/schemas/AIToolCallSearch" }, { "$ref": "#/components/schemas/AIToolCallEditPage" }, { "$ref": "#/components/schemas/AIToolCallCreatePage" }, { "$ref": "#/components/schemas/AIToolCallDeletePage" }, { "$ref": "#/components/schemas/AIToolCallRenamePage" }, { "$ref": "#/components/schemas/AIToolCallMovePage" }, { "$ref": "#/components/schemas/AIToolCallListModifiedPages" }, { "$ref": "#/components/schemas/AIToolCallGetPageDiff" }, { "$ref": "#/components/schemas/AIToolCallCreateReusableContent" }, { "$ref": "#/components/schemas/AIToolCallEditReusableContent" }, { "$ref": "#/components/schemas/AIToolCallGetReusableContent" }, { "$ref": "#/components/schemas/AIToolCallCreateChangeRequest" }, { "$ref": "#/components/schemas/AIToolCallComment" }, { "$ref": "#/components/schemas/AIToolCallReplyToComment" }, { "$ref": "#/components/schemas/AIToolCallSubmitChangeRequestReview" }, { "$ref": "#/components/schemas/AIToolCallMCP" }, { "$ref": "#/components/schemas/AIToolCallOther" } ] }, "AIMessageStepPhase": { "type": "string", "description": "The phase of a step in a message from the AI agent.", "enum": [ "commentary", "final_answer" ] }, "Timerange": { "type": "object", "properties": { "start": { "$ref": "#/components/schemas/Timestamp" }, "end": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "start", "end" ] }, "AIAttachmentImage": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ] }, "url": { "$ref": "#/components/schemas/URL" } }, "required": [ "type", "url" ] }, "AIAttachmentFile": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "url": { "$ref": "#/components/schemas/URL" }, "filename": { "type": "string", "description": "Name of the file." }, "contentType": { "type": "string", "enum": [ "application/pdf" ] } }, "required": [ "type", "url", "filename", "contentType" ] }, "AIAttachment": { "oneOf": [ { "$ref": "#/components/schemas/AIAttachmentImage" }, { "$ref": "#/components/schemas/AIAttachmentFile" } ] }, "AIMessageStep": { "type": "object", "description": "A step in a message from the AI agent.", "properties": { "content": { "$ref": "#/components/schemas/JSONDocument" }, "reasoning": { "$ref": "#/components/schemas/JSONDocument" }, "toolCalls": { "type": "array", "items": { "$ref": "#/components/schemas/AIToolCall" } }, "phase": { "$ref": "#/components/schemas/AIMessageStepPhase" }, "timing": { "type": "object", "description": "The timing of the step.", "properties": { "reasoning": { "$ref": "#/components/schemas/Timerange" } } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AIAttachment" } } } }, "AIMessageTask": { "oneOf": [ { "type": "object", "description": "When the agent is responding to a comment.", "properties": { "type": { "type": "string", "enum": [ "respond_to_comment" ] }, "spaceId": { "type": "string", "description": "The ID of the space to respond to the comment in." }, "changeRequestId": { "type": "string", "description": "The ID of the change request to respond to the comment in." }, "commentId": { "type": "string", "description": "The ID of the comment to respond to." } }, "required": [ "type", "spaceId", "commentId" ] }, { "type": "object", "description": "When the agent is reviewing a change request.", "properties": { "type": { "type": "string", "enum": [ "review_change_request" ] }, "spaceId": { "type": "string", "description": "The ID of the space the change request is in." }, "changeRequestId": { "type": "string", "description": "The ID of the change request to review." } }, "required": [ "type", "spaceId", "changeRequestId" ] }, { "type": "object", "description": "When the agent is implementing a task in a change request.", "properties": { "type": { "type": "string", "enum": [ "implement_change_request" ] }, "spaceId": { "type": "string", "description": "The ID of the space the change request is in." }, "changeRequestId": { "type": "string", "description": "The ID of the change request to implement the task in." } }, "required": [ "type", "spaceId", "changeRequestId" ] } ] }, "AIMessageResponseMetadata": { "description": "The response that generated this message.", "type": "object", "properties": { "stopReason": { "type": "string", "description": "The reason the response was stopped. If not defined, the response finished normally.", "enum": [ "aborted" ] }, "id": { "type": "string", "description": "The ID of the response that generated this message. It can be undefined if the stream was aborted." }, "previous": { "type": "string", "description": "The ID of the previous response that this message is based on." } } }, "AIMessage": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "$ref": "#/components/schemas/AIMessageRole" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AIMessageStep" } }, "task": { "$ref": "#/components/schemas/AIMessageTask" }, "response": { "$ref": "#/components/schemas/AIMessageResponseMetadata" } }, "required": [ "id", "role", "steps" ] }, "SiteQuestionAnswerWithResponse": { "allOf": [ { "$ref": "#/components/schemas/SiteQuestionAnswer" }, { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/AIMessage" } }, "required": [ "response" ] } ] }, "SiteSpaceCustomizationSettings": { "allOf": [ { "$ref": "#/components/schemas/SiteCustomizationSettings" }, { "type": "object", "properties": { "hasOverrides": { "type": "boolean", "description": "Indicates whether the site customization settings have been overridden." } }, "required": [ "hasOverrides" ] } ] }, "SiteSectionGroupPointer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site-section", "site-section-group" ] }, "id": { "type": "string", "description": "Unique identifier for the site section" } }, "required": [ "type", "id" ] }, "SiteSectionGroupMovePosition": { "type": "object", "description": "Position at which to move the site section group.", "properties": { "before": { "$ref": "#/components/schemas/SiteSectionGroupPointer" }, "after": { "$ref": "#/components/schemas/SiteSectionGroupPointer" } } }, "SiteSectionPointer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site-section" ] }, "siteSection": { "type": "string", "description": "Unique identifier for the site section" } }, "required": [ "type", "siteSection" ] }, "SiteSectionMovePosition": { "type": "object", "description": "Position at which to move the site section to.", "properties": { "before": { "$ref": "#/components/schemas/SiteSectionPointer" }, "after": { "$ref": "#/components/schemas/SiteSectionPointer" } } }, "SiteSpacePointer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site-space" ] }, "siteSpace": { "type": "string", "description": "Unique identifier for the site space" } }, "required": [ "type", "siteSpace" ] }, "SiteSpaceMovePosition": { "type": "object", "description": "Position at which to move the site space to.", "properties": { "before": { "$ref": "#/components/schemas/SiteSpacePointer" }, "after": { "$ref": "#/components/schemas/SiteSpacePointer" } } }, "InviteSiteUsersAndTeams": { "type": "object", "properties": { "role": { "description": "Role to set.", "$ref": "#/components/schemas/MemberRoleOrGuest" } }, "anyOf": [ { "type": "object", "properties": { "teams": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "The ID of the team to be invited" } } }, "required": [ "teams" ] }, { "type": "object", "properties": { "users": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "The ID of the user to be invited" } } }, "required": [ "users" ] } ], "required": [ "role" ] }, "OrganizationPointer": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] }, "organization": { "type": "string", "description": "Unique identifier for the organization" } }, "required": [ "type", "organization" ] }, "UserSitePermissionSiteOrigin": { "type": "object", "description": "Direct site permission origin.", "properties": { "type": { "type": "string", "enum": [ "site" ] }, "site": { "type": "string", "description": "Unique identifier for the site" }, "reason": { "type": "string", "description": "Why the permission was enforced at the site level.", "enum": [ "member", "team", "default" ] }, "team": { "type": "string", "description": "Unique identifier for the team when the permission comes from a team override." } }, "required": [ "type", "site", "reason" ] }, "UserSitePermissionOrigin": { "description": "The origin that enforced the effective permission level for a user in a site.", "oneOf": [ { "$ref": "#/components/schemas/SpacePointer" }, { "$ref": "#/components/schemas/OrganizationPointer" }, { "$ref": "#/components/schemas/UserSitePermissionSiteOrigin" } ] }, "UserSitePermission": { "type": "object", "description": "Permission of a user in a site.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "user": { "$ref": "#/components/schemas/User" }, "origin": { "$ref": "#/components/schemas/UserSitePermissionOrigin" } }, "required": [ "permission", "user", "origin" ] }, "UserSitePermissionOverride": { "type": "object", "description": "Permission override of a user in a site.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "permission", "user" ] }, "TeamSitePermissionOverride": { "type": "object", "description": "Permission override of a team in a site.", "properties": { "permission": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "team": { "$ref": "#/components/schemas/OrganizationTeam" } }, "required": [ "permission", "team" ] }, "AIMessageContext": { "type": "object", "description": "Context about the current user sending a message.", "properties": { "location": { "type": "object", "properties": { "spaceId": { "type": "string", "description": "ID of the current space." }, "pageId": { "type": "string", "description": "ID of the current page." } }, "required": [ "spaceId", "pageId" ] }, "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" } }, "required": [ "anchorKey", "anchorOffset", "focusKey", "focusOffset" ] } } }, "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" ] }, "AIStreamResponse": { "oneOf": [ { "$ref": "#/components/schemas/AIStreamResponseStart" }, { "$ref": "#/components/schemas/AIStreamResponseStepStart" }, { "$ref": "#/components/schemas/AIStreamResponseFinish" }, { "$ref": "#/components/schemas/AIStreamResponseDocument" }, { "$ref": "#/components/schemas/AIStreamResponseObject" }, { "$ref": "#/components/schemas/AIStreamResponseToolCall" }, { "$ref": "#/components/schemas/AIStreamResponseToolCallPending" }, { "$ref": "#/components/schemas/AIStreamResponseFollowupSuggestion" }, { "$ref": "#/components/schemas/AIStreamResponseAttachment" } ] }, "SiteSettingsScanTopics": { "type": "string", "enum": [ "auto", "never" ], "description": "Controls when topics are being scanned for findings." }, "SiteSettingsFindingChangeRequests": { "type": "string", "enum": [ "always", "auto-fixable", "never" ], "description": "Controls how issue remediation change requests should be handled for a site." }, "SiteAgentSettingsInput": { "type": "object", "properties": { "scans": { "description": "Settings related to scanning for a site.", "type": "object", "properties": { "topics": { "$ref": "#/components/schemas/SiteSettingsScanTopics" } }, "required": [ "topics" ] }, "findings": { "description": "Settings related to processing of findings for a site.", "type": "object", "properties": { "changeRequests": { "$ref": "#/components/schemas/SiteSettingsFindingChangeRequests" } }, "required": [ "changeRequests" ] }, "editing": { "description": "Site-specific instructions for the editing agent.", "type": "object", "properties": { "customInstructions": { "$ref": "#/components/schemas/JSONDocument" } }, "required": [ "customInstructions" ] } }, "required": [ "scans", "findings", "editing" ] }, "SiteAgentSettings": { "allOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site-agent-settings" ] }, "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "updatedBy": { "type": "string", "description": "Identifier of the member who last updated the settings." }, "urls": { "type": "object", "properties": { "location": { "type": "string", "description": "Relative URL to the resource in the API." } }, "required": [ "location" ] } }, "required": [ "object", "urls" ] }, { "$ref": "#/components/schemas/SiteAgentSettingsInput" } ] }, "SiteInsightsEventSession": { "allOf": [ { "$ref": "#/components/schemas/SiteInsightsSession" }, { "type": "object", "description": "Analytics info on the GitBook's site session.", "properties": { "cookies": { "type": "object", "description": "The visitors cookies.", "additionalProperties": { "type": "string" } }, "ip": { "type": "string", "description": "IP address of the visitor.\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 }, "SiteMcpServerHeaders": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "HTTP headers sent with requests to this server" }, "SiteMcpServer": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site-mcp-server" ] }, "id": { "type": "string", "description": "Unique identifier for the MCP server" }, "name": { "$ref": "#/components/schemas/SiteMcpServerName" }, "url": { "$ref": "#/components/schemas/URL" }, "headers": { "$ref": "#/components/schemas/SiteMcpServerHeaders" }, "condition": { "description": "Conditional expression used to evaluate whether the MCP server should be available to the site's visitor.", "$ref": "#/components/schemas/Expression" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "location": { "type": "string", "description": "URL of the MCP server in the API", "format": "uri" } }, "required": [ "location" ] } }, "required": [ "object", "id", "name", "url", "headers", "urls" ] }, "GenericChannelPattern": { "type": "string", "description": "A generic channel name or pattern. For example, \"general\" or \"support-*\".", "pattern": "^[a-zA-Z0-9_\\*-]+$" }, "GitHubRepositoryPattern": { "type": "string", "description": "A GitHub repository name or pattern in the format \"owner/repository\". For example, \"my-org/my-repo\" or \"my-org/*\" to allow all repositories under \"my-org\".", "pattern": "^[a-zA-Z0-9._*-]+\\/[a-zA-Z0-9._*-]+$" }, "SiteChannelSetup": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "builtin:slack" ] }, "setupSettings": { "type": "object", "additionalProperties": false, "properties": { "allowedChannels": { "description": "List of allowed Slack channel names or patterns. If empty, all channels are allowed.", "type": "array", "items": { "$ref": "#/components/schemas/GenericChannelPattern" } } } } }, "required": [ "type", "setupSettings" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "builtin:linear" ] }, "setupSettings": { "type": "object", "additionalProperties": false, "properties": { "allowedTeams": { "description": "List of allowed Linear team keys or patterns. If empty, all teams are allowed.", "type": "array", "items": { "$ref": "#/components/schemas/GenericChannelPattern" } } } } }, "required": [ "type", "setupSettings" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "builtin:github" ] }, "setupSettings": { "type": "object", "additionalProperties": false, "properties": { "allowedRepositories": { "description": "List of allowed GitHub repository names or patterns. If empty, all repositories are allowed.", "type": "array", "items": { "$ref": "#/components/schemas/GitHubRepositoryPattern" } } } } }, "required": [ "type", "setupSettings" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "builtin:discord" ] }, "setupSettings": { "type": "object", "additionalProperties": false, "properties": { "allowedChannels": { "description": "List of allowed Discord channel names or patterns. If empty, all channels are allowed.", "type": "array", "items": { "$ref": "#/components/schemas/GenericChannelPattern" } } } } }, "required": [ "type", "setupSettings" ] } ] }, "SiteChannelStatus": { "type": "string", "enum": [ "active", "pending" ] }, "SiteChannelRole": { "type": "string", "enum": [ "collaborator", "support" ] }, "SiteChannel": { "allOf": [ { "$ref": "#/components/schemas/SiteChannelSetup" }, { "type": "object", "properties": { "object": { "type": "string", "enum": [ "site-channel" ] }, "id": { "type": "string", "description": "Unique identifier for the site channel." }, "status": { "$ref": "#/components/schemas/SiteChannelStatus" }, "role": { "$ref": "#/components/schemas/SiteChannelRole" }, "answers": { "type": "integer", "minimum": 0, "description": "Number of answers linked to this channel." }, "createdAt": { "$ref": "#/components/schemas/Timestamp" }, "urls": { "type": "object", "properties": { "location": { "type": "string", "format": "uri", "description": "URL of the site channel in the API." } }, "required": [ "location" ] } }, "required": [ "object", "id", "status", "role", "answers", "createdAt", "urls" ] } ] }, "Subdomain": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "subdomain" ] }, "subdomain": { "type": "string", "description": "The GitBook subdomain, for example \"my-company\" in \"my-company.gitbook.io\"", "pattern": "^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$", "minLength": 3, "maxLength": 32 }, "target": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationPointer" } ] }, "isActive": { "type": "boolean" } }, "required": [ "object", "subdomain", "target", "isActive" ] }, "CustomHostnameDnsStatus": { "type": "string", "enum": [ "dns_passed", "dns_wrong_cname", "dns_no_cname", "dns_cloudflare_proxied", "dns_wrong_caa" ] }, "CustomHostnameSslStatus": { "type": "string", "enum": [ "live", "ssl_unknown", "ssl_pending", "ssl_failed", "ssl_retry_expired" ] }, "CustomHostnameErrorStatus": { "type": "string", "enum": [ "invalid_domain", "internal_error" ] }, "CustomHostnameStatus": { "type": "string", "oneOf": [ { "$ref": "#/components/schemas/CustomHostnameDnsStatus" }, { "$ref": "#/components/schemas/CustomHostnameSslStatus" }, { "$ref": "#/components/schemas/CustomHostnameErrorStatus" } ] }, "CustomHostname": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "custom-hostname" ] }, "hostname": { "$ref": "#/components/schemas/SiteHostname" }, "target": { "oneOf": [ { "$ref": "#/components/schemas/OrganizationPointer" }, { "$ref": "#/components/schemas/SitePointer" } ] }, "isActive": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/CustomHostnameStatus" }, "urls": { "type": "object", "description": "URLs associated with the object", "properties": { "location": { "type": "string", "description": "URL of the custom hostname in the API", "format": "uri" } }, "required": [ "location" ] } }, "required": [ "object", "hostname", "target", "isActive", "urls" ] }, "UnsplashImage": { "type": "object", "required": [ "kind", "id", "description", "downloadLocation", "urls", "author" ], "properties": { "kind": { "type": "string", "enum": [ "unsplash_image" ] }, "id": { "type": "string" }, "description": { "type": "string" }, "downloadLocation": { "type": "string" }, "urls": { "type": "object", "properties": { "full": { "type": "string" }, "small": { "type": "string" } }, "required": [ "full", "small" ] }, "author": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] } } }, "HiveAccessToken": { "type": "object", "description": "JWT tokens to authenticate in Hive for all content.", "properties": { "contents": { "type": "object", "additionalProperties": { "description": "The Hive JWT access token.", "type": "string" } } }, "required": [ "contents" ] }, "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" }, "blockPaidOrg": { "type": "boolean" } }, "required": [ "block" ] }, "UserImpersonationInfo": { "type": "object", "description": "The GitBook User impersonation info.", "properties": { "authURL": { "type": "string" }, "impersonatorId": { "type": "string" } }, "required": [ "authURL", "impersonatorId" ] }, "UserImpersonation": { "type": "object", "description": "The info returned when impersonating a GitBook User.", "allOf": [ { "$ref": "#/components/schemas/UserBackOfficeInfo" }, { "type": "object", "properties": { "impersonation": { "$ref": "#/components/schemas/UserImpersonationInfo" } }, "required": [ "impersonation" ] } ] }, "UserOrganizationsTeamsPermissions": { "type": "object", "description": "The teams permissions of a user", "properties": { "role": { "$ref": "#/components/schemas/TeamMemberRole" } }, "required": [ "role" ] }, "UserOrganizationsPermissions": { "type": "object", "description": "The organizations permissions of a user", "properties": { "role": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "teams": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserOrganizationsTeamsPermissions" } }, "disabled": { "type": "boolean" } }, "required": [ "role", "teams" ] }, "UserCollectionsPermissions": { "type": "object", "description": "The collections permissions of a user", "properties": { "organization": { "type": "string" }, "level": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "collection": { "type": "string" } }, "required": [ "organization", "level" ] }, "UserSpacesPermissions": { "type": "object", "description": "The spaces permissions of a user", "properties": { "organization": { "type": "string" }, "level": { "$ref": "#/components/schemas/MemberRoleOrGuest" }, "collection": { "type": "string" } }, "required": [ "organization", "level" ] }, "_index": { "type": "object", "description": "All the permissions of a user", "properties": { "updatedAt": { "$ref": "#/components/schemas/Timestamp" }, "organizations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserOrganizationsPermissions" } }, "collections": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserCollectionsPermissions" } }, "spaces": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UserSpacesPermissions" } } }, "required": [ "updatedAt", "organizations", "collections", "spaces" ] }, "BackOfficeSite": { "allOf": [ { "$ref": "#/components/schemas/Site" }, { "type": "object", "properties": { "organization": { "type": "string", "description": "ID of the organization owning this site" } }, "required": [ "organization" ] } ] }, "PublishedContentRedirect": { "oneOf": [ { "type": "object", "title": "Redirect to the application or a different content in the site", "properties": { "target": { "type": "string", "description": "Type of target for the redirect", "enum": [ "application", "content" ] }, "redirect": { "$ref": "#/components/schemas/URL" } }, "required": [ "target", "redirect" ] }, { "type": "object", "title": "Redirect to an external resource from the site", "properties": { "target": { "type": "string", "description": "Type of target for the redirect", "enum": [ "external" ] }, "site": { "type": "string", "description": "ID of the resolved site." }, "redirect": { "$ref": "#/components/schemas/URL" } }, "required": [ "target", "site", "redirect" ] } ], "discriminator": { "propertyName": "target" } }, "PublishedSiteContent": { "type": "object", "title": "Site Content", "properties": { "site": { "type": "string", "description": "ID of the site matching." }, "siteSection": { "type": "string", "description": "ID of the site-section matching." }, "siteSpace": { "type": "string", "description": "ID of the site-space matching." }, "space": { "type": "string", "description": "ID of the space matching." }, "changeRequest": { "type": "string", "description": "Identifier of the change request being previewed in this URL." }, "revision": { "type": "string", "description": "Identifier of the revision being previewed in this URL." }, "pathname": { "type": "string", "description": "Path of the content relative to the input URL being resolved" }, "basePath": { "type": "string", "description": "Prefix of the path in the input URL being resolved" }, "siteBasePath": { "type": "string", "description": "Prefix of the site path in the input URL being resolved" }, "apiToken": { "type": "string", "description": "Short-lived API token to fetch content related to the space in the context of the URL." }, "organization": { "type": "string", "description": "ID of the organization." }, "shareKey": { "type": "string", "description": "Share link key of the site in case the site was published with share-links." }, "complete": { "type": "boolean", "description": "Whether the resolved site URL is complete and at it's terminal point, meaning no more site path segments can be further expected before any page path segments." }, "contextId": { "type": "string", "description": "Context returned only for a authenticated access session to track changes in the visitor session context that affect content rendering (used for cache invalidation)." }, "canonicalUrl": { "type": "string", "description": "The canonical URL of the resolution." }, "preview": { "type": "boolean", "description": "Whether the URL is a preview URL" } }, "required": [ "site", "siteSpace", "space", "pathname", "basePath", "siteBasePath", "apiToken", "organization", "complete", "canonicalUrl" ] }, "PublishedSiteContentLookup": { "oneOf": [ { "$ref": "#/components/schemas/PublishedContentRedirect" }, { "$ref": "#/components/schemas/PublishedSiteContent" } ] }, "SiteVisitorPayload": { "type": "object", "description": "An object that describes the payload of site visitor info. It can include a jwt token with signed claims and/or a record of its unsigned claims.", "properties": { "jwtToken": { "type": "string", "description": "JWT token generated for a authenticated access session." }, "unsignedClaims": { "$ref": "#/components/schemas/PlainObject" } } }, "GitSyncInstallationProvider": { "type": "string", "description": "The provider of the Git Sync installation.", "enum": [ "github", "gitlab" ] }, "GitSyncInstallationTarget": { "type": "object", "description": "Resource targeted by a Git Sync installation. Currently only spaces are supported.", "properties": { "spaceId": { "type": "string", "description": "Unique identifier of the space targeted by the Git Sync installation." } }, "required": [ "spaceId" ] }, "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" } } ] }, "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" ] } ] }, "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" ] }, "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" ] }, "SiteChannelType": { "oneOf": [ { "$ref": "#/components/schemas/SiteCoreChannelType" }, { "$ref": "#/components/schemas/SiteConfigurableChannelType" } ] }, "SiteQuestionAnswerSourceType": { "type": "string", "description": "Source type used to answer a site question.", "enum": [ "page", "record" ] }, "Seat": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "seat" ] }, "organization": { "description": "The unique ID of the organization", "type": "string" }, "member": { "description": "The unique ID of the organization member", "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "organization", "member", "createdAt", "updatedAt" ] }, "AgentStreamMessages": { "type": "object", "description": "Payload emitted by the agent to reset the messages.\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" ] }, "AgentState": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/AgentStatus" }, "suggestions": { "type": "array", "description": "A list of response suggestions for the user to select from.", "items": { "type": "string" } } }, "required": [ "status", "suggestions" ] }, "AgentStreamState": { "type": "object", "description": "Payload emitted by the agent with its current state.\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" ] } } } } } } } } }