diff --git a/tests/gitbook.json b/tests/gitbook.json index 5ffdd4d..2698462 100644 --- a/tests/gitbook.json +++ b/tests/gitbook.json @@ -97,14 +97,40 @@ "enum": ["document", "markdown"] } }, + "documentSchema": { + "name": "schema", + "in": "query", + "description": "Version of the schema used for the document.", + "schema": { + "type": "string", + "enum": ["current", "next"] + } + }, "commentStatus": { "name": "status", "in": "query", - "description": "When provided, only comments with the given status are returned. Only \"all\" is supported for now.", + "description": "When provided, only comments with the given status are returned. Defaults to \"all\".", "schema": { "type": "string", "default": "all", - "enum": ["all"] + "enum": ["all", "open", "resolved"] + } + }, + "commentTargetPage": { + "name": "targetPage", + "in": "query", + "description": "The target page of the comment", + "schema": { + "type": "string" + } + }, + "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 } }, "spaceId": { @@ -140,14 +166,7 @@ "required": true, "description": "The unique ID of the change request or its number identifier in the space", "schema": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ] + "type": "string" } }, "commentId": { @@ -172,7 +191,7 @@ "name": "integrationName", "in": "path", "required": true, - "description": "Name of the integration. Allowed characters are a-z, A-Z, 0-9, -, _, .", + "description": "Name of the integration.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", @@ -188,6 +207,24 @@ "type": "string" } }, + "siteId": { + "name": "siteId", + "in": "path", + "required": true, + "description": "The unique id of the site", + "schema": { + "type": "string" + } + }, + "siteSpaceId": { + "name": "siteSpaceId", + "in": "path", + "required": true, + "description": "The unique id of the site-space relationship", + "schema": { + "type": "string" + } + }, "organizationId": { "name": "organizationId", "in": "path", @@ -206,6 +243,24 @@ "type": "string" } }, + "snippetId": { + "name": "snippetId", + "in": "path", + "required": true, + "description": "The unique id of a snippet", + "schema": { + "type": "string" + } + }, + "syncedBlockId": { + "name": "syncedBlockId", + "in": "path", + "required": true, + "description": "The unique id of a synced block", + "schema": { + "type": "string" + } + }, "userId": { "name": "userId", "in": "path", @@ -233,6 +288,15 @@ "type": "string" } }, + "fileId": { + "name": "fileId", + "in": "path", + "required": true, + "description": "The unique id of the file", + "schema": { + "type": "string" + } + }, "pagePath": { "name": "pagePath", "in": "path", @@ -260,6 +324,51 @@ "$ref": "#/components/schemas/EntityType" } }, + "relationId": { + "name": "relationId", + "in": "path", + "required": true, + "description": "The id of the content audit relation", + "schema": { + "type": "string" + } + }, + "visitorId": { + "name": "visitorId", + "in": "path", + "required": true, + "description": "The id of the visitor", + "schema": { + "type": "string" + } + }, + "inviteId": { + "name": "inviteId", + "in": "path", + "required": true, + "description": "The unique id of the invite", + "schema": { + "type": "string" + } + }, + "shareLinkId": { + "name": "shareLinkId", + "in": "path", + "required": true, + "description": "The unique id of the share link", + "schema": { + "type": "string" + } + }, + "hostname": { + "name": "hostname", + "in": "path", + "required": true, + "description": "The custom hostname, for example \"docs.gitbook.com\"", + "schema": { + "type": "string" + } + }, "backofficeHostname": { "name": "hostname", "in": "path", @@ -268,6 +377,15 @@ "schema": { "type": "string" } + }, + "ifUnmodifiedSince": { + "in": "header", + "name": "If-Unmodified-Since", + "description": "If provided, the operation will be rejected if the underlying resource has been modified since the date provided in the header.", + "schema": { + "type": "string", + "format": "date-time" + } } }, "schemas": { @@ -313,13 +431,17 @@ "type": "string", "format": "uri" }, - "Date": { + "Color": { + "type": "string", + "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$" + }, + "Timestamp": { "type": "string", - "format": "date" + "format": "date-time" }, "Emoji": { "type": "string", - "maxLength": 20, + "maxLength": 50, "description": "Unicode codepoint or character of the emoji", "example": "🎉" }, @@ -345,7 +467,7 @@ "$ref": "#/components/schemas/User" }, "reactedAt": { - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" } }, "required": ["user", "reactedAt"] @@ -382,9 +504,17 @@ "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." + "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"] @@ -398,7 +528,7 @@ "description": "The URL of referrer that linked to the page." } }, - "required": ["pageId", "visitor", "url", "referrer"] + "required": ["visitor", "url", "referrer"] }, "RequestPublishIntegration": { "type": "object", @@ -486,6 +616,28 @@ } } }, + "RequestUpdateIntegrationSpaceInstallation": { + "type": "object", + "properties": { + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + }, + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + } + } + }, + "RequestUpdateIntegrationSiteInstallation": { + "type": "object", + "properties": { + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + }, + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + } + } + }, "RequestUpgradeOrganizationBilling": { "type": "object", "properties": { @@ -572,6 +724,10 @@ "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" }, @@ -586,6 +742,65 @@ }, "required": ["url", "ref"] }, + "RequestSyncGitRepository": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "description": "Git ref in the format \"refs/heads/main\"" + }, + "repoURL": { + "type": "string", + "description": "URL of the Git repository used for synchronization. It can contain basic auth credentials." + }, + "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." + }, + "commitMessageTemplate": { + "type": "string", + "description": "Template message for the commit generated during the synchronization." + }, + "standalone": { + "type": "boolean", + "description": "If true, the synchronization of the ref will generate a revision without updating the space primary content." + }, + "force": { + "type": "object", + "description": "Whether to force the synchronization", + "properties": { + "priority": { + "type": "string", + "enum": ["gitbook", "git"] + } + }, + "required": ["priority"] + }, + "timestamp": { + "description": "The timestamp of the event. It ensures the synchronize operations are executed in the same order on GitBook and on the remote repository.\n", + "$ref": "#/components/schemas/Timestamp" + }, + "gitInfo": { + "description": "Optional metadata to store on the space about the Git provider", + "$ref": "#/components/schemas/RequestUpdateSpaceGitInfo" + } + }, + "required": [ + "ref", + "repoURL", + "repoTreeURL", + "repoCommitURL", + "commitMessageTemplate" + ] + }, "RequestExportToGitRepository": { "type": "object", "properties": { @@ -617,6 +832,10 @@ "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" }, @@ -737,6 +956,57 @@ } } }, + "CreateOrganizationInvite": { + "oneOf": [ + { + "$ref": "#/components/schemas/CreateInviteToOrganization" + }, + { + "$ref": "#/components/schemas/CreateInviteToSpace" + }, + { + "$ref": "#/components/schemas/CreateInviteToCollection" + } + ] + }, + "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"] + }, + "CreateInviteToOrganization": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The role of the member in the organization" + } + }, + "required": ["role"] + }, "ApiInformation": { "type": "object", "properties": { @@ -751,6 +1021,16 @@ }, "required": ["version", "build"] }, + "BlockContext": { + "type": "object", + "description": "The context to send when blocking/unblocking", + "properties": { + "block": { + "type": "boolean" + } + }, + "required": ["block"] + }, "RequestPurgeCDNCacheContext": { "type": "object", "description": "The context to send when purging the CDN Cache", @@ -768,16 +1048,6 @@ }, "required": ["type", "values"] }, - "RequestBlockUserContext": { - "type": "object", - "description": "The context to send when blocking/unblocking a user", - "properties": { - "block": { - "type": "boolean" - } - }, - "required": ["block"] - }, "TriggerContentIndexingContext": { "type": "object", "description": "The context to send when triggering a content indexing.", @@ -826,7 +1096,8 @@ "description": "URL of the user in the API", "format": "uri" } - } + }, + "required": ["location"] } }, "required": ["object", "id", "displayName", "urls"] @@ -844,7 +1115,7 @@ "description": "The API token name." }, "createdAt": { - "$ref": "#/components/schemas/Date", + "$ref": "#/components/schemas/Timestamp", "description": "The API token creation date." } }, @@ -900,7 +1171,7 @@ "description": "Contributor towards content.", "properties": { "updatedAt": { - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" }, "count": { "type": "integer" @@ -974,6 +1245,7 @@ "oneOf": [ { "type": "object", + "title": "Link", "properties": { "type": { "type": "string", @@ -984,6 +1256,7 @@ }, { "type": "object", + "title": "HTML", "properties": { "type": { "type": "string", @@ -1019,11 +1292,11 @@ }, "postedAt": { "description": "When the comment was posted.", - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" }, "editedAt": { "description": "Date when the comment was edited, if it has been edited.", - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" }, "reactions": { "description": "Any emoji reactions to the comment.", @@ -1051,7 +1324,8 @@ "preview": { "type": "string" } - } + }, + "required": ["id"] }, "changeRequest": { "description": "The change request containing this comment, if the comment was made inside a change request.", @@ -1123,6 +1397,7 @@ "oneOf": [ { "type": "object", + "title": "Resolved", "properties": { "status": { "description": "Status of the comment.", @@ -1131,7 +1406,7 @@ }, "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/Date" + "$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.", @@ -1142,6 +1417,7 @@ }, { "type": "object", + "title": "Open", "properties": { "status": { "description": "Status of the comment.", @@ -1171,11 +1447,11 @@ "$ref": "#/components/schemas/User" }, "postedAt": { - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" }, "editedAt": { "description": "Date when the reply was edited, if it has been edited.", - "$ref": "#/components/schemas/Date" + "$ref": "#/components/schemas/Timestamp" }, "reactions": { "$ref": "#/components/schemas/EmojiReactions" @@ -1198,2372 +1474,2480 @@ }, "required": ["object", "id", "body", "postedBy", "postedAt", "reactions", "urls"] }, - "Document": { + "PublishedContentLookup": { "oneOf": [ { - "$ref": "#/components/schemas/MarkdownDocument" - }, - { - "$ref": "#/components/schemas/JSONDocument" + "type": "object", + "title": "Redirect", + "properties": { + "target": { + "type": "string", + "description": "Type of target for the redirect", + "enum": ["application", "content", "external"] + }, + "redirect": { + "$ref": "#/components/schemas/URL" + } + }, + "required": ["target", "redirect"] }, { "type": "object", - "properties": {}, - "additionalProperties": false + "title": "Content", + "properties": { + "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 space" + }, + "basePath": { + "type": "string", + "description": "Prefix of the path in the URL dedicated to the space" + }, + "apiToken": { + "type": "string", + "description": "Short-lived API token to fetch content related to the space in the context of the URL." + } + }, + "required": ["space", "pathname", "basePath", "apiToken"] } ] }, - "MarkdownDocument": { + "SpacePointer": { "type": "object", "properties": { - "markdown": { + "type": { "type": "string", - "description": "Content of the document formatted as markdown" + "enum": ["space"] + }, + "space": { + "type": "string", + "description": "Unique identifier for the space" } }, - "required": ["markdown"] + "required": ["type", "space"] }, - "JSONDocument": { + "CollectionPointer": { "type": "object", "properties": { - "document": { - "type": "object", - "properties": { - "nodes": { - "type": "array", - "items": { - "type": "object", - "properties": {} - } - } - }, - "required": ["nodes"] - } - }, - "required": ["document"] - }, - "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": { - "type": "string", - "description": "Title of the space", - "minLength": 0, - "maxLength": 100 - }, - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" - }, - "createdAt": { - "$ref": "#/components/schemas/Date" - }, - "updatedAt": { - "$ref": "#/components/schemas/Date" - }, - "deletedAt": { - "$ref": "#/components/schemas/Date" - }, - "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" - } - }, - "required": ["app", "location"] - }, - "organization": { + "type": { "type": "string", - "description": "ID of the organization owning this space" + "enum": ["collection"] }, - "parent": { + "collection": { "type": "string", - "description": "ID of the parent collection." + "description": "Unique identifier for the collection" } }, - "required": [ - "object", - "id", - "type", - "title", - "organization", - "visibility", - "createdAt", - "updatedAt", - "urls" - ] + "required": ["type", "collection"] }, - "RevisionBase": { + "ContentPosition": { "type": "object", + "description": "Position at which to insert an item", "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" - } - }, - "git": { - "type": "object", - "description": "Metadata about a potential associated git commit.", - "required": ["oid", "message", "createdByGitBook"], - "properties": { - "oid": { - "type": "string", - "description": "SHA of the Git commit." - }, - "message": { - "type": "string", - "description": "Git commit message." - }, - "createdByGitBook": { - "type": "boolean", - "description": "Whether not this commit was created by GitBook, while exporting the revision." + "before": { + "oneOf": [ + { + "$ref": "#/components/schemas/SpacePointer" }, - "url": { - "type": "string", - "description": "URL of the Git commit." + { + "$ref": "#/components/schemas/CollectionPointer" } - } + ] }, - "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" + "after": { + "oneOf": [ + { + "$ref": "#/components/schemas/SpacePointer" }, - "public": { - "type": "string", - "description": "URL of the public version of the revision. Only defined when the space visibility is \"public\".", - "format": "uri" + { + "$ref": "#/components/schemas/CollectionPointer" } - }, - "required": ["app"] + ] } - }, - "required": ["object", "id", "parents", "pages", "files", "urls"] + } }, - "RevisionTypeMerge": { - "allOf": [ + "DefaultLevel": { + "description": "Default level for a piece of content", + "oneOf": [ { - "$ref": "#/components/schemas/RevisionBase" + "$ref": "#/components/schemas/MemberRoleOrGuest" }, { - "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"] + "type": "string", + "enum": ["inherit"] } ] }, - "RevisionTypeRollback": { - "allOf": [ + "Document": { + "oneOf": [ { - "$ref": "#/components/schemas/RevisionBase" + "$ref": "#/components/schemas/MarkdownDocument", + "title": "Markdown" }, { "type": "object", + "title": "JSON Document", "properties": { - "type": { - "type": "string", - "description": "Revision created as a rollback of a previous revision.", - "enum": ["rollback"] + "document": { + "$ref": "#/components/schemas/JSONDocument" } }, - "required": ["type"] - } - ] - }, - "RevisionTypeUpdate": { - "allOf": [ - { - "$ref": "#/components/schemas/RevisionBase" + "required": ["document"] }, { "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Revision created when updating a change request with changes from primary.", - "enum": ["update"] - } - }, - "required": ["type"] + "title": "Empty", + "properties": {}, + "additionalProperties": false } ] }, - "RevisionTypeEdits": { - "allOf": [ - { - "$ref": "#/components/schemas/RevisionBase" + "MarkdownDocument": { + "type": "object", + "properties": { + "markdown": { + "type": "string", + "description": "Content of the document formatted as markdown" + } + }, + "required": ["markdown"] + }, + "JSONDocument": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["document"] }, - { + "data": { "type": "object", "properties": { - "type": { - "type": "string", - "description": "Revision created by editing the content.", - "enum": ["edits"] + "schemaVersion": { + "description": "The schema version of the document. If undefined, the document is considered to be of the latest schema version.", + "type": "integer" } }, - "required": ["type"] + "additionalProperties": true + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksTopLevels" + } } - ] + }, + "required": ["object", "data", "nodes"] }, - "Revision": { + "DocumentBlock": { "oneOf": [ { - "$ref": "#/components/schemas/RevisionTypeEdits" + "$ref": "#/components/schemas/DocumentBlockParagraph" }, { - "$ref": "#/components/schemas/RevisionTypeMerge" + "$ref": "#/components/schemas/DocumentBlockHeading" }, { - "$ref": "#/components/schemas/RevisionTypeRollback" + "$ref": "#/components/schemas/DocumentBlockListOrdered" }, { - "$ref": "#/components/schemas/RevisionTypeUpdate" - } - ], - "discriminator": { - "propertyName": "type" - } - }, - "RevisionPage": { - "oneOf": [ + "$ref": "#/components/schemas/DocumentBlockListUnordered" + }, { - "$ref": "#/components/schemas/RevisionPageDocument" + "$ref": "#/components/schemas/DocumentBlockListTasks" }, { - "$ref": "#/components/schemas/RevisionPageGroup" + "$ref": "#/components/schemas/DocumentBlockListItem" }, { - "$ref": "#/components/schemas/RevisionPageLink" - } - ], - "discriminator": { - "propertyName": "type" - } - }, - "RevisionPageBase": { - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for the page in the revision", - "type": "string" + "$ref": "#/components/schemas/DocumentBlockDivider" }, - "title": { - "description": "Title of the page", - "type": "string", - "maxLength": 100 - } - }, - "required": ["id", "title"] - }, - "RevisionPageDocument": { - "allOf": [ { - "$ref": "#/components/schemas/RevisionPageBase" + "$ref": "#/components/schemas/DocumentBlockQuote" }, { - "$ref": "#/components/schemas/Document" + "$ref": "#/components/schemas/DocumentBlockHint" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "deprecated": true, - "enum": ["sheet"] - }, - "type": { - "type": "string", - "enum": ["document"] - }, - "slug": { - "description": "Page's slug in its direct parent", - "type": "string" - }, - "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" - } - ] - } - } - }, - "required": ["kind", "type", "slug", "path", "pages"] - } - ] - }, - "RevisionPageGroup": { - "allOf": [ + "$ref": "#/components/schemas/DocumentBlockImages" + }, { - "$ref": "#/components/schemas/RevisionPageBase" + "$ref": "#/components/schemas/DocumentBlockImage" }, { - "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" - }, - "pages": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageLink" - } - ] - } - } - }, - "required": ["kind", "type", "slug", "path", "pages"] + "$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/DocumentBlockSwagger" + }, + { + "$ref": "#/components/schemas/DocumentBlockContentRef" + }, + { + "$ref": "#/components/schemas/DocumentBlockIntegration" + }, + { + "$ref": "#/components/schemas/DocumentBlockSyncedBlock" } ] }, - "RevisionPageLink": { - "allOf": [ + "DocumentInline": { + "oneOf": [ { - "$ref": "#/components/schemas/RevisionPageBase" + "$ref": "#/components/schemas/DocumentInlineLink" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "deprecated": true, - "enum": ["link"] - }, - "type": { - "type": "string", - "enum": ["link"] - }, - "href": { - "type": "string" - } - }, - "required": ["kind", "type"] + "$ref": "#/components/schemas/DocumentInlineEmoji" + }, + { + "$ref": "#/components/schemas/DocumentInlineMath" + }, + { + "$ref": "#/components/schemas/DocumentInlineImage" + }, + { + "$ref": "#/components/schemas/DocumentInlineAnnotation" + }, + { + "$ref": "#/components/schemas/DocumentInlineMention" } ] }, - "RevisionFile": { + "DocumentText": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" + "object": { + "type": "string", + "enum": ["text"] }, - "contentType": { + "key": { "type": "string" }, - "downloadURL": { - "type": "string" + "leaves": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTextLeaf" + } } }, - "required": ["id", "name", "contentType", "downloadURL"] - }, - "ImportContentSource": { - "type": "string", - "enum": [ - "website", - "docx", - "markdown", - "html", - "zip", - "confluence", - "github-wiki", - "dropbox-paper", - "notion", - "quip", - "google-docs", - "open-api" - ] + "required": ["object", "leaves"] }, - "GitSyncState": { + "DocumentFragment": { "type": "object", "properties": { - "installationProvider": { + "object": { "type": "string", - "description": "The provider of the Git Sync installation." + "enum": ["fragment"] }, - "operation": { - "$ref": "#/components/schemas/GitSyncOperation" + "key": { + "type": "string" }, - "url": { - "type": "string", - "description": "The URL to the repository tree, used when rendering public content." + "fragment": { + "type": "string" }, - "updatedAt": { - "description": "When the Git provider details were last updated", - "$ref": "#/components/schemas/Date" + "type": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + } } - } + }, + "required": ["object", "nodes"] }, - "GitSyncOperation": { - "type": "object", - "properties": { - "state": { - "$ref": "#/components/schemas/GitSyncOperationState" + "DocumentBlocksEssentials": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockParagraph" }, - "startedAt": { - "$ref": "#/components/schemas/Date" + { + "$ref": "#/components/schemas/DocumentBlockHeading" }, - "completedAt": { - "description": "Date when the operation was successful (when state is `success`)", - "$ref": "#/components/schemas/Date" + { + "$ref": "#/components/schemas/DocumentBlockListOrdered" }, - "error": { - "type": "string", - "description": "Error details, defined if state is `failure`." + { + "$ref": "#/components/schemas/DocumentBlockListUnordered" + }, + { + "$ref": "#/components/schemas/DocumentBlockListTasks" + }, + { + "$ref": "#/components/schemas/DocumentBlockDivider" } - }, - "required": ["state", "startedAt"] - }, - "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"] + ] }, - "Organization": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"organization\"", - "enum": ["organization"] + "DocumentBlocksTopLevels": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlocksEssentials" }, - "id": { - "type": "string", - "description": "Unique identifier for the organization" + { + "$ref": "#/components/schemas/DocumentBlockQuote" }, - "title": { - "$ref": "#/components/schemas/OrganizationTitle" + { + "$ref": "#/components/schemas/DocumentBlockHint" }, - "emailDomains": { - "$ref": "#/components/schemas/OrganizationEmailDomains" + { + "$ref": "#/components/schemas/DocumentBlockImages" }, - "type": { - "$ref": "#/components/schemas/OrganizationType" + { + "$ref": "#/components/schemas/DocumentBlockFile" }, - "useCase": { - "$ref": "#/components/schemas/OrganizationUseCase" + { + "$ref": "#/components/schemas/DocumentBlockDrawing" }, - "communityType": { - "$ref": "#/components/schemas/OrganizationCommunityType" + { + "$ref": "#/components/schemas/DocumentBlockEmbed" }, - "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" - } - }, - "required": ["app", "location"] - } - }, - "required": ["object", "id", "title", "type", "emailDomains", "urls"] - }, - "OrganizationType": { - "type": "string", - "enum": ["business", "community"] - }, - "OrganizationTitle": { - "type": "string", - "description": "Name of the organization", - "minLength": 2, - "maxLength": 300 - }, - "OrganizationEmailDomains": { - "type": "array", - "items": { - "type": "string" - } - }, - "OrganizationUseCase": { - "type": "string", - "enum": [ - "productDocs", - "teamKnowledgeBase", - "designSystem", - "openSourceDocs", - "notes", - "other" - ] - }, - "OrganizationCommunityType": { - "type": "string", - "enum": ["nonProfit", "openSource", "education"] - }, - "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" + "$ref": "#/components/schemas/DocumentBlockCode" }, { - "type": "string", - "nullable": true, - "enum": [null] + "$ref": "#/components/schemas/DocumentBlockMath" + }, + { + "$ref": "#/components/schemas/DocumentBlockExpandable" + }, + { + "$ref": "#/components/schemas/DocumentBlockTabs" + }, + { + "$ref": "#/components/schemas/DocumentBlockTable" + }, + { + "$ref": "#/components/schemas/DocumentBlockSwagger" + }, + { + "$ref": "#/components/schemas/DocumentBlockContentRef" + }, + { + "$ref": "#/components/schemas/DocumentBlockIntegration" + }, + { + "$ref": "#/components/schemas/DocumentBlockSyncedBlock" } ] }, - "OrganizationTransferResponse": { + "DocumentTextLeaf": { "type": "object", - "required": ["collection"], "properties": { - "collection": { + "object": { "type": "string", - "description": "The unique id of the collection created in the target organization containing the content of the source organization." + "enum": ["leaf"] }, - "newSourceHostname": { - "type": "string", - "description": "The new hostname if the source organization needed to change hostname." + "text": { + "type": "string" + }, + "marks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTextMark" + } } - } + }, + "required": ["object", "text", "marks"] }, - "OrganizationDirectorySyncGroup": { + "DocumentMarkBold": { "type": "object", - "required": ["id", "idp_id", "directory_id", "name"], "properties": { - "id": { + "object": { "type": "string", - "description": "The unique identifier of this group in WorkOS. Not the unique ID from GitBook." + "enum": ["mark"] }, - "idp_id": { + "type": { + "type": "string", + "enum": ["bold"] + } + }, + "required": ["object", "type"] + }, + "DocumentMarkItalic": { + "type": "object", + "properties": { + "object": { "type": "string", - "description": "The identity provider's unique ID for this group, should be used to generate the team's unique ID when syncing the groups." + "enum": ["mark"] }, - "directory_id": { + "type": { + "type": "string", + "enum": ["italic"] + } + }, + "required": ["object", "type"] + }, + "DocumentMarkCode": { + "type": "object", + "properties": { + "object": { "type": "string", - "description": "The unique ID of the directory this group is owned by in WorkOS. Is not a unique ID from our database." + "enum": ["mark"] }, - "name": { + "type": { + "type": "string", + "enum": ["code"] + } + }, + "required": ["object", "type"] + }, + "DocumentMarkStrikethrough": { + "type": "object", + "properties": { + "object": { "type": "string", - "description": "The name of the group from the identity provider, it should always be set according to the WorkOS documentation." + "enum": ["mark"] }, - "teamKey": { + "type": { "type": "string", - "description": "The unique ID of the GitBook team already synced to this group, if applicable." + "enum": ["strikethrough"] } - } + }, + "required": ["object", "type"] }, - "OrganizationDirectorySyncGroupTeamStatus": { - "anyOf": [ - { + "DocumentMarkColor": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["mark"] + }, + "type": { + "type": "string", + "enum": ["color"] + }, + "data": { "type": "object", - "required": ["success", "group_id", "team_id"], "properties": { - "success": { - "type": "boolean", - "enum": [true] - }, - "group_id": { - "type": "string" + "text": { + "type": "string", + "enum": [ + "default", + "green", + "blue", + "red", + "orange", + "yellow", + "purple" + ] }, - "team_id": { - "type": "string" + "background": { + "type": "string", + "enum": [ + "default", + "green", + "blue", + "red", + "orange", + "yellow", + "purple" + ] } - } + }, + "required": ["text", "background"] + } + }, + "required": ["object", "type", "data"] + }, + "DocumentTextMark": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentMarkBold" }, { - "type": "object", - "required": ["success", "error"], - "properties": { - "success": { - "type": "boolean", - "enum": [false] - }, - "error": { - "type": "string" - } - } + "$ref": "#/components/schemas/DocumentMarkItalic" + }, + { + "$ref": "#/components/schemas/DocumentMarkCode" + }, + { + "$ref": "#/components/schemas/DocumentMarkStrikethrough" + }, + { + "$ref": "#/components/schemas/DocumentMarkColor" } ] }, - "OrganizationTarget": { + "DocumentInlineLink": { "type": "object", - "required": ["organization"], "properties": { - "organization": { + "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"] }, - "OrganizationMember": { + "DocumentInlineMath": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of Object, always equals to \"member\"", - "enum": ["member"] + "enum": ["inline"] }, - "id": { + "type": { "type": "string", - "description": "Unique identifier for the user." + "enum": ["inline-math"] }, - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest" + "key": { + "type": "string" }, - "user": { - "$ref": "#/components/schemas/User" + "data": { + "type": "object", + "properties": { + "formula": { + "type": "string" + } + }, + "required": ["formula"] }, - "disabled": { + "isVoid": { "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/Date" + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentInlineEmoji": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["inline"] }, - "lastSeenAt": { - "description": "Date at which the user was last seen active in the organization.", - "$ref": "#/components/schemas/Date" + "type": { + "type": "string", + "enum": ["emoji"] }, - "sso": { - "type": "boolean", - "description": "Whether the user can login with SSO." + "key": { + "type": "string" }, - "spaces": { - "type": "number" + "data": { + "type": "object", + "properties": { + "code": { + "type": "string" + } + }, + "required": ["code"] }, - "teams": { - "type": "number" + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": [ - "object", - "id", - "role", - "user", - "disabled", - "joinedAt", - "sso", - "spaces", - "teams" - ] + "required": ["object", "type", "data", "isVoid"] }, - "OrganizationTeam": { + "DocumentInlineImage": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of Object, always equals to \"team\"", - "enum": ["team"] + "enum": ["inline"] }, - "id": { + "type": { "type": "string", - "description": "Unique identifier for the team." + "enum": ["inline-image"] }, - "title": { - "type": "string", - "description": "Title of the team." - }, - "members": { - "type": "integer", - "description": "Count of members in this team." + "key": { + "type": "string" }, - "spaces": { - "type": "number", - "description": "Count of spaces this team has access to." + "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" + }, + "size": { + "type": "string", + "enum": ["original", "line"] + } + }, + "required": ["ref"] }, - "createdAt": { - "description": "Date at which the team was created.", - "$ref": "#/components/schemas/Date" + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["object", "id", "title", "members", "spaces", "createdAt"] + "required": ["object", "type", "data", "isVoid"] }, - "TeamMember": { + "DocumentInlineMention": { "type": "object", "properties": { - "role": { - "$ref": "#/components/schemas/TeamMemberRole" + "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": ["role"] - }, - "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"] + "required": ["object", "type", "data", "isVoid"] }, - "OrganizationTeamMember": { + "DocumentInlineAnnotation": { "type": "object", - "description": "A member of a team in an organization, including its relationship to it", "properties": { - "organization": { - "$ref": "#/components/schemas/OrganizationMember" + "object": { + "type": "string", + "enum": ["inline"] }, - "team": { - "$ref": "#/components/schemas/TeamMember" + "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": ["organization", "team"] + "required": ["object", "type", "fragments", "isVoid", "nodes"] }, - "Capture": { + "DocumentBlockParagraph": { "type": "object", "properties": { - "id": { + "object": { "type": "string", - "description": "Unique identifier for the capture" + "enum": ["block"] }, - "title": { - "$ref": "#/components/schemas/CaptureTitle" + "type": { + "type": "string", + "enum": ["paragraph"] }, - "context": { - "$ref": "#/components/schemas/CaptureContext" + "key": { + "type": "string" }, - "externalId": { - "type": "string", - "description": "ID in the original source of the capture." + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentInline" + }, + { + "$ref": "#/components/schemas/DocumentText" + } + ] + } }, - "externalURL": { - "type": "string", - "format": "uri", - "description": "URL of the source from which the capture originated" + "isVoid": { + "type": "boolean", + "enum": [false] }, - "createdAt": { + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false + } + }, + "required": ["object", "type", "nodes"] + }, + "DocumentBlockHeading": { + "type": "object", + "properties": { + "object": { "type": "string", - "format": "date-time" + "enum": ["block"] }, - "stoppedAt": { + "type": { "type": "string", - "format": "date-time" + "enum": ["heading-1", "heading-2", "heading-3"] }, - "events": { - "description": "Count of events recorded.", - "properties": { - "terminal.command": { - "type": "integer" - }, - "speech": { - "type": "integer" - }, - "thread.message": { - "type": "integer" - } - } + "key": { + "type": "string" }, - "contributors": { - "description": "An array of contributors to the capture. The first contributor is the one who triggered the capture (either a user or an integration).", + "nodes": { "type": "array", - "minItems": 1, "items": { "oneOf": [ { - "$ref": "#/components/schemas/Integration" + "$ref": "#/components/schemas/DocumentInline" }, { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/DocumentText" } ] } }, - "output": { - "description": "Output document for the capture. Is not set when capture is not finished.", - "$ref": "#/components/schemas/Document" - }, - "urls": { + "data": { "type": "object", - "description": "URLs associated with the object", "properties": { - "location": { - "type": "string", - "description": "URL of the capture in the API", - "format": "uri" - }, - "app": { + "id": { "type": "string", - "description": "URL of the capture in the app", - "format": "uri" + "pattern": "^[-a-z0-9.+_]+$" + } + } + }, + "meta": { + "type": "object", + "properties": { + "id": { + "description": "Unique ID to be used in an URL for the block.", + "type": "string" } }, - "required": ["location", "app"] + "required": ["id"] + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": [ - "object", - "id", - "title", - "context", - "events", - "createdAt", - "contributors", - "urls" - ] - }, - "CaptureTitle": { - "type": "string", - "description": "Optional title describing the capture", - "maxLength": 100 + "required": ["object", "type", "nodes", "data"] }, - "CaptureEvent": { - "oneOf": [ - { - "$ref": "#/components/schemas/CaptureTerminalCommandEvent" + "DocumentBlockQuote": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - { - "$ref": "#/components/schemas/CaptureSpeechEvent" + "type": { + "type": "string", + "enum": ["blockquote"] }, - { - "$ref": "#/components/schemas/CaptureThreadMessageEvent" + "key": { + "type": "string" }, - { - "$ref": "#/components/schemas/CaptureFileAddedEvent" + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + }, + { + "$ref": "#/components/schemas/DocumentBlockQuote" + } + ] + } }, - { - "$ref": "#/components/schemas/CaptureFileChangedEvent" + "isVoid": { + "type": "boolean", + "enum": [false] }, - { - "$ref": "#/components/schemas/CaptureFileRemovedEvent" - } - ] - }, - "CaptureContext": { - "oneOf": [ - { - "type": "string", - "enum": ["meeting", "thread", "walkthrough"] + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } - ] + }, + "required": ["object", "type", "nodes"] }, - "BaseCaptureEvent": { + "DocumentBlockHint": { "type": "object", "properties": { - "type": { + "object": { "type": "string", - "description": "The type of event" + "enum": ["block"] }, - "timestamp": { + "type": { "type": "string", - "format": "date-time", - "description": "When the event happened" + "enum": ["hint"] }, - "source": { - "type": "string", - "description": "Optionally, provide the source of the event. GitBook may use this to improve the generated content.", - "maxLength": 50 + "key": { + "type": "string" }, - "actor": { + "data": { "type": "object", - "description": "Optionally, provide the actor of the event, in the context of multiple people contributing to the capture.", "properties": { - "name": { - "type": "string" + "style": { + "type": "string", + "enum": ["info", "warning", "danger", "success"] } }, - "required": ["name"] + "required": ["style"] + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["type", "timestamp"] + "required": ["object", "type", "data", "nodes"] }, - "CaptureSpeechEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + "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", - "properties": { - "type": { - "type": "string", - "enum": ["speech"] - } - }, - "required": ["type"] + "additionalProperties": false }, - { - "oneOf": [ - { - "type": "object", - "properties": { - "audio": { - "description": "WAV audio file, encoded as base64", - "type": "string" - } - }, - "required": ["audio"] - }, - { - "type": "object", - "properties": { - "transcript": { - "description": "Transcript of the speech", - "type": "string" - } - }, - "required": ["transcript"] - } - ] + "isVoid": { + "type": "boolean", + "enum": [false] } - ] + }, + "required": ["object", "type", "nodes"] }, - "CaptureTerminalCommandEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + "DocumentBlockListOrdered": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - { + "type": { + "type": "string", + "enum": ["list-ordered"] + }, + "key": { + "type": "string" + }, + "data": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": ["terminal.command"] - }, - "command": { - "type": "string" - }, - "stdout": { - "type": "string" + "start": { + "type": "number", + "description": "An integer to start counting from for the list items." } - }, - "required": ["type", "command", "stdout"] + } + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockListItem" + } + ] + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } - ] + }, + "required": ["object", "type", "data", "nodes"] }, - "CaptureThreadMessageEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + "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": { - "type": { - "type": "string", - "enum": ["thread.message"] - }, - "isFirst": { - "type": "boolean" - }, - "text": { - "type": "string" - } - }, - "required": ["type", "text"] + "properties": {}, + "additionalProperties": false } - ] + }, + "required": ["object", "type", "nodes"] }, - "CaptureFileAddedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + "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": { - "type": { - "type": "string", - "enum": ["file.added"] - }, - "filename": { - "type": "string" - }, - "fileSnapshot": { - "type": "string" + "checked": { + "type": "boolean" } - }, - "required": ["type", "filename", "fileSnapshot"] + } } - ] + }, + "required": ["object", "type", "nodes"] }, - "CaptureFileChangedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + "DocumentBlockImages": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - { + "type": { + "type": "string", + "enum": ["images"] + }, + "key": { + "type": "string" + }, + "data": { "type": "object", "properties": { - "type": { + "align": { "type": "string", - "enum": ["file.changed"] - }, - "filename": { - "type": "string" + "enum": ["center", "left", "right"] }, - "fileDiff": { - "type": "string" + "fullWidth": { + "type": "boolean" } - }, - "required": ["type", "filename", "fileDiff"] + } + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockImage" + } + }, + "isVoid": { + "type": "boolean", + "enum": [true] } - ] + }, + "required": ["object", "type", "data", "nodes", "isVoid"] }, - "CaptureFileRemovedEvent": { - "allOf": [ + "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/DocumentBlockImageDimension" + }, + "height": { + "$ref": "#/components/schemas/DocumentBlockImageDimension" + }, + "alt": { + "type": "string" + } + }, + "required": ["ref"] + }, + "fragments": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentFragment" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["caption"] + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockParagraph" + } + } + }, + "required": ["nodes", "type"] + } + ] + } + }, + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "fragments", "isVoid"] + }, + "DocumentBlockImageDimension": { + "oneOf": [ { - "$ref": "#/components/schemas/BaseCaptureEvent" + "type": "number" }, { "type": "object", "properties": { - "type": { - "type": "string", - "enum": ["file.removed"] - }, - "filename": { + "unit": { "type": "string" }, - "fileSnapshot": { - "type": "string" + "value": { + "type": "number" } }, - "required": ["type", "filename", "fileSnapshot"] + "required": ["unit", "value"] } ] }, - "ChangeRequest": { + "DocumentBlockFile": { "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" + "enum": ["block"] }, - "subject": { + "type": { "type": "string", - "description": "Subject of the change request", - "minLength": 0, - "maxLength": 100 - }, - "createdBy": { - "$ref": "#/components/schemas/User" - }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "enum": ["file"] }, - "updatedAt": { - "$ref": "#/components/schemas/Date" + "key": { + "type": "string" }, - "urls": { + "data": { "type": "object", - "description": "URLs associated with the object", "properties": { - "app": { - "type": "string", - "description": "URL of the space in the application", - "format": "uri" + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] } }, - "required": ["app"] + "required": ["ref"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": [ - "object", - "id", - "number", - "status", - "subject", - "createdBy", - "createdAt", - "updatedAt", - "urls" - ] - }, - "ChangeRequestStatus": { - "type": "string", - "enum": ["draft", "open", "archived", "merged"] + "required": ["object", "type", "data", "isVoid"] }, - "ChangeRequestReview": { + "DocumentBlockDrawing": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of Object, always equals to \"change-request-review\"", - "enum": ["change-request-review"] + "enum": ["block"] }, - "id": { + "type": { "type": "string", - "description": "Unique identifier for the review." + "enum": ["drawing"] }, - "revision": { - "type": "string", - "description": "The revision this review was made against." + "key": { + "type": "string" }, - "reviewer": { - "description": "The user who performed the review.", - "$ref": "#/components/schemas/User" + "data": { + "type": "object", + "properties": { + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] + } + } }, - "requestedBy": { - "description": "The user who requested the review. If undefined, the review was left without a request.", - "$ref": "#/components/schemas/User" + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlockEmbed": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - "status": { - "description": "The status of the review.", - "$ref": "#/components/schemas/ChangeRequestReviewStatus" + "type": { + "type": "string", + "enum": ["embed"] }, - "comment": { - "$ref": "#/components/schemas/Comment" + "key": { + "type": "string" }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "data": { + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "fullWidth": { + "type": "boolean" + } + }, + "required": ["url"] }, - "updatedAt": { - "$ref": "#/components/schemas/Date" + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": [ - "object", - "id", - "revision", - "reviewer", - "status", - "createdAt", - "updatedAt" - ] - }, - "ChangeRequestReviewStatus": { - "type": "string", - "description": "Status of a change request review.", - "enum": ["changes-requested", "approved"] + "required": ["object", "type", "data", "isVoid"] }, - "ChangeRequestRequestedReviewer": { + "DocumentBlockCode": { "type": "object", - "allOf": [ - { + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["code"] + }, + "key": { + "type": "string" + }, + "data": { "type": "object", "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"change-request-requested-reviewer\"", - "enum": ["change-request-requested-reviewer"] + "syntax": { + "type": "string" }, - "revision": { + "title": { + "type": "string" + }, + "overflow": { "type": "string", - "description": "The revision of the content when the request was made." + "default": "scroll", + "enum": ["scroll", "wrap"] }, - "requestedBy": { - "description": "The user who made the request.", - "$ref": "#/components/schemas/User" + "lineNumbers": { + "type": "boolean" }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "fullWidth": { + "type": "boolean" } - }, - "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"] - } - ] - } - ] - }, - "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": { + "nodes": { "type": "array", - "description": "Reactions to add to the comment.", "items": { - "type": "string" + "$ref": "#/components/schemas/DocumentBlockCodeLine" } }, - "removedReactions": { - "type": "array", - "description": "Reactions to remove from the comment.", - "items": { - "type": "string" - } + "isVoid": { + "type": "boolean", + "enum": [false] } - } + }, + "required": ["object", "type", "data", "nodes"] }, - "UpdateCommentReplySchema": { + "DocumentBlockCodeLine": { "type": "object", "properties": { - "body": { - "description": "Content of the comment.", - "$ref": "#/components/schemas/Document" + "object": { + "type": "string", + "enum": ["block"] }, - "addedReactions": { - "type": "array", - "description": "Reactions to add to the comment.", - "items": { - "type": "string" - } + "type": { + "type": "string", + "enum": ["code-line"] }, - "removedReactions": { + "key": { + "type": "string" + }, + "nodes": { "type": "array", - "description": "Reactions to remove from the comment.", "items": { - "type": "string" + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentText" + }, + { + "$ref": "#/components/schemas/DocumentInlineAnnotation" + } + ] } - } - } - }, - "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" + "data": { + "type": "object", + "properties": { + "highlighted": { + "type": "boolean" + } + } }, - "body": { - "description": "The content of the comment.", - "$ref": "#/components/schemas/Document" - } - }, - "required": ["body"] - }, - "PostCommentReplySchema": { - "type": "object", - "properties": { - "body": { - "description": "The content of the comment.", - "$ref": "#/components/schemas/Document" + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["body"] + "required": ["object", "type", "nodes", "data"] }, - "UserContentPermission": { + "DocumentBlockMath": { "type": "object", - "description": "Permission of a user in a content.", "properties": { - "permission": { - "$ref": "#/components/schemas/MemberRole" + "object": { + "type": "string", + "enum": ["block"] }, - "user": { - "$ref": "#/components/schemas/User" - } - }, - "required": ["permission", "user"] - }, - "MemberContentPermission": { - "type": "object", - "description": "Permission of a member in a content.", - "properties": { - "permission": { - "$ref": "#/components/schemas/MemberRole" + "type": { + "type": "string", + "enum": ["math"] }, - "space": { - "$ref": "#/components/schemas/Space" - } - }, - "required": ["permission", "space"] - }, - "SearchSpaceResult": { - "type": "object", - "description": "Search result representing a space.", - "properties": { - "id": { + "key": { "type": "string" }, - "title": { - "type": "string" + "data": { + "type": "object", + "properties": { + "formula": { + "type": "string" + } + }, + "required": ["formula"] }, - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchPageResult" - } + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["id", "title", "pages"] + "required": ["object", "type", "data", "isVoid"] }, - "SearchPageResult": { + "DocumentBlockExpandable": { "type": "object", - "description": "Search result representing a page in a space.", "properties": { - "id": { - "type": "string" + "object": { + "type": "string", + "enum": ["block"] }, - "title": { - "type": "string" + "type": { + "type": "string", + "enum": ["expandable"] }, - "path": { + "key": { "type": "string" }, - "sections": { + "isVoid": { + "type": "boolean", + "enum": [true] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "fragments": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchSectionResult" + "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/DocumentBlockCode" + } + ] + }, + "minItems": 1 + } + }, + "required": ["nodes", "fragment", "type"] + } + ] + } + ] } }, - "urls": { + "meta": { "type": "object", - "description": "URLs associated with the object", "properties": { - "app": { - "type": "string", - "description": "URL of the page in the application", - "format": "uri" + "id": { + "description": "Unique ID to be used in an URL for the block.", + "type": "string" } }, - "required": ["app"] + "required": ["id"] } }, - "required": ["id", "title", "path", "urls"] + "required": ["object", "type", "isVoid", "fragments", "data"] }, - "SearchSectionResult": { + "DocumentBlockTabs": { "type": "object", - "description": "Search result representing a section in a page.", "properties": { - "id": { - "type": "string" + "object": { + "type": "string", + "enum": ["block"] }, - "title": { - "type": "string" + "type": { + "type": "string", + "enum": ["tabs"] }, - "path": { + "key": { "type": "string" }, - "body": { - "type": "string" + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockTabsItem" + } }, - "urls": { + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { "type": "object", - "description": "URLs associated with the object", - "properties": { - "app": { - "type": "string", - "description": "URL of the section in the application", - "format": "uri" - } - }, - "required": ["app"] + "properties": {}, + "additionalProperties": false } }, - "required": ["id", "title", "path", "body", "urls"] + "required": ["object", "type", "nodes"] }, - "SearchAIQuery": { + "DocumentBlockSwagger": { "type": "object", "properties": { - "query": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["swagger"] + }, + "key": { "type": "string" }, - "previousQueries": { - "type": "array", - "deprecated": true, - "maxItems": 10, - "items": { - "type": "string" - } + "data": { + "type": "object", + "properties": { + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] + }, + "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." + }, + "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": ["query"] + "required": ["object", "type", "data", "isVoid"] }, - "SearchAIAnswer": { + "DocumentBlockTable": { "type": "object", - "description": "Answer from AI for a question asked on a content.", "properties": { - "text": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["table"] + }, + "key": { "type": "string" }, - "followupQuestions": { - "type": "array", - "items": { - "type": "string" - } + "isVoid": { + "type": "boolean", + "enum": [true] }, - "sources": { + "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", - "description": "The sources used to generate the answer.", "items": { - "$ref": "#/components/schemas/SearchAIAnswerSource" + "$ref": "#/components/schemas/DocumentFragment" } + } + }, + "required": ["object", "type", "data", "isVoid", "fragments"] + }, + "DocumentTableRecord": { + "type": "object", + "properties": { + "orderIndex": { + "type": "string" }, - "pages": { - "type": "array", - "deprecated": true, - "description": "The pages used to generate the answer. Deprecated - use sources instead.", - "items": { - "type": "object", - "properties": { - "page": { - "type": "string" + "values": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "number" }, - "revision": { + { "type": "string" }, - "space": { - "type": "string" + { + "type": "boolean" }, - "sections": { + { "type": "array", "items": { "type": "string" } + }, + { + "$ref": "#/components/schemas/ContentRef" } - }, - "required": ["page", "revision", "space", "sections"] + ] } } }, - "required": ["text", "pages", "sources", "followupQuestions"] + "required": ["orderIndex", "values"] }, - "SearchAIAnswerSource": { + "DocumentTableDefinitionBase": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string", + "description": "Title for the column" + } + }, + "required": ["id", "title"] + }, + "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" + } + ] + }, + "DocumentTableDefinitionText": { "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, { "type": "object", "properties": { "type": { "type": "string", - "enum": ["page", "entity", "capture"] + "enum": ["text"] + }, + "textAlignment": { + "type": "string", + "enum": ["center", "right", "left"] + } + }, + "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" }, { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page"] - }, - "page": { - "type": "string" - }, - "revision": { - "type": "string" - }, - "space": { - "type": "string" - }, - "sections": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["type", "page", "revision", "space", "sections"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["entity"] - }, - "entityId": { - "type": "string", - "description": "ID of the entity" - }, - "entityType": { - "$ref": "#/components/schemas/EntityType" - }, - "integration": { - "description": "The name of the integration that manages this entity. If undefined, this entity is not managed by an integration.", - "type": "string" - } - }, - "required": ["type", "entityId", "entityType"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["capture"] - }, - "captureId": { - "type": "string", - "description": "ID of the capture" - }, - "source": { - "type": "string", - "description": "Source of the capture" - } - }, - "required": ["type", "captureId", "source"] + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["checkbox"] } - ] + }, + "required": ["type"] } ] }, - "SearchAIRecommendedQuestions": { - "type": "object", - "description": "Questions recommended by the AI for the given content.", - "properties": { - "questions": { - "type": "array", - "items": { - "type": "string" - } + "DocumentTableDefinitionFiles": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["files"] + } + }, + "required": ["type"] } - }, - "required": ["questions"] + ] }, - "AnalyticsSearchPeriod": { - "type": "string", - "enum": ["last_month", "last_week", "last_year"] - }, - "AnalyticsSearchQuery": { - "type": "object", - "description": "Analytics entry for a search query.", - "required": ["query", "searches", "hits", "pageHits", "sectionHits"], - "properties": { - "query": { - "type": "string" - }, - "searches": { - "description": "Number of searches done by users.", - "type": "number" - }, - "hits": { - "description": "Number of objects matching this search.", - "type": "number" - }, - "pageHits": { - "description": "Number of pages matching this search.", - "type": "number" + "DocumentTableDefinitionUsers": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "sectionHits": { - "description": "Number of sections matching this search.", - "type": "number" + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["users"] + }, + "multiple": { + "type": "boolean" + } + }, + "required": ["type", "multiple"] } - } + ] }, - "AnalyticsTopSearches": { - "type": "object", - "description": "Top search queries for a content.", - "required": ["searches", "queries"], - "properties": { - "searches": { - "description": "Number of searches done by users.", - "type": "number" + "DocumentTableDefinitionRating": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "queries": { - "description": "Top queries searched for this content.", - "type": "array", - "items": { - "$ref": "#/components/schemas/AnalyticsSearchQuery" - } + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["rating"] + }, + "max": { + "type": "number" + } + }, + "required": ["type", "max"] } - } - }, - "AnalyticsTrafficInterval": { - "type": "string", - "enum": ["daily", "weekly", "monthly"] + ] }, - "AnalyticsTrafficPageViews": { - "type": "object", - "required": ["count", "views"], - "properties": { - "count": { - "description": "Total number of page views over the period.", - "type": "number" + "DocumentTableDefinitionSelect": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "views": { - "description": "Page views per interval (day, week, month).", - "type": "array", - "items": { - "type": "object", - "properties": { - "timestamp": { - "type": "string" - }, - "count": { - "type": "number" - } + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["select"] }, - "required": ["timestamp", "count"] - } + "multiple": { + "type": "boolean" + }, + "options": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTableSelectOption" + } + } + }, + "required": ["type", "multiple", "options"] } - } + ] }, - "AnalyticsContentPages": { - "type": "object", - "required": ["pages"], - "properties": { - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AnalyticsContentPage" - } + "DocumentTableDefinitionContentRef": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["content-ref"] + } + }, + "required": ["type"] } - } + ] }, - "AnalyticsContentPage": { + "DocumentTableSelectOption": { "type": "object", - "description": "Page entry in the content analytics.", - "required": ["page", "title", "pageViews"], "properties": { - "page": { + "value": { "type": "string" }, - "title": { + "label": { "type": "string" }, - "pageViews": { - "type": "number" - }, - "feedbacks": { - "type": "object", - "required": ["score", "total", "rating", "bad", "ok", "good"], - "properties": { - "score": { - "type": "number", - "description": "Score between 0 and 4." - }, - "total": { - "type": "number" - }, - "rating": { - "type": "string", - "enum": ["unknown", "bad", "ok", "good"] - }, - "bad": { - "type": "number" - }, - "ok": { - "type": "number" - }, - "good": { - "type": "number" - } - } + "color": { + "type": "string" } - } + }, + "required": ["value", "label", "color"] }, - "Collection": { + "DocumentTableViewCards": { "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": { + "type": { "type": "string", - "description": "Title of the collection", - "minLength": 0, - "maxLength": 100 + "enum": ["cards"] }, - "path": { + "cardSize": { "type": "string", - "description": "Path in the published URL" + "description": "Size of the cards. It indicates how many columns will be used", + "enum": ["medium", "large"] }, - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" + "columns": { + "type": "array", + "description": "Ordered list of the definition IDs to display", + "items": { + "type": "string" + } }, - "publishingType": { + "targetDefinition": { "type": "string", - "enum": ["variants"] + "description": "Definition ID to use as a target link for the card" }, - "primarySpace": { + "coverDefinition": { "type": "string", - "description": "ID of the primary space for this collection" + "description": "Definition ID to use as a cover image" }, - "collection": { - "type": "string", - "description": "ID of the parent collection, if any" + "hideColumnTitle": { + "type": "boolean", + "description": "Should we display the column title or not" } }, - "required": ["object", "id", "title", "visibility"] + "required": ["type", "columns", "cardSize"] }, - "Integration": { + "DocumentTableViewGrid": { "type": "object", "properties": { - "object": { - "type": "string", - "enum": ["integration"] - }, - "name": { + "type": { "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" + "enum": ["grid"] }, - "previewImages": { + "columns": { "type": "array", - "description": "URLs of images to showcase the integration", - "maxItems": 3, + "description": "Ordered list of the definition IDs to display", "items": { "type": "string" } }, - "target": { - "$ref": "#/components/schemas/IntegrationTarget" + "columnWidths": { + "type": "object", + "description": "Percent width of each column", + "additionalProperties": { + "type": "number" + } }, - "verified": { + "hideHeader": { "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" + "description": "Should we display the header with column titles" }, - "configurations": { - "$ref": "#/components/schemas/IntegrationConfigurations" + "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"] + }, + "DocumentBlockTabsItem": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - "externalLinks": { - "$ref": "#/components/schemas/IntegrationExternalLinks" + "type": { + "type": "string", + "enum": ["tabs-item"] }, - "owner": { - "$ref": "#/components/schemas/Organization" + "key": { + "type": "string" }, - "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"] + "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" + } + ] + } }, - "permissions": { + "data": { "type": "object", - "description": "The set of permissions for the integration", "properties": { - "admin": { - "type": "boolean" + "title": { + "type": "string" } - }, - "required": ["admin"] + } }, - "contentSecurityPolicy": { - "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" - } - }, - "required": [ - "object", - "name", - "version", - "title", - "scopes", - "categories", - "visibility", - "target", - "verified", - "previewImages", - "externalLinks", - "owner", - "permissions", - "urls" - ] - }, - "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 - }, - "IntegrationScopes": { - "type": "array", - "description": "Permissions that should be granted to the integration", - "items": { - "$ref": "#/components/schemas/IntegrationScope" - } - }, - "IntegrationScope": { - "type": "string", - "enum": [ - "entities:write", - "capture:write", - "space:views:read", - "space:content:read", - "space:content:write", - "space:metadata:read", - "space:metadata:write", - "space:script:inject", - "space:script:cookies", - "space:git:sync" - ] - }, - "IntegrationCategories": { - "type": "array", - "description": "Categories for which the integration is listed in the marketplace", - "items": { - "$ref": "#/components/schemas/IntegrationCategory" - } - }, - "IntegrationBlockMarkdown": { - "oneOf": [ - { + "meta": { "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.", + "id": { + "description": "Unique ID to be used in an URL for the block.", "type": "string" } }, - "required": ["codeblock", "body"] + "required": ["id"] + }, + "isVoid": { + "type": "boolean", + "enum": [false] } - ] - }, - "IntegrationBlocks": { - "type": "array", - "description": "Custom blocks defined by this integration.", - "items": { - "$ref": "#/components/schemas/IntegrationBlock" - } + }, + "required": ["object", "type", "nodes", "data"] }, - "IntegrationBlock": { + "DocumentBlockContentRef": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique ID in the integration for the block. It also represents the UI component used." - }, - "title": { + "object": { "type": "string", - "description": "Short descriptive title for the block.", - "minLength": 2, - "maxLength": 40 + "enum": ["block"] }, - "description": { + "type": { "type": "string", - "description": "Long descriptive text for the block.", - "minLength": 0, - "maxLength": 150 + "enum": ["content-ref"] }, - "icon": { - "type": "string", - "description": "URL of the icon to represent this block." + "key": { + "type": "string" }, - "urlUnfurl": { - "type": "array", - "description": "URLs patterns to convert as this block.", - "items": { - "type": "string" - } + "data": { + "type": "object", + "properties": { + "ref": { + "$ref": "#/components/schemas/ContentRef" + } + }, + "required": ["ref"] }, - "markdown": { - "$ref": "#/components/schemas/IntegrationBlockMarkdown" + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["id", "title"] - }, - "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"] - } + "required": ["object", "type", "data", "isVoid"] }, - "IntegrationEvent": { + "DocumentBlockIntegration": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique ID of the event." - }, - "integrationId": { + "object": { "type": "string", - "description": "Unique ID of the integration." + "enum": ["block"] }, - "installationId": { + "type": { "type": "string", - "description": "Unique ID of the integration installation." + "enum": ["integration"] }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "key": { + "type": "string" }, - "payload": { - "$ref": "#/components/schemas/Event" + "data": { + "type": "object", + "properties": { + "integration": { + "type": "string", + "description": "Name of the integration" + }, + "block": { + "type": "string", + "description": "ID of the block in the integration" + }, + "props": { + "type": "object", + "description": "Properties passed to the block during rendering", + "additionalProperties": { + "description": "Any value" + } + }, + "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"] }, - "status": { - "type": "string", - "description": "Status of the event.", - "enum": ["success", "failed"] + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["id", "integrationId", "createdAt", "payload", "status"] + "required": ["object", "type", "data", "isVoid"] }, - "IntegrationEventLog": { + "DocumentBlockDivider": { "type": "object", "properties": { - "message": { - "description": "The message of the log entry.", - "type": "string" + "object": { + "type": "string", + "enum": ["block"] }, - "timestamp": { - "$ref": "#/components/schemas/Date" - }, - "level": { - "description": "The level of the log entry.", + "type": { "type": "string", - "enum": ["debug", "info", "warn", "error"] - } - } - }, - "IntegrationEventTrace": { - "type": "object", - "required": ["logs"], - "properties": { - "logs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationEventLog" - } + "enum": ["divider"] + }, + "key": { + "type": "string" + }, + "isVoid": { + "type": "boolean", + "enum": [true] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } - } - }, - "IntegrationInstallationSpaceSelection": { - "type": "string", - "description": "Describe whether all spaces have been selected or there's a selection involved", - "enum": ["all", "selected"] - }, - "IntegrationCategory": { - "type": "string", - "enum": [ - "analytics", - "captures", - "collaboration", - "content", - "gitsync", - "marketing", - "other" - ] + }, + "required": ["object", "type", "isVoid", "data"] }, - "IntegrationConfigurations": { + "DocumentBlockSyncedBlock": { "type": "object", "properties": { - "account": { - "$ref": "#/components/schemas/IntegrationConfiguration" + "object": { + "type": "string", + "enum": ["block"] }, - "space": { - "$ref": "#/components/schemas/IntegrationConfiguration" + "type": { + "type": "string", + "enum": ["synced-block"] + }, + "key": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "ref": { + "$ref": "#/components/schemas/ContentRefSyncedBlock" + } + }, + "required": ["ref"] + }, + "meta": { + "type": "object", + "properties": { + "apiToken": { + "description": "API Token to use to fetch the synced block from the API.", + "type": "string" + } + }, + "required": ["apiToken"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } - } + }, + "required": ["object", "type", "data", "isVoid"] }, - "IntegrationConfiguration": { + "ContentRef": { "oneOf": [ { - "$ref": "#/components/schemas/IntegrationConfigurationSchema" + "$ref": "#/components/schemas/ContentRefFile" }, { - "$ref": "#/components/schemas/IntegrationConfigurationComponent" + "$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/ContentRefSnippet" + }, + { + "$ref": "#/components/schemas/ContentRefSyncedBlock" } ] }, - "IntegrationConfigurationSchema": { + "ContentRefURL": { "type": "object", - "description": "Schema for a configuration", "properties": { - "properties": { - "type": "object", - "additionalProperties": { - "allOf": [ - { - "type": "object", - "properties": { - "title": { - "type": "string", - "maxLength": 30 - }, - "description": { - "type": "string", - "maxLength": 100 - } - } - }, - { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["string"] - }, - "default": { - "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"] - } - ] - } - ] - } + "kind": { + "type": "string", + "enum": ["url"] }, - "required": { - "type": "array", - "uniqueItems": true, - "items": { - "type": "string" - } + "url": { + "type": "string" } }, - "required": ["properties"] + "required": ["kind", "url"] }, - "IntegrationConfigurationComponent": { + "ContentRefFile": { "type": "object", - "description": "ContentKit component for configuration", "properties": { - "componentId": { + "kind": { "type": "string", - "description": "ID of the ContentKit component defined in the integration" + "enum": ["file"] + }, + "file": { + "type": "string" } }, - "required": ["componentId"] - }, - "IntegrationVisibility": { - "type": "string", - "enum": ["public", "private", "unlisted"] + "required": ["kind", "file"] }, - "IntegrationInstallation": { + "ContentRefPage": { "type": "object", - "description": "Installation of an integration on an account", "properties": { - "id": { + "kind": { + "type": "string", + "enum": ["page"] + }, + "page": { "type": "string" }, - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" + "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"] }, - "space_selection": { - "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" + "anchor": { + "type": "string" }, - "spaces": { - "type": "number", - "description": "Count of spaces, the installation is managing" + "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" }, - "configuration": { - "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + "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"] }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "user": { + "type": "string" + } + }, + "required": ["kind", "user"] + }, + "ContentRefCollection": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["collection"] }, - "updatedAt": { - "$ref": "#/components/schemas/Date" + "collection": { + "type": "string" + } + }, + "required": ["kind", "collection"] + }, + "ContentRefSpace": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["space"] }, - "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"] + "space": { + "type": "string" + } + }, + "required": ["kind", "space"] + }, + "ContentRefSnippet": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["snippet"] }, - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + "snippet": { + "type": "string" }, - "target": { - "$ref": "#/components/schemas/IntegrationInstallationTarget", - "description": "Target of the integration installation" + "organization": { + "type": "string" } }, - "required": [ - "id", - "status", - "space_selection", - "spaces", - "configuration", - "urls", - "externalIds", - "target", - "createdAt", - "updatedAt" - ] + "required": ["kind", "snippet", "organization"] }, - "IntegrationSpaceInstallation": { + "ContentRefSyncedBlock": { "type": "object", - "description": "Installation of an integration at a space level", "properties": { - "integration": { - "description": "Unique name identifier of the integration", - "type": "string" + "kind": { + "type": "string", + "enum": ["synced-block"] }, - "installation": { - "description": "ID of the integration installation", + "syncedBlock": { "type": "string" }, - "space": { - "description": "ID of the space the integration is installed on.", + "organization": { "type": "string" + } + }, + "required": ["kind", "syncedBlock", "organization"] + }, + "Space": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"space\"", + "enum": ["space"] }, - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" + "id": { + "type": "string", + "description": "Unique identifier for the space" }, - "configuration": { - "description": "Configuration of the integration for this space", - "type": "object" + "title": { + "$ref": "#/components/schemas/SpaceTitle" }, - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + "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" }, "urls": { "type": "object", @@ -3571,3235 +3955,2933 @@ "properties": { "location": { "type": "string", - "description": "URL of the integration's space installation in the API", + "description": "URL of the space in the API", "format": "uri" }, - "publicEndpoint": { + "app": { "type": "string", - "description": "Public HTTP endpoint for the integration's space installation", + "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": ["location", "publicEndpoint"] + "required": ["app", "location"] + }, + "organization": { + "type": "string", + "description": "ID of the organization owning this space" + }, + "parent": { + "type": "string", + "description": "ID of the parent collection." + }, + "gitSync": { + "$ref": "#/components/schemas/GitSyncState" + }, + "visitorAuth": { + "$ref": "#/components/schemas/SpaceVisitorAuth" + }, + "revision": { + "type": "string", + "description": "ID of the active revision in the space." + }, + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" } }, "required": [ - "integration", - "installation", - "space", - "status", - "configuration", - "externalIds", - "urls" + "object", + "id", + "type", + "title", + "emoji", + "organization", + "visibility", + "revision", + "createdAt", + "updatedAt", + "urls", + "defaultLevel" ] }, - "IntegrationInstallationStatus": { + "SpaceEditMode": { "type": "string", - "enum": ["active", "pending", "paused"] + "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"] }, - "IntegrationSecrets": { - "type": "object", - "description": "Secrets stored on the integration and passed at runtime.", - "properties": {}, - "maxProperties": 20, - "additionalProperties": { - "type": "string" - } + "SpaceTitle": { + "type": "string", + "description": "Title of the space", + "minLength": 1, + "maxLength": 50 }, - "IntegrationEnvironment": { + "SpaceVisitorAuth": { + "oneOf": [ + { + "type": "object", + "title": "Custom", + "properties": { + "backend": { + "type": "string", + "description": "Custom backend for Visitor Authentication", + "enum": ["custom"] + } + }, + "required": ["backend"] + }, + { + "type": "object", + "title": "Integration", + "properties": { + "backend": { + "type": "string", + "description": "Integration as backend for Visitor Authentication", + "enum": ["integration"] + }, + "integration": { + "type": "string", + "description": "Name of integration being used as the backend for Visitor Authentication" + } + }, + "required": ["backend", "integration"] + } + ] + }, + "RevisionBase": { "type": "object", - "description": "Runtime environment provided during the execution of integration's code.", "properties": { - "authToken": { + "object": { "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 + "description": "Type of Object, always equals to \"revision\"", + "enum": ["revision"] }, - "integration": { - "$ref": "#/components/schemas/Integration" + "id": { + "description": "Unique identifier for the revision", + "type": "string" }, - "installation": { - "$ref": "#/components/schemas/IntegrationInstallation" + "parents": { + "description": "IDs of the parent revisions", + "type": "array", + "items": { + "type": "string" + } }, - "spaceInstallation": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } }, - "secrets": { - "$ref": "#/components/schemas/IntegrationSecrets" + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionFile" + } }, - "signingSecret": { - "type": "string", - "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the integration." + "createdAt": { + "description": "When the revision was created.", + "$ref": "#/components/schemas/Timestamp" }, - "apiEndpoint": { - "type": "string", - "description": "URL of the HTTP API" + "git": { + "description": "Metadata about a potential associated git commit.", + "$ref": "#/components/schemas/GitSyncCommit" }, - "apiTokens": { + "urls": { "type": "object", "properties": { - "integration": { + "app": { "type": "string", - "description": "API authentication token representing the integration." + "format": "uri", + "description": "URL in the application for the revision" }, - "installation": { + "published": { "type": "string", - "description": "API authentication token representing the current installation." + "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": ["integration"] + "required": ["app"] } }, - "required": ["apiEndpoint", "apiTokens", "integration", "secrets"] + "required": ["object", "id", "parents", "pages", "files", "urls", "createdAt"] }, - "IntegrationTarget": { - "type": "string", - "enum": ["organization", "all"] - }, - "IntegrationInstallationTarget": { - "oneOf": [ + "RevisionTypeMerge": { + "allOf": [ { - "$ref": "#/components/schemas/OrganizationTarget" - } - ] - }, - "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" - } - }, - "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" + "$ref": "#/components/schemas/RevisionBase" }, { "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" + "type": { + "type": "string", + "description": "Revision created when merging a change request with primary.", + "enum": ["merge"] }, - "worker-src": { - "type": "string" + "mergedFrom": { + "$ref": "#/components/schemas/ChangeRequest" } - } - } - ] - }, - "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" - } - } - } - } - }, - "UpsertEntity": { - "type": "object", - "description": "Entity to create or update in an integration's installation.", - "properties": { - "entityId": { - "$ref": "#/components/schemas/EntityId" - }, - "properties": { - "type": "object", - "description": "Map of values stored as properties on the entity", - "additionalProperties": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - }, - { - "type": "object", - "properties": { - "entityId": { - "type": "string" - } - }, - "required": ["entityId"] - } - ] - } + "required": ["type", "mergedFrom"] } - }, - "required": ["entityId", "properties"] + ] }, - "Entity": { + "RevisionTypeRollback": { "allOf": [ { - "$ref": "#/components/schemas/UpsertEntity" + "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", - "description": "Entity created and managed by an integration, representing an external element.", "properties": { - "id": { - "type": "string", - "description": "Unique ID for the entity in GitBook" - }, "type": { - "deprecated": true, - "description": "Type of an entity. Deprecated, use entityType.", - "$ref": "#/components/schemas/EntityType" - }, - "entityType": { - "$ref": "#/components/schemas/EntityType" - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the entity in the API", - "format": "uri" - } - }, - "required": ["location"] + "type": "string", + "description": "Revision created as a rollback of a previous revision.", + "enum": ["rollback"] } }, - "required": ["id", "type", "entityType", "urls"] + "required": ["type"] } ] }, - "EntityType": { - "type": "string", - "description": "Type of an entity", - "minLength": 1, - "maxLength": 64 - }, - "EntityId": { - "type": "string", - "description": "Unique ID of the entity in the context of the integration's entity type", - "minLength": 1, - "maxLength": 256 - }, - "EntitySchemaTitle": { - "type": "string", - "maxLength": 50 - }, - "EntityRawSchema": { - "type": "object", - "description": "Schema for a type of entities", - "properties": { - "type": { - "$ref": "#/components/schemas/EntityType" + "RevisionTypeUpdate": { + "allOf": [ + { + "$ref": "#/components/schemas/RevisionBase" }, - "title": { + { "type": "object", - "description": "Title of the entity type", "properties": { - "singular": { - "$ref": "#/components/schemas/EntitySchemaTitle" - }, - "plural": { - "$ref": "#/components/schemas/EntitySchemaTitle" + "type": { + "type": "string", + "description": "Revision created when updating a change request with changes from primary.", + "enum": ["update"] } }, - "required": ["singular", "plural"] - }, - "properties": { - "type": "array", - "description": "Ordered list of all properties stored in entities.", - "items": { - "$ref": "#/components/schemas/EntityPropertySchema" - } + "required": ["type"] } - }, - "required": ["type", "title", "properties"] + ] }, - "EntitySchema": { + "RevisionTypeEdits": { "allOf": [ { - "$ref": "#/components/schemas/EntityRawSchema" + "$ref": "#/components/schemas/RevisionBase" }, { "type": "object", "properties": { - "entities": { - "description": "Count of entities created in this schema.", - "type": "number" - }, - "integration": { - "description": "Integration managing this schema.", - "$ref": "#/components/schemas/Integration" - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the entity schema in the API", - "format": "uri" - } - }, - "required": ["location"] - } - }, - "required": ["entities", "urls"] - } - ] - }, - "EntityPropertySchema": { - "allOf": [ - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the property in the object" - }, - "title": { - "type": "string", - "description": "Title displayed to the users" - }, - "description": { + "type": { "type": "string", - "description": "Description of the property" - }, - "deprecated": { - "type": "boolean", - "description": "If true, the property is no longer required and not taken into consideration" + "description": "Revision created by editing the content.", + "enum": ["edits"] } }, - "required": ["name", "title"] - }, - { - "oneOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["text"] - }, - "role": { - "type": "string", - "enum": ["title"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["longtext"] - }, - "role": { - "type": "string", - "enum": ["body"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["url"] - }, - "role": { - "type": "string", - "enum": ["target", "icon"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["number"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["boolean"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["enum"] - }, - "values": { - "type": "array", - "items": { - "type": "object", - "properties": { - "label": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "required": ["label", "value"] - } - } - }, - "required": ["type", "values"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["date"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["user"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "description": "reference to another entity, creating a relation", - "properties": { - "type": { - "type": "string", - "enum": ["relation"] - }, - "entity": { - "type": "object", - "properties": { - "type": { - "$ref": "#/components/schemas/EntityType" - } - }, - "required": ["type"] - } - }, - "required": ["type", "entity"] - } - ] + "required": ["type"] } ] }, - "Event": { - "description": "Any event that can be received from GitBook.", + "Revision": { "oneOf": [ { - "$ref": "#/components/schemas/InstallationSetupEvent" - }, - { - "$ref": "#/components/schemas/SpaceInstallationSetupEvent" - }, - { - "$ref": "#/components/schemas/SpaceInstallationDeletedEvent" - }, - { - "$ref": "#/components/schemas/SpaceViewEvent" - }, - { - "$ref": "#/components/schemas/SpaceContentUpdatedEvent" + "$ref": "#/components/schemas/RevisionTypeEdits" }, { - "$ref": "#/components/schemas/SpaceGitSyncCompletedEvent" + "$ref": "#/components/schemas/RevisionTypeMerge" }, { - "$ref": "#/components/schemas/SpaceGitSyncStartedEvent" + "$ref": "#/components/schemas/RevisionTypeRollback" }, { - "$ref": "#/components/schemas/SpaceVisibilityUpdatedEvent" - }, + "$ref": "#/components/schemas/RevisionTypeUpdate" + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "RevisionPage": { + "oneOf": [ { - "$ref": "#/components/schemas/FetchEvent" + "$ref": "#/components/schemas/RevisionPageDocument" }, { - "$ref": "#/components/schemas/FetchPublishedScriptEvent" + "$ref": "#/components/schemas/RevisionPageGroup" }, { - "$ref": "#/components/schemas/UIRenderEvent" + "$ref": "#/components/schemas/RevisionPageLink" } ], "discriminator": { "propertyName": "type" } }, - "BaseEvent": { - "description": "Common properties for all events.", + "RevisionPageBase": { "type": "object", "properties": { - "eventId": { - "description": "Unique identifier for the event.", + "id": { + "description": "Unique identifier for the page in the revision", "type": "string" }, - "type": { - "description": "Type of the event.", - "type": "string" + "title": { + "description": "Title of the page", + "type": "string", + "maxLength": 100 + }, + "emoji": { + "description": "Emoji of the page, if one has been set.", + "$ref": "#/components/schemas/Emoji" + }, + "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": ["eventId", "type"] + "required": ["id", "title"] }, - "InstallationEvent": { + "RevisionPageDocument": { "allOf": [ { - "$ref": "#/components/schemas/BaseEvent" + "$ref": "#/components/schemas/RevisionPageBase" + }, + { + "$ref": "#/components/schemas/Document" }, { "type": "object", - "description": "Common properties for all events related to an installation", "properties": { - "installationId": { + "kind": { "type": "string", - "description": "ID of the integration installation" - } - }, - "required": ["installationId"] - } - ] - }, - "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"] - } - ] - }, - "InstallationSetupEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/InstallationEvent" - }, - { - "type": "object", - "description": "Event received when integration has been installed or updated.", - "properties": { + "deprecated": true, + "enum": ["sheet"] + }, "type": { "type": "string", - "enum": ["installation_setup"] - }, - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" + "enum": ["document"] }, - "previous": { - "type": "object", - "description": "The state of the installation at the account level before it was updated.", + "urls": { + "required": ["app"], "properties": { - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" - }, - "configuration": { - "type": "object", - "description": "The previous configuration of the installation at the account level." + "app": { + "description": "Location of the page in the app", + "$ref": "#/components/schemas/URL" } - }, - "required": ["status"] + } + }, + "slug": { + "description": "Page's slug in its direct parent", + "type": "string" + }, + "path": { + "description": "Complete path to access the page in the revision.", + "type": "string" + }, + "description": { + "type": "string" + }, + "documentId": { + "type": "string", + "description": "ID of the document with the page body. If undefined, the page is empty." + }, + "pages": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageLink" + } + ] + } + }, + "git": { + "$ref": "#/components/schemas/GitSyncBlob" + }, + "layout": { + "$ref": "#/components/schemas/RevisionPageLayoutOptions" + }, + "cover": { + "$ref": "#/components/schemas/RevisionPageDocumentCover" } }, - "required": ["type", "status"] + "required": ["kind", "type", "urls", "slug", "path", "pages", "layout"] } ] }, - "SpaceInstallationSetupEvent": { + "RevisionPageDocumentCover": { + "type": "object", + "properties": { + "ref": { + "description": "Content reference pointing to the source image.", + "$ref": "#/components/schemas/ContentRefFile" + }, + "yPos": { + "description": "Vertical position of the cover image.", + "type": "number" + } + }, + "required": ["yPos"] + }, + "RevisionPageGroup": { "allOf": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/schemas/RevisionPageBase" }, { "type": "object", - "description": "Event received when integration has been installed or updated on a space.", "properties": { + "kind": { + "type": "string", + "deprecated": true, + "enum": ["group"] + }, "type": { "type": "string", - "enum": ["space_installation_setup"] + "enum": ["group"] }, - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" + "slug": { + "description": "Page's slug in its direct parent", + "type": "string" }, - "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"] + "path": { + "description": "Complete path to access the page in the revision.", + "type": "string" + }, + "pages": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageLink" + } + ] + } } }, - "required": ["type", "status"] + "required": ["kind", "type", "slug", "path", "pages"] } ] }, - "SpaceInstallationDeletedEvent": { - "allOf": [ + "RevisionPageLayout": { + "oneOf": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/schemas/RevisionPageLayoutPreset" }, { - "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"] + "$ref": "#/components/schemas/RevisionPageLayoutOptions" } ] }, - "SpaceViewEvent": { + "RevisionPageLayoutOptions": { + "type": "object", + "properties": { + "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?" + } + } + }, + "RevisionPageLayoutOptionsCoverSize": { + "type": "string", + "description": "Size of the cover image.", + "enum": ["hero", "full"] + }, + "RevisionPageLayoutPreset": { + "type": "string", + "description": "The core layout presets for a page.", + "enum": ["docs", "editorial", "landing"] + }, + "RevisionPageLink": { "allOf": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/schemas/RevisionPageBase" }, { "type": "object", - "description": "Event received when a page has been visited.", "properties": { - "type": { + "kind": { "type": "string", - "enum": ["space_view"] + "deprecated": true, + "enum": ["link"] }, - "pageId": { + "type": { "type": "string", - "description": "Unique identifier of the visited 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" - } - }, - "userAgent": { - "type": "string", - "description": "User-agent of the visitor." - }, - "ip": { - "type": "string", - "description": "IP address of the visitor." - } - }, - "required": ["anonymousId", "cookies", "userAgent", "ip"] + "enum": ["link"] }, - "url": { - "type": "string", - "description": "The GitBook content's URL visited (including URL params)." + "target": { + "$ref": "#/components/schemas/ContentRef" }, - "referrer": { - "type": "string", - "description": "The URL of referrer that linked to the page." + "href": { + "type": "string" } }, - "required": ["type", "visitor", "url", "referrer"] + "required": ["kind", "type", "target"] } ] }, - "SpaceContentUpdatedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + "RevisionPageType": { + "type": "string", + "enum": ["document", "group", "link"] + }, + "RevisionFile": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - { + "name": { + "type": "string" + }, + "contentType": { + "type": "string" + }, + "downloadURL": { + "type": "string" + }, + "size": { + "type": "number" + }, + "dimensions": { "type": "object", - "description": "Event when the primary content of a space has been updated.", + "description": "For images, it contains the dimensions of it.", "properties": { - "type": { - "type": "string", - "enum": ["space_content_updated"] + "width": { + "type": "number" }, - "revisionId": { - "type": "string", - "description": "Unique identifier of the new content revision" + "height": { + "type": "number" } }, - "required": ["type", "revisionId"] - } - ] - }, - "SpaceVisibilityUpdatedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + "required": ["width", "height"] }, - { - "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"] + "git": { + "$ref": "#/components/schemas/GitSyncBlob" } - ] + }, + "required": ["id", "name", "contentType", "downloadURL", "size"] }, - "SpaceGitSyncCompletedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + "RevisionFileImageDimensions": { + "type": "object", + "properties": { + "height": { + "type": "number" }, - { - "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"] + "width": { + "type": "number" } + }, + "required": ["height", "width"] + }, + "ImportContentSource": { + "type": "string", + "enum": [ + "website", + "docx", + "markdown", + "html", + "zip", + "confluence", + "github-wiki", + "dropbox-paper", + "notion", + "quip", + "google-docs", + "open-api" ] }, - "SpaceGitSyncStartedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + "ChangeAttributeContentReference": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/ContentRef" }, - { - "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"] + "after": { + "$ref": "#/components/schemas/ContentRef" } - ] + } }, - "FetchRequest": { + "ChangeAttributeCustomFields": { "type": "object", "properties": { - "method": { - "type": "string", - "enum": ["post", "get", "put", "delete"] - }, - "url": { - "type": "string" - }, - "headers": { + "before": { "type": "object", "additionalProperties": { - "type": "string" + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } + }, + "required": ["value"] } - } - }, - "required": ["method", "url", "headers"] - }, - "FetchEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseEvent" }, - { + "after": { "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" - }, - "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"] + "additionalProperties": { + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } }, - "request": { - "$ref": "#/components/schemas/FetchRequest" - } - }, - "required": ["type", "request"] + "required": ["value"] + } } - ] + } }, - "FetchPublishedScriptEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + "ChangeAttributeNumber": { + "type": "object", + "properties": { + "before": { + "type": "number" }, - { - "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"] + "after": { + "type": "number" } - ] + } }, - "UIRenderEvent": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" - }, - { - "$ref": "#/components/schemas/InstallationEvent" - } - ] + "ChangeAttributeRevisionFileImageDimensions": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/RevisionFileImageDimensions" }, - { - "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"] + "after": { + "$ref": "#/components/schemas/RevisionFileImageDimensions" } - ] - }, - "BillingInterval": { - "type": "string", - "description": "Interval for a billing subscription", - "enum": ["monthly", "yearly"] + } }, - "BillingPortal": { + "ChangeAttributeRevisionPageDocumentCover": { "type": "object", "properties": { - "url": { - "type": "string", - "description": "URL to the billing portal for an organization" + "before": { + "$ref": "#/components/schemas/RevisionPageDocumentCover" + }, + "after": { + "$ref": "#/components/schemas/RevisionPageDocumentCover" } - }, - "required": ["url"] - }, - "BillingProduct": { - "type": "string", - "description": "Name of the product", - "enum": [ - "free", - "plus", - "pro", - "team", - "business", - "legacy", - "startup", - "enterprise" - ] - }, - "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"] - } - ] + } }, - "BillingInvoicePreview": { + "ChangeAttributeRevisionPageLayout": { "type": "object", "properties": { - "amount": { - "description": "Amount of the invoice", - "type": "number" - }, - "amountDueToday": { - "description": "Amount that will be immediately charged.", - "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/Date" - }, - "periodEnd": { - "$ref": "#/components/schemas/Date" - } - }, - "required": ["amount", "description", "periodStart", "periodEnd"] - } - } - }, - "required": [ - "amount", - "amountDueToday", - "customerBalance", - "remainingCustomerBalance", - "lines" - ] - }, - "APIIntegrationScope": { - "type": "string", - "enum": [ - "integration:read", - "integration:update", - "integration:installation:read", - "integration:installation:update" - ] - }, - "APIScope": { - "anyOf": [ - { - "$ref": "#/components/schemas/IntegrationScope" + "before": { + "$ref": "#/components/schemas/RevisionPageLayout" }, - { - "$ref": "#/components/schemas/APIIntegrationScope" + "after": { + "$ref": "#/components/schemas/RevisionPageLayout" } - ] - }, - "CloudflareHostnameStatus": { - "type": "string", - "description": "The Cloudflare Hostname status", - "enum": ["pending", "active", "blocked", "moved", "deleted"] + } }, - "CloudflareHostnameTLSCertificate": { + "ChangeAttributeString": { "type": "object", - "description": "The Cloudflare Hostname TLS certificate", "properties": { - "issuer": { - "type": "string" - }, - "expiresOn": { + "before": { "type": "string" }, - "issuedOn": { + "after": { "type": "string" } } }, - "CloudflareHostnameTLSInfo": { + "ChangedRevisionFile": { "type": "object", - "description": "The Cloudflare Hostname TLS information", "properties": { - "status": { - "$ref": "#/components/schemas/CloudflareHostnameTLSStatus" - }, - "method": { - "$ref": "#/components/schemas/CloudflareHostnameTLSValidationMethod" + "id": { + "type": "string" }, - "certificateAuthority": { + "name": { "type": "string" }, - "certificates": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CloudflareHostnameTLSCertificate" - } + "contentType": { + "type": "string" }, - "validationErrors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CloudflareHostnameTLSValidationError" - } + "downloadURL": { + "type": "string" } }, - "required": ["status", "method", "certificates", "validationErrors"] - }, - "CloudflareHostnameTLSStatus": { - "type": "string", - "description": "The Cloudflare Hostname TLS status", - "enum": [ - "initializing", - "pending_validation", - "pending_issuance", - "pending_deployment", - "active", - "pending_deletion", - "pending_cleanup", - "deleted" - ] + "required": ["id", "name", "contentType", "downloadURL"] }, - "CloudflareHostnameTLSValidationError": { + "ChangedRevisionPage": { "type": "object", - "description": "The Cloudflare Hostname TLS validation error", "properties": { - "message": { + "id": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/RevisionPageType" + }, + "title": { + "type": "string" + }, + "path": { "type": "string" } }, - "required": ["message"] - }, - "CloudflareHostnameTLSValidationMethod": { - "type": "string", - "description": "The Cloudflare Hostname TLS validation method", - "enum": ["http", "txt", "email"] + "required": ["id", "type", "title"] }, - "CustomDomainInfo": { + "RevisionFileChangeAttributes": { "type": "object", - "description": "Cloudflare Custom Domain's information", + "minProperties": 1, "properties": { - "hostname": { - "type": "string" + "name": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "status": { - "$ref": "#/components/schemas/CloudflareHostnameStatus" + "downloadURL": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "createdAt": { - "type": "string" + "size": { + "$ref": "#/components/schemas/ChangeAttributeNumber" }, - "ssl": { - "$ref": "#/components/schemas/CloudflareHostnameTLSInfo" + "contentType": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "verificationErrors": { - "type": "array", - "items": { - "type": "string" - } + "dimensions": { + "$ref": "#/components/schemas/ChangeAttributeRevisionFileImageDimensions" } - }, - "required": ["hostname", "status", "createdAt", "verificationErrors"] + } }, - "FirebaseUserInfo": { + "RevisionPageDocumentChangeAttributes": { "type": "object", - "description": "The User Firebase Auth Info.", + "minProperties": 1, "properties": { - "uid": { - "type": "string" + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "displayName": { - "type": "string" + "description": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "email": { - "type": "string" + "slug": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "phoneNumber": { - "type": "string" + "document": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "photoUrl": { - "type": "string" + "cover": { + "$ref": "#/components/schemas/ChangeAttributeRevisionPageDocumentCover" }, - "providerId": { - "type": "string" + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "layout": { + "$ref": "#/components/schemas/ChangeAttributeRevisionPageLayout" + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - }, - "required": ["uid"] - }, - "PurgeCDNCacheContextType": { - "type": "string", - "description": "The type of purge, e.g by tags or hosts", - "enum": ["tags", "hosts"] + } }, - "StaffUserInfo": { + "RevisionPageGroupChangeAttributes": { "type": "object", - "description": "The GitBook Staff User info.", + "minProperties": 1, "properties": { - "id": { - "type": "string" + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "searchKey": { - "type": "string" + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "slug": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - }, - "required": ["id", "searchKey"] + } }, - "UserBackOfficeInfo": { + "RevisionPageLinkChangeAttributes": { "type": "object", - "description": "The GitBook User info shown in the BackOffice.", + "minProperties": 1, "properties": { - "id": { - "type": "string" - }, - "riskEvaluation": { - "$ref": "#/components/schemas/UserRiskEvaluation" - }, - "authProviders": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FirebaseUserInfo" - } + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "createdAt": { - "type": "string" + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "lastSignInAt": { - "type": "string" + "target": { + "$ref": "#/components/schemas/ChangeAttributeContentReference" }, - "disabled": { - "type": "boolean" + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - }, - "required": [ - "id", - "riskEvaluation", - "authProviders", - "createdAt", - "lastSignInAt", - "disabled" - ] + } }, - "UserImpersonation": { - "type": "object", - "description": "The info returned when impersonating a GitBook User.", - "allOf": [ + "RevisionSemanticChange": { + "oneOf": [ { - "$ref": "#/components/schemas/UserBackOfficeInfo" + "$ref": "#/components/schemas/RevisionSemanticChangePageCreated" }, { - "type": "object", - "properties": { - "impersonation": { - "$ref": "#/components/schemas/UserImpersonationInfo" - } - }, - "required": ["impersonation"] + "$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/RevisionSemanticChangeCustomFieldsEdited" } ] }, - "UserImpersonationInfo": { + "RevisionSemanticChangeCustomFieldsEdited": { "type": "object", - "description": "The GitBook User impersonation info.", "properties": { - "authURL": { - "type": "string" + "type": { + "type": "string", + "enum": ["custom_fields_edited"] }, - "impersonatorId": { - "type": "string" + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } }, - "required": ["authURL", "impersonatorId"] + "required": ["type", "customFields"] }, - "UserRiskEvaluation": { + "RevisionSemanticChangeFileCreated": { "type": "object", - "description": "The GitBook User risk evaluation.", "properties": { - "wasRisky": { - "description": "True if the user was originally considered as risky", - "type": "boolean" - }, - "isRisky": { - "description": "True if the user is currently considered as risky", - "type": "boolean" - }, - "isVerified": { - "description": "True if the user went through the verification process", - "type": "boolean" - }, - "riskScore": { - "description": "Risk score of the user", - "type": "number" - }, - "completedSteps": { - "description": "Number of verification steps completed by the user", - "type": "number" - }, - "expectedSteps": { - "description": "Total number of verification steps expected", - "type": "number" - }, - "googleLogin": { - "description": "User completed the Google Account verification step", - "type": "boolean" - }, - "githubLogin": { - "description": "User completed the GitHub Account verification step", - "type": "boolean" - }, - "emailVerified": { - "description": "User completed the Email verification step", - "type": "boolean" + "type": { + "type": "string", + "enum": ["file_created"] }, - "activeDaysRemaining": { - "type": "number" + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" } }, - "required": [ - "wasRisky", - "isRisky", - "isVerified", - "riskScore", - "completedSteps", - "expectedSteps", - "googleLogin", - "githubLogin", - "emailVerified", - "activeDaysRemaining" - ] + "required": ["type", "file"] }, - "HiveAccessToken": { + "RevisionSemanticChangeFileDeleted": { "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" - } + "type": { + "type": "string", + "enum": ["file_deleted"] + }, + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" } }, - "required": ["contents"] + "required": ["type", "file"] }, - "UnsplashImage": { + "RevisionSemanticChangeFileEdited": { "type": "object", - "required": ["kind", "id", "description", "downloadLocation", "urls", "author"], "properties": { - "kind": { + "type": { "type": "string", - "enum": ["unsplash_image"] + "enum": ["file_edited"] }, - "id": { - "type": "string" - }, - "description": { - "type": "string" - }, - "downloadLocation": { - "type": "string" - }, - "urls": { - "type": "object", - "properties": { - "full": { - "type": "string" - }, - "small": { - "type": "string" - } - }, - "required": ["full", "small"] + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" }, - "author": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "required": ["name", "url"] + "attributes": { + "$ref": "#/components/schemas/RevisionFileChangeAttributes" } - } + }, + "required": ["type", "file", "attributes"] }, - "APITemporaryToken": { + "RevisionSemanticChangePageCreated": { "type": "object", "properties": { - "token": { + "type": { "type": "string", - "description": "Temporary access token to authenticate with the API" + "enum": ["page_created"] + }, + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" } }, - "required": ["token"] + "required": ["type", "page"] }, - "ContentKitContextBase": { + "RevisionSemanticChangePageDeleted": { "type": "object", - "description": "Common properties for ContentKit context.", "properties": { - "theme": { + "type": { "type": "string", - "enum": ["dark", "light"] + "enum": ["page_deleted"] + }, + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" } }, - "required": ["theme"] + "required": ["type", "page"] }, - "ContentKitContext": { - "description": "Object representing the context in which a ContentKit component is rendered.", - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitContextConfigurationAccount" + "RevisionSemanticChangePageEdited": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_edited"] }, - { - "$ref": "#/components/schemas/ContentKitContextConfigurationSpace" + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" }, - { - "$ref": "#/components/schemas/ContentKitContextDocument" + "attributes": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocumentChangeAttributes" + }, + { + "$ref": "#/components/schemas/RevisionPageGroupChangeAttributes" + }, + { + "$ref": "#/components/schemas/RevisionPageLinkChangeAttributes" + } + ] } - ] + }, + "required": ["type", "page", "attributes"] }, - "ContentKitContextConfigurationAccount": { - "allOf": [ - { - "$ref": "#/components/schemas/ContentKitContextBase" + "RevisionSemanticChangePageMoved": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_moved"] }, - { + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" + }, + "parent": { "type": "object", - "description": "Context while rendering in an account installation's configuration.", "properties": { - "type": { - "type": "string", - "enum": ["configuration_account"] + "before": { + "$ref": "#/components/schemas/ChangedRevisionPage" }, - "organizationId": { - "type": "string", - "description": "ID of the organization the account installation configuration is in." + "after": { + "$ref": "#/components/schemas/ChangedRevisionPage" } - }, - "required": ["type", "organizationId"] + } } + }, + "required": ["type", "page", "parent"] + }, + "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" ] }, - "ContentKitContextConfigurationSpace": { - "allOf": [ - { - "$ref": "#/components/schemas/ContentKitContextBase" + "GitSyncState": { + "type": "object", + "properties": { + "installationProvider": { + "type": "string", + "description": "The provider of the Git Sync installation." }, - { - "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"] - } - ] - }, - "ContentKitContextDocument": { - "allOf": [ - { - "$ref": "#/components/schemas/ContentKitContextBase" + "operation": { + "$ref": "#/components/schemas/GitSyncOperation" }, - { - "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"] + "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" } - ] + } }, - "ContentKitDynamicBinding": { + "GitSyncOperation": { "type": "object", - "description": "Binding between a property and a state value.", "properties": { - "$state": { + "state": { + "$ref": "#/components/schemas/GitSyncOperationState" + }, + "startedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "completedAt": { + "description": "Date when the operation was successful (when state is `success`)", + "$ref": "#/components/schemas/Timestamp" + }, + "error": { "type": "string", - "description": "Key in the state" + "description": "Error details, defined if state is `failure`." } }, - "required": ["$state"] + "required": ["state"] }, - "ContentKitBlock": { + "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"] + }, + "GitSyncCommit": { "type": "object", - "description": "Higher level element to represent a custom block.", "properties": { - "type": { + "oid": { "type": "string", - "enum": ["block"] + "description": "SHA for the commit" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + "message": { + "type": "string", + "description": "Message describing the purpose of the commit" }, - "controls": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitBlockControl" - }, - { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitBlockControl" - } - } - ] - } + "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": ["type", "children"] + "required": ["oid", "message", "createdByGitBook"] }, - "ContentKitBlockControl": { + "GitSyncBlob": { "type": "object", - "description": "Control menu item displayed for the block.", "properties": { - "icon": { - "$ref": "#/components/schemas/ContentKitIcon" - }, - "label": { - "type": "string" - }, - "onPress": { - "$ref": "#/components/schemas/ContentKitAction" + "oid": { + "type": "string", + "description": "SHA for the blob" }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "path": { + "type": "string", + "description": "Path of the blob in the Git tree" } }, - "required": ["label", "onPress"] + "required": ["oid", "path"] }, - "ContentKitButton": { + "Organization": { "type": "object", - "description": "Pressable button triggering an action.", "properties": { - "type": { + "object": { "type": "string", - "enum": ["button"] + "description": "Type of Object, always equals to \"organization\"", + "enum": ["organization"] }, - "style": { + "id": { "type": "string", - "enum": ["primary", "secondary", "danger"] + "description": "Unique identifier for the organization" }, - "onPress": { - "$ref": "#/components/schemas/ContentKitAction" + "title": { + "$ref": "#/components/schemas/OrganizationTitle" }, - "icon": { - "$ref": "#/components/schemas/ContentKitIcon" + "emailDomains": { + "$ref": "#/components/schemas/OrganizationEmailDomains" }, - "trailingIcon": { - "$ref": "#/components/schemas/ContentKitIcon" + "type": { + "$ref": "#/components/schemas/OrganizationType" }, - "label": { - "type": "string" + "useCase": { + "$ref": "#/components/schemas/OrganizationUseCase" }, - "tooltip": { - "type": "string" + "communityType": { + "$ref": "#/components/schemas/OrganizationCommunityType" }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" }, - "disabled": { + "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" + }, + "aiInsights": { + "description": "If true, the organization is configured to run content audits on any space update", "type": "boolean" + }, + "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"] } }, - "required": ["type", "onPress"] + "required": ["object", "id", "title", "type", "emailDomains", "urls"] }, - "ContentKitTextInput": { + "OrganizationType": { + "type": "string", + "enum": ["business", "community"] + }, + "OrganizationTitle": { + "type": "string", + "description": "Name of the organization", + "minLength": 2, + "maxLength": 300 + }, + "OrganizationEmailDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "OrganizationUseCase": { + "type": "string", + "enum": [ + "productDocs", + "teamKnowledgeBase", + "designSystem", + "openSourceDocs", + "notes", + "other" + ] + }, + "OrganizationCommunityType": { + "type": "string", + "enum": ["nonProfit", "openSource", "education"] + }, + "OrganizationExperimentalFeature": { "type": "object", - "description": "Text input to prompt the user.", "properties": { - "type": { - "type": "string", - "enum": ["textinput"] - }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "id": { "type": "string" }, - "initialValue": { - "description": "Text value to initialize the input with.", + "title": { "type": "string" }, - "placeholder": { - "description": "Text that appears in the form control when it has no value set", + "description": { "type": "string" }, - "multiline": { + "enabled": { "type": "boolean" + }, + "stage": { + "type": "string", + "enum": ["alpha", "beta"] } }, - "required": ["type", "state"] + "required": ["id", "title", "description", "enabled", "stage"] }, - "ContentKitText": { + "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": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "OrganizationTransferResponse": { "type": "object", - "description": "Low level text element.", + "required": ["collection"], "properties": { - "type": { + "collection": { "type": "string", - "enum": ["text"] + "description": "The unique id of the collection created in the target organization containing the content of the source organization." }, - "style": { + "newSourceHostname": { "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" - } - ] - } - } - ] + "description": "The new hostname if the source organization needed to change hostname." } - }, - "required": ["type", "children"] + } }, - "ContentKitBox": { + "OrganizationTarget": { "type": "object", + "required": ["organization"], "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" - } + "organization": { + "type": "string" } - }, - "required": ["type", "children"] + } }, - "ContentKitHint": { + "OrganizationMember": { "type": "object", - "description": "Element used to contextualize other elements or info.", "properties": { - "type": { + "object": { "type": "string", - "enum": ["hint"] + "description": "Type of Object, always equals to \"member\"", + "enum": ["member"] }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" - } + "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": ["type", "children"] + "required": [ + "object", + "id", + "role", + "user", + "disabled", + "joinedAt", + "sso", + "spaces", + "teams" + ] }, - "ContentKitHStack": { + "OrganizationTeam": { "type": "object", - "description": "Horizontal stack of boxes.", "properties": { - "type": { + "object": { "type": "string", - "enum": ["hstack"] + "description": "Type of Object, always equals to \"team\"", + "enum": ["team"] }, - "align": { + "id": { "type": "string", - "default": "start", - "enum": ["start", "center", "end"] + "description": "Unique identifier for the team." }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + "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" } }, - "required": ["type", "children"] + "required": ["object", "id", "title", "members", "spaces", "createdAt"] }, - "ContentKitVStack": { + "OrganizationTeamTitle": { + "type": "string", + "description": "Title of the team", + "minLength": 1, + "maxLength": 64 + }, + "TeamMember": { "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" - } + "role": { + "$ref": "#/components/schemas/TeamMemberRole" } }, - "required": ["type", "children"] + "required": ["role"] }, - "ContentKitDivider": { + "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"] + }, + "OrganizationTeamMember": { "type": "object", - "description": "Divider between 2 boxes in a stack.", + "description": "A member of a team in an organization, including its relationship to it", "properties": { - "type": { - "type": "string", - "enum": ["divider"] + "organization": { + "$ref": "#/components/schemas/OrganizationMember" }, - "size": { - "type": "string", - "enum": ["small", "medium", "large"] + "team": { + "$ref": "#/components/schemas/TeamMember" } }, - "required": ["type"] + "required": ["organization", "team"] }, - "ContentKitAction": { - "anyOf": [ + "OrganizationDefaultContent": { + "description": "The default content for the organization", + "oneOf": [ { - "type": "object", - "description": "Custom action to re-render the block.", - "properties": { - "action": { - "type": "string" - } - }, - "additionalProperties": true, - "required": ["action"] + "$ref": "#/components/schemas/SpacePointer" }, { - "$ref": "#/components/schemas/ContentKitDefaultAction" + "$ref": "#/components/schemas/CollectionPointer" } ] }, - "ContentKitDefaultAction": { - "oneOf": [ + "OrganizationInvite": { + "allOf": [ { "type": "object", - "description": "Action to open an overlay modal defined by \"componentId\".", "properties": { - "action": { + "object": { "type": "string", - "enum": ["@ui.modal.open"] + "description": "Type of Object, always equals to \"invite\"", + "enum": ["invite"] }, - "componentId": { - "type": "string" - }, - "props": { - "type": "object" - } - }, - "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": { + "id": { "type": "string", - "enum": ["@ui.modal.close"] - }, - "returnValue": { - "type": "object" + "description": "Unique identifier for the organization invite" } }, - "required": ["action", "returnValue"] + "required": ["object", "id"] }, { - "type": "object", - "description": "Action to open an url.", - "properties": { - "action": { - "type": "string", - "enum": ["@ui.url.open"] + "oneOf": [ + { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The role of the member in the organization" + } + }, + "required": ["role"] }, - "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"] + { + "type": "object", + "properties": { + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The level of the member in the target space" + }, + "space": { + "$ref": "#/components/schemas/Space", + "description": "The space the member has been invited to" + } + }, + "required": ["level", "space"] }, - "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": { - "type": "object" + { + "type": "object", + "properties": { + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The level of the member in the target collection" + }, + "collection": { + "$ref": "#/components/schemas/Collection", + "description": "The collection the member has been invited to" + } + }, + "required": ["level", "collection"] } - }, - "required": ["action", "props"] + ] } ] }, - "ContentKitIcon": { - "type": "string", - "enum": [ - "close", - "edit", - "github", - "gitlab", - "maximize", - "email", - "settings", - "search", - "delete", - "star", - "warning", - "link", - "link-external", - "eye", - "lock" - ] - }, - "ContentKitModal": { + "OrganizationPointer": { "type": "object", - "description": "Overlay modal.", "properties": { "type": { "type": "string", - "enum": ["modal"] + "enum": ["organization"] + }, + "organization": { + "type": "string", + "description": "Unique identifier for the organization" + } + }, + "required": ["type", "organization"] + }, + "Capture": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the capture" }, "title": { - "type": "string" + "$ref": "#/components/schemas/CaptureTitle" }, - "subtitle": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" - } + "context": { + "$ref": "#/components/schemas/CaptureContext" }, - "size": { + "externalId": { "type": "string", - "enum": ["medium", "xlarge", "fullscreen"] + "description": "ID in the original source of the capture." }, - "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" + "externalURL": { + "type": "string", + "format": "uri", + "description": "URL of the source from which the capture originated" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + "createdAt": { + "type": "string", + "format": "date-time" }, - "submit": { - "$ref": "#/components/schemas/ContentKitButton" - } - }, - "required": ["type", "children"] - }, - "ContentKitWebFrame": { - "type": "object", - "description": "Frame for a webpage", - "properties": { - "type": { + "stoppedAt": { "type": "string", - "enum": ["webframe"] + "format": "date-time" }, - "aspectRatio": { - "type": "number", - "description": "Ratio between width and height. Used to size the webframe." + "editedAt": { + "type": "string", + "format": "date-time" }, - "source": { - "type": "object", - "description": "Content to load in the frame.", + "events": { + "description": "Count of events recorded.", "properties": { - "url": { - "type": "string" + "terminal.command": { + "type": "integer" + }, + "speech": { + "type": "integer" + }, + "thread.message": { + "type": "integer" } - }, - "required": ["url"] + } }, - "buttons": { + "contributors": { + "description": "An array of contributors to the capture. The first contributor is the one who triggered the capture (either a user or an integration).", "type": "array", - "description": "Controls button shown as an overlay in a corner of the frame.", + "minItems": 1, "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/Integration" }, { - "$ref": "#/components/schemas/ContentKitDynamicBinding" + "$ref": "#/components/schemas/User" } ] } - } - }, - "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" + "output": { + "description": "Output document for the capture. Is not set when capture is not finished.", + "$ref": "#/components/schemas/Document" }, - "lineNumbers": { - "oneOf": [ - { - "type": "boolean" + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the capture in the API", + "format": "uri" }, - { - "type": "number", - "description": "Line number to start at." + "app": { + "type": "string", + "description": "URL of the capture in the app", + "format": "uri" } - ] + }, + "required": ["location", "app"] + } + }, + "required": [ + "object", + "id", + "title", + "context", + "events", + "createdAt", + "contributors", + "urls" + ] + }, + "CaptureTitle": { + "type": "string", + "description": "Optional title describing the capture", + "maxLength": 100 + }, + "CaptureEvent": { + "oneOf": [ + { + "$ref": "#/components/schemas/CaptureTerminalCommandEvent" }, - "buttons": { - "type": "array", - "description": "Controls button shown as an overlay in a corner of the code block.", - "items": { - "$ref": "#/components/schemas/ContentKitButton" - } + { + "$ref": "#/components/schemas/CaptureSpeechEvent" }, - "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" + { + "$ref": "#/components/schemas/CaptureThreadMessageEvent" }, - "onContentChange": { - "$ref": "#/components/schemas/ContentKitAction" + { + "$ref": "#/components/schemas/CaptureFileAddedEvent" }, - "header": { - "type": "array", - "description": "Header displayed before the code lines", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + { + "$ref": "#/components/schemas/CaptureFileChangedEvent" }, - "footer": { - "type": "array", - "description": "Footer displayed after the code lines", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + { + "$ref": "#/components/schemas/CaptureFileRemovedEvent" } - }, - "required": ["type", "content"] + ] }, - "ContentKitRenderOutput": { - "type": "object", - "description": "Output of the integration when rendering an UI.", - "properties": { - "element": { - "$ref": "#/components/schemas/ContentKitRootElement" - }, - "state": { - "type": "object" - }, - "props": { - "type": "object" + "CaptureContext": { + "oneOf": [ + { + "type": "string", + "enum": ["thread", "walkthrough", "document"] } - }, - "required": ["element", "state", "props"] + ] }, - "ContentKitMarkdown": { + "BaseCaptureEvent": { "type": "object", - "description": "Block with rich text formatting of a markdown content.", "properties": { "type": { "type": "string", - "enum": ["markdown"] + "description": "The type of event" }, - "content": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitDynamicBinding" - }, - { - "type": "string", - "description": "Markdown content to display" + "timestamp": { + "type": "string", + "format": "date-time", + "description": "When the event happened" + }, + "source": { + "type": "string", + "description": "Optionally, provide the source of the event. GitBook may use this to improve the generated content.", + "maxLength": 50 + }, + "actor": { + "type": "object", + "description": "Optionally, provide the actor of the event, in the context of multiple people contributing to the capture.", + "properties": { + "name": { + "type": "string" } - ] + }, + "required": ["name"] } }, - "required": ["type", "content"] + "required": ["type", "timestamp"] }, - "ContentKitCard": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["card"] + "CaptureSpeechEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "title": { - "type": "string" + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["speech"] + } + }, + "required": ["type"] }, - "hint": { + { "oneOf": [ { - "type": "string" + "type": "object", + "properties": { + "audio": { + "description": "WAV audio file, encoded as base64", + "type": "string" + } + }, + "required": ["audio"] }, { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" - } + "type": "object", + "properties": { + "transcript": { + "description": "Transcript of the speech", + "type": "string" + } + }, + "required": ["transcript"] } ] + } + ] + }, + "CaptureTerminalCommandEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "icon": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitIcon" + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["terminal.command"] }, - { - "$ref": "#/components/schemas/ContentKitImage" + "command": { + "type": "string" + }, + "stdout": { + "type": "string" } - ] - }, - "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", "command", "stdout"] } - }, - "required": ["type"] + ] }, - "ContentKitImage": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["image"] + "CaptureThreadMessageEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "source": { + { "type": "object", "properties": { - "url": { + "type": { "type": "string", - "format": "uri" + "enum": ["thread.message"] + }, + "isFirst": { + "type": "boolean" + }, + "text": { + "type": "string" } }, - "required": ["url"] + "required": ["type", "text"] + } + ] + }, + "CaptureFileAddedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "aspectRatio": { - "type": "number" + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file.added"] + }, + "filename": { + "type": "string" + }, + "fileSnapshot": { + "type": "string" + } + }, + "required": ["type", "filename", "fileSnapshot"] } - }, - "required": ["type", "source", "aspectRatio"] + ] }, - "ContentKitLink": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["link"] + "CaptureFileChangedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "target": { + { "type": "object", "properties": { - "url": { - "oneOf": [ - { - "type": "string" - }, - { - "$ref": "#/components/schemas/ContentKitURL" - } - ] + "type": { + "type": "string", + "enum": ["file.changed"] + }, + "filename": { + "type": "string" + }, + "fileDiff": { + "type": "string" } }, - "required": ["url"] + "required": ["type", "filename", "fileDiff"] + } + ] + }, + "CaptureFileRemovedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "children": { - "oneOf": [ - { + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file.removed"] + }, + "filename": { "type": "string" }, - { - "type": "array", - "items": { - "type": "string" - } + "fileSnapshot": { + "type": "string" } - ] + }, + "required": ["type", "filename", "fileSnapshot"] } - }, - "required": ["type", "target", "children"] + ] }, - "ContentKitInput": { + "Snippet": { "type": "object", - "description": "Field for an input.", "properties": { - "type": { + "id": { "type": "string", - "enum": ["input"] + "description": "Unique identifier for the snippet" }, - "label": { + "organization": { "type": "string", - "description": "Text label displayed next to the input." + "description": "ID of the organization owning this snippet" }, - "hint": { - "oneOf": [ - { - "type": "string" - }, - { - "$ref": "#/components/schemas/ContentKitInlineElement" - } - ] + "createdAt": { + "type": "string", + "format": "date-time" }, - "element": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitTextInput" - }, - { - "$ref": "#/components/schemas/ContentKitSelect" - }, - { - "$ref": "#/components/schemas/ContentKitSwitch" + "editedAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp of when the snippet was last edited, if it has been edited since its creation." + }, + "archived": { + "type": "boolean", + "description": "Whether the snippet is archived. Archived snippets don't appear in search results or in the app." + }, + "title": { + "type": "string", + "description": "Title describing the snippet.", + "maxLength": 100 + }, + "source": { + "description": "The source of the snippet.", + "type": "object", + "properties": { + "sourceId": { + "type": "string", + "description": "An ID identifying the source, unique across all sources." }, - { - "$ref": "#/components/schemas/ContentKitRadio" + "name": { + "type": "string", + "description": "A display name for the source." }, - { - "$ref": "#/components/schemas/ContentKitCheckbox" + "externalId": { + "type": "string", + "description": "An ID identifying the snippet in the source system, if available." }, - { - "$ref": "#/components/schemas/ContentKitButton" + "externalUrl": { + "description": "URL of the snippet in the source system, if available.", + "$ref": "#/components/schemas/URL" + } + }, + "required": ["sourceId", "name"] + }, + "contributors": { + "description": "An array of contributors to the snippet, which can be either users or integrations. The first contributor is the one who created the snippet.", + "type": "array", + "minItems": 1, + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/Integration" + }, + { + "$ref": "#/components/schemas/User" + } + ] + } + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "description": "URL of the snippet in the API", + "$ref": "#/components/schemas/URL" }, - { - "$ref": "#/components/schemas/ContentKitCodeBlock" + "app": { + "description": "URL of the snippet in the app", + "$ref": "#/components/schemas/URL" } - ] + }, + "required": ["location", "app"] } }, - "required": ["type", "label", "element"] + "required": [ + "id", + "organization", + "source", + "createdAt", + "archived", + "contributors", + "urls" + ] }, - "ContentKitSelectOption": { + "UpdateSnippetSchema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "A new title for the snippet." + } + } + }, + "SyncedBlock": { "type": "object", - "description": "An individual option in a select element", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the synced block" }, - "label": { - "type": "string" + "organization": { + "type": "string", + "description": "ID of the organization owning this synced block" }, - "icon": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitIcon" - }, - { - "$ref": "#/components/schemas/ContentKitImage" + "createdAt": { + "type": "string", + "format": "date-time" + }, + "title": { + "type": "string", + "description": "Title describing the synced block.", + "maxLength": 100 + }, + "document": { + "$ref": "#/components/schemas/JSONDocument" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "description": "URL of the synced block in the API", + "$ref": "#/components/schemas/URL" } - ] + }, + "required": ["location"] } }, - "required": ["id", "label"] + "required": ["id", "organization", "source", "createdAt", "urls", "document"] }, - "ContentKitSelect": { + "ContentAuditRelation": { "type": "object", - "description": "Creates a drop down menu with a list of options for a user to choose.", + "description": "Content audit relation", "properties": { - "type": { - "type": "string", - "enum": ["select"] - }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "id": { "type": "string" }, - "initialValue": { - "description": "Value to initialize the select with.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - }, - "onValueChange": { - "$ref": "#/components/schemas/ContentKitAction" + "sources": { + "description": "The sources that are related", + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentAuditSource" + } }, - "placeholder": { - "description": "Text that appears in the form control when it has no value set", - "type": "string" + "type": { + "description": "The type of the relation between the sources", + "$ref": "#/components/schemas/ContentAuditRelationType" }, - "multiple": { - "description": "Should the select accept the selection of multiple options. If true, the state will be an array.", - "type": "boolean" + "reason": { + "type": "string", + "description": "A human readable description of the reason for the relation" }, - "acceptInput": { - "description": "Should the filter input be allowed to be selected as an option.", - "type": "boolean" + "status": { + "description": "The status of the relation", + "$ref": "#/components/schemas/ContentAuditRelationStatus" }, - "options": { - "description": "Array of options to display in the select.", - "oneOf": [ - { - "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"] - } - ] + "createdAt": { + "description": "The date at which the relation was created", + "$ref": "#/components/schemas/Timestamp" } }, - "required": ["type", "state", "options"] + "required": ["id", "sources", "type", "status", "createdAt"] }, - "ContentKitSwitch": { + "ContentAuditRelationType": { + "description": "The type of the relation between the sources", + "type": "string", + "enum": ["contradiction", "duplicate"] + }, + "ContentAuditRelationStatus": { + "description": "Status of the audit relation to filter on", + "type": "string", + "enum": ["pending", "rejected"] + }, + "ContentAuditRelationStatusUpdate": { "type": "object", - "description": "Renders a boolean input.", "properties": { + "status": { + "$ref": "#/components/schemas/ContentAuditRelationStatus" + } + }, + "required": ["status"] + }, + "ContentAuditSource": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentAuditSourceSection" + } + ] + }, + "ContentAuditSourceSection": { + "type": "object", + "description": "A GitBook section source", + "properties": { + "id": { + "type": "string" + }, "type": { "type": "string", - "enum": ["switch"] + "enum": ["section"] }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", - "type": "string" + "space": { + "$ref": "#/components/schemas/Space" }, - "initialValue": { - "description": "Value to initialize the switch with.", - "type": "boolean" + "page": { + "$ref": "#/components/schemas/RevisionPageDocument" + } + }, + "required": ["id", "type", "space", "page"] + }, + "ContentReferenceUsage": { + "type": "object", + "properties": { + "status": { + "$ref": "#/components/schemas/ContentReferenceStatus" }, - "onValueChange": { - "$ref": "#/components/schemas/ContentKitAction" + "targetReference": { + "description": "The reference target where a list of pages are pointing at", + "$ref": "#/components/schemas/ContentReferenceResolved" }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "locationReferences": { + "description": "All pages where the target is being referenced.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentReferenceResolved" + } } }, - "required": ["type", "state"] + "required": ["status", "targetReference", "locationReferences"] }, - "ContentKitCheckbox": { + "ContentReferenceResolved": { "type": "object", "properties": { + "text": { + "description": "Text to display to represent the reference", + "type": "string" + }, "type": { + "description": "The type of the content reference", "type": "string", - "enum": ["checkbox"] + "enum": [ + "space", + "page", + "file", + "anchor", + "collection", + "user", + "snippet", + "url", + "synced-block" + ] }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "url": { + "description": "Target in-app url for the reference", "type": "string" }, - "value": { - "description": "Value to store in a state array when the checkbox is selected.", - "oneOf": [ - { - "type": "string" + "extra": { + "type": "object", + "properties": { + "collection": { + "$ref": "#/components/schemas/Collection" }, - { - "type": "number" + "space": { + "$ref": "#/components/schemas/Space" + }, + "page": { + "$ref": "#/components/schemas/RevisionPage" + }, + "anchor": { + "$ref": "#/components/schemas/RevisionPage" + }, + "file": { + "$ref": "#/components/schemas/RevisionFile" + }, + "snippet": { + "$ref": "#/components/schemas/Snippet" + }, + "user": { + "$ref": "#/components/schemas/User" } - ] - }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + } } }, - "required": ["type", "state", "value"] + "required": ["text", "type", "url", "extra"] }, - "ContentKitRadio": { + "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": { - "type": { - "type": "string", - "enum": ["radio"] - }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", - "type": "string" + "total": { + "description": "Total count of links", + "type": "number" }, - "value": { - "description": "Value to store in th state when the checkbox is selected.", - "oneOf": [ - { - "type": "string" + "broken": { + "type": "object", + "properties": { + "total": { + "description": "Count of broken links", + "type": "number" }, - { + "space": { + "description": "Count of broken links in space. When in the context of a change request it refers to the broken links already existing at the time of the change request creation.", + "type": "number" + }, + "changeRequest": { + "description": "Count of broken links that were broken in current change request, if applicable.", "type": "number" } - ] - }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + }, + "required": ["total", "space", "changeRequest"] } }, - "required": ["type", "state", "value"] + "required": ["total", "broken"] }, - "ContentKitConfirm": { + "ChangeRequest": { "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": { + "object": { "type": "string", - "description": "A text value to define the text of the button that confirms the action.", - "maxLength": 30 + "description": "Type of Object, always equals to \"change-request\"", + "enum": ["change-request"] }, - "style": { + "id": { "type": "string", - "enum": ["primary", "danger"] - } - }, - "required": ["title", "text", "confirm"] - }, - "ContentKitRootElement": { - "description": "Element used as root", - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitBlock" - }, - { - "$ref": "#/components/schemas/ContentKitModal" - } - ], - "discriminator": { - "propertyName": "type" - } - }, - "ContentKitDescendantElement": { - "description": "Any element that can be used as children.", - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitButton" - }, - { - "$ref": "#/components/schemas/ContentKitTextInput" - }, - { - "$ref": "#/components/schemas/ContentKitHStack" + "description": "Unique identifier for the change request" }, - { - "$ref": "#/components/schemas/ContentKitVStack" + "number": { + "type": "number", + "description": "Incremental identifier of the change request" }, - { - "$ref": "#/components/schemas/ContentKitBox" + "status": { + "$ref": "#/components/schemas/ChangeRequestStatus" }, - { - "$ref": "#/components/schemas/ContentKitDivider" + "subject": { + "$ref": "#/components/schemas/ChangeRequestSubject" }, - { - "$ref": "#/components/schemas/ContentKitWebFrame" + "createdBy": { + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/schemas/ContentKitCodeBlock" + "createdAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$ref": "#/components/schemas/ContentKitMarkdown" + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$ref": "#/components/schemas/ContentKitCard" + "revision": { + "type": "string", + "description": "ID of the active revision in the change request." }, - { - "$ref": "#/components/schemas/ContentKitImage" + "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", + "revision", + "urls" + ] + }, + "ChangeRequestStatus": { + "type": "string", + "enum": ["draft", "open", "archived", "merged"] + }, + "ChangeRequestReview": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"change-request-review\"", + "enum": ["change-request-review"] }, - { - "$ref": "#/components/schemas/ContentKitInput" + "id": { + "type": "string", + "description": "Unique identifier for the review." }, - { - "$ref": "#/components/schemas/ContentKitSelect" + "revision": { + "type": "string", + "description": "The revision this review was made against." }, - { - "$ref": "#/components/schemas/ContentKitSwitch" + "reviewer": { + "description": "The user who performed the review.", + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/schemas/ContentKitCheckbox" + "requestedBy": { + "description": "The user who requested the review. If undefined, the review was left without a request.", + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/schemas/ContentKitRadio" + "status": { + "description": "The status of the review.", + "$ref": "#/components/schemas/ChangeRequestReviewStatus" }, - { - "$ref": "#/components/schemas/ContentKitText" + "comment": { + "$ref": "#/components/schemas/Comment" }, - { - "$ref": "#/components/schemas/ContentKitHint" + "createdAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$ref": "#/components/schemas/ContentKitLink" + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" } - ], - "discriminator": { - "propertyName": "type" - } + }, + "required": [ + "object", + "id", + "revision", + "reviewer", + "status", + "createdAt", + "updatedAt" + ] }, - "ContentKitInlineElement": { - "description": "Any element that is inline.", - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitText" - }, + "ChangeRequestReviewStatus": { + "type": "string", + "description": "Status of a change request review.", + "enum": ["changes-requested", "approved"] + }, + "ChangeRequestRequestedReviewer": { + "type": "object", + "allOf": [ { - "$ref": "#/components/schemas/ContentKitImage" + "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"] }, { - "$ref": "#/components/schemas/ContentKitLink" - } - ], - "discriminator": { - "propertyName": "type" - } + "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"] + } + ] + } + ] }, - "ContentKitURL": { + "ChangeRequestSubject": { + "type": "string", + "description": "Subject of the change request", + "minLength": 0, + "maxLength": 100 + }, + "UpdateCommentSchema": { "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" + "resolved": { + "type": "boolean", + "description": "Whether the comment is resolved or not." }, - "pathname": { - "type": "string", - "description": "Path of the URL prefixed with a `/`.", - "example": "/v1/options" + "body": { + "description": "Content of the comment.", + "$ref": "#/components/schemas/Document" }, - "query": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "type": "string" - }, - { - "$ref": "#/components/schemas/ContentKitDynamicBinding" - } - ] + "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" } } - }, - "required": ["host", "pathname"] + } }, - "SubscriptionChannel": { - "description": "Channel to subscribe to for API updates.", - "oneOf": [ - { - "$ref": "#/components/schemas/SpaceInfoChannel" - }, - { - "$ref": "#/components/schemas/SpaceGitInfoChannel" - }, - { - "$ref": "#/components/schemas/SpacePublishingAuthChannel" + "UpdateCommentReplySchema": { + "type": "object", + "properties": { + "body": { + "description": "Content of the comment.", + "$ref": "#/components/schemas/Document" }, - { - "$ref": "#/components/schemas/SpaceEntitiesChannel" + "addedReactions": { + "type": "array", + "description": "Reactions to add to the comment.", + "items": { + "type": "string" + } }, - { - "$ref": "#/components/schemas/SpaceCustomFieldsChannel" + "removedReactions": { + "type": "array", + "description": "Reactions to remove from the comment.", + "items": { + "type": "string" + } + } + } + }, + "PostCommentSchema": { + "type": "object", + "properties": { + "node": { + "description": "The node to which the comment is posted, if any.", + "type": "string" }, - { - "$ref": "#/components/schemas/BackofficeUserInfoChannel" + "page": { + "description": "The page to which the comment is posted, if any.", + "type": "string" }, - { - "$ref": "#/components/schemas/SpaceIntegrationsChannel" + "body": { + "description": "The content of the comment.", + "$ref": "#/components/schemas/Document" + } + }, + "required": ["body"] + }, + "PostCommentReplySchema": { + "type": "object", + "properties": { + "body": { + "description": "The content of the comment.", + "$ref": "#/components/schemas/Document" + } + }, + "required": ["body"] + }, + "UserContentPermission": { + "type": "object", + "description": "Permission of a user in a content.", + "properties": { + "permission": { + "$ref": "#/components/schemas/MemberRole" }, - { - "$ref": "#/components/schemas/OrganizationCustomFieldsChannel" + "user": { + "$ref": "#/components/schemas/User" + } + }, + "required": ["permission", "user"] + }, + "MemberContentPermission": { + "type": "object", + "description": "Permission of a member in a content.", + "properties": { + "permission": { + "$ref": "#/components/schemas/MemberRole" }, - { - "$ref": "#/components/schemas/UserAPITokensChannel" + "space": { + "$ref": "#/components/schemas/Space" + } + }, + "required": ["permission", "space"] + }, + "SearchSpaceResult": { + "type": "object", + "description": "Search result representing a space.", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/schemas/UserProfileChannel" + "title": { + "type": "string" }, - { - "$ref": "#/components/schemas/ChangeRequestReviewsChannel" + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchPageResult" + } + } + }, + "required": ["id", "title", "pages"] + }, + "SearchPageResult": { + "type": "object", + "description": "Search result representing a page in a space.", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationMembersChannel" + "title": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationMemberChannel" + "path": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationTeamsChannel" + "sections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchSectionResult" + } }, - { - "$ref": "#/components/schemas/OrganizationTeamChannel" + "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", "urls"] + }, + "SearchSectionResult": { + "type": "object", + "description": "Search result representing a section in a page.", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationTeamMembersChannel" + "title": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationTeamMemberChannel" + "path": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationSpacesChannel" + "body": { + "type": "string" }, - { - "$ref": "#/components/schemas/OrganizationEntitiesChannel" - }, - { - "$ref": "#/components/schemas/OrganizationSchemasChannel" - }, - { - "$ref": "#/components/schemas/OrganizationCapturesChannel" - }, - { - "$ref": "#/components/schemas/OrganizationIntegrationsChannel" - }, - { - "$ref": "#/components/schemas/OrganizationInstallationsChannel" - }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comments"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - } - }, - "required": ["channel", "space"] - }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comment"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" - } - }, - "required": ["channel", "space", "comment"] - }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comment-reply"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" - }, - "commentReply": { - "type": "string" - } - }, - "required": ["channel", "space", "comment", "commentReply"] - }, - { + "urls": { "type": "object", + "description": "URLs associated with the object", "properties": { - "channel": { + "app": { "type": "string", - "enum": ["space-comment-replies"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" + "description": "URL of the section in the application", + "format": "uri" } }, - "required": ["channel", "space", "comment"] - }, - { - "$ref": "#/components/schemas/IntegrationChannel" - }, - { - "$ref": "#/components/schemas/IntegrationInstallationChannel" - }, - { - "$ref": "#/components/schemas/IntegrationSpaceInstallationChannel" - }, - { - "$ref": "#/components/schemas/IntegrationSpaceInstallationsChannel" - } - ], - "discriminator": { - "propertyName": "channel" - } - }, - "SpaceInfoChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space"] - }, - "space": { - "type": "string" + "required": ["app"] } }, - "required": ["channel", "space"] + "required": ["id", "title", "path", "body", "urls"] }, - "SpaceGitInfoChannel": { + "SearchAIQuery": { "type": "object", "properties": { - "channel": { - "type": "string", - "enum": ["space-git-info"] - }, - "space": { + "query": { "type": "string" - } - }, - "required": ["channel", "space"] - }, - "SpacePublishingAuthChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-publishing-auth"] }, - "space": { - "type": "string" + "previousQueries": { + "type": "array", + "deprecated": true, + "maxItems": 10, + "items": { + "type": "string" + } } }, - "required": ["channel", "space"] + "required": ["query"] }, - "SpaceEntitiesChannel": { + "SearchAIAnswer": { "type": "object", + "description": "Answer from AI for a question asked on a content.", "properties": { - "channel": { - "type": "string", - "enum": ["space-entities"] - }, - "space": { + "text": { + "deprecated": true, "type": "string" - } - }, - "required": ["channel", "space"] - }, - "SpaceCustomFieldsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-customfields"] }, - "space": { - "type": "string" - } - }, - "required": ["channel", "space"] - }, - "BackofficeUserInfoChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["backoffice-user-info"] + "answer": { + "$ref": "#/components/schemas/Document" }, - "user": { - "type": "string" - } - }, - "required": ["channel", "user"] - }, - "SpaceIntegrationsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-integrations"] + "followupQuestions": { + "type": "array", + "items": { + "type": "string" + } }, - "space": { - "type": "string" - } - }, - "required": ["channel", "space"] - }, - "UserAPITokensChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["user-api-tokens"] + "sources": { + "type": "array", + "description": "The sources used to generate the answer.", + "items": { + "$ref": "#/components/schemas/SearchAIAnswerSource" + } }, - "user": { - "type": "string" + "pages": { + "type": "array", + "deprecated": true, + "description": "The pages used to generate the answer. Deprecated - use sources instead.", + "items": { + "type": "object", + "properties": { + "page": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "space": { + "type": "string" + }, + "sections": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["page", "revision", "space", "sections"] + } } }, - "required": ["channel", "user"] + "required": ["text", "answer", "pages", "sources", "followupQuestions"] }, - "UserProfileChannel": { + "SearchAIAnswerStream": { "type": "object", "properties": { - "channel": { + "type": { "type": "string", - "enum": ["user-profile"] + "enum": ["answer"] }, - "user": { - "type": "string" + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" } }, - "required": ["channel", "user"] + "required": ["type"] }, - "ChangeRequestReviewsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-change-request-reviews"] - }, - "space": { - "type": "string" + "SearchAIAnswerSource": { + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page", "entity", "capture"] + } + }, + "required": ["type"] }, - "changeRequest": { - "type": "string" + { + "discriminator": { + "propertyName": "type" + }, + "oneOf": [ + { + "type": "object", + "title": "Page", + "properties": { + "type": { + "type": "string", + "enum": ["page"] + }, + "page": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "space": { + "type": "string" + }, + "sections": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["type", "page", "revision", "space", "sections"] + }, + { + "type": "object", + "title": "Entity", + "properties": { + "type": { + "type": "string", + "enum": ["entity"] + }, + "entityId": { + "type": "string", + "description": "ID of the entity" + }, + "entityType": { + "$ref": "#/components/schemas/EntityType" + }, + "integration": { + "description": "The name of the integration that manages this entity. If undefined, this entity is not managed by an integration.", + "type": "string" + } + }, + "required": ["type", "entityId", "entityType"] + }, + { + "type": "object", + "title": "Snippet", + "properties": { + "type": { + "type": "string", + "enum": ["capture"] + }, + "captureId": { + "type": "string", + "description": "ID of the capture" + }, + "source": { + "type": "string", + "description": "Source of the capture" + } + }, + "required": ["type", "captureId", "source"] + } + ] } - }, - "required": ["channel", "space", "changeRequest"] + ] }, - "OrganizationCustomFieldsChannel": { + "SearchAIRecommendedQuestions": { "type": "object", + "description": "Questions recommended by the AI for the given content.", "properties": { - "channel": { - "type": "string", - "enum": ["organization-customfields"] - }, - "organization": { - "type": "string" + "questions": { + "type": "array", + "items": { + "type": "string" + } } }, - "required": ["channel", "organization"] + "required": ["questions"] }, - "OrganizationMembersChannel": { + "SearchAIRecommendedQuestionStream": { "type": "object", "properties": { - "channel": { - "type": "string", - "enum": ["organization-members"] - }, - "organization": { + "question": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["question"] }, - "OrganizationMemberChannel": { + "AnalyticsSearchPeriod": { + "type": "string", + "enum": ["last_month", "last_week", "last_year"] + }, + "AnalyticsSearchQuery": { "type": "object", + "description": "Analytics entry for a search query.", + "required": ["query", "searches", "hits", "pageHits", "sectionHits"], "properties": { - "channel": { - "type": "string", - "enum": ["organization-member"] - }, - "organization": { + "query": { "type": "string" }, - "user": { - "type": "string" - } - }, - "required": ["channel", "organization", "user"] - }, - "OrganizationTeamsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization-teams"] + "searches": { + "description": "Number of searches done by users.", + "type": "number" }, - "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] - }, - "OrganizationTeamChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization-team"] + "hits": { + "description": "Number of objects matching this search.", + "type": "number" }, - "organization": { - "type": "string" + "pageHits": { + "description": "Number of pages matching this search.", + "type": "number" }, - "team": { - "type": "string" + "sectionHits": { + "description": "Number of sections matching this search.", + "type": "number" } - }, - "required": ["channel", "organization", "team"] + } }, - "OrganizationTeamMembersChannel": { + "AnalyticsTopSearches": { "type": "object", + "description": "Top search queries for a content.", + "required": ["searches", "queries"], "properties": { - "channel": { - "type": "string", - "enum": ["organization-team-members"] - }, - "organization": { - "type": "string" + "searches": { + "description": "Number of searches done by users.", + "type": "number" }, - "team": { - "type": "string" + "queries": { + "description": "Top queries searched for this content.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AnalyticsSearchQuery" + } } - }, - "required": ["channel", "organization", "team"] + } }, - "OrganizationTeamMemberChannel": { + "AnalyticsTrafficInterval": { + "type": "string", + "enum": ["daily", "weekly", "monthly"] + }, + "AnalyticsTrafficPageViews": { "type": "object", + "required": ["count", "views"], "properties": { - "channel": { - "type": "string", - "enum": ["organization-team-member"] - }, - "organization": { - "type": "string" - }, - "team": { - "type": "string" + "count": { + "description": "Total number of page views over the period.", + "type": "number" }, - "member": { - "type": "string" + "views": { + "description": "Page views per interval (day, week, month).", + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "string" + }, + "count": { + "type": "number" + } + }, + "required": ["timestamp", "count"] + } } - }, - "required": ["channel", "organization", "member"] + } }, - "OrganizationSpacesChannel": { + "AnalyticsContentPages": { "type": "object", - "description": "Subscription channel for changes in spaces in an organization.", + "required": ["pages"], "properties": { - "channel": { - "type": "string", - "enum": ["organization-spaces"] - }, - "organization": { - "type": "string" + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnalyticsContentPage" + } } - }, - "required": ["channel", "organization"] + } }, - "OrganizationEntitiesChannel": { + "AnalyticsContentPage": { "type": "object", - "description": "Subscription channel for entities in an organization.", + "description": "Page entry in the content analytics.", + "required": ["page", "pageViews"], "properties": { - "channel": { - "type": "string", - "enum": ["organization-entities"] + "page": { + "$ref": "#/components/schemas/RevisionPageDocument" }, - "organization": { - "type": "string" + "pageViews": { + "type": "number" }, - "entityType": { - "type": "string" + "feedbacks": { + "type": "object", + "required": [ + "score", + "total", + "rating", + "ponderedScore", + "bad", + "ok", + "good" + ], + "properties": { + "score": { + "type": "number", + "description": "Score based on each rating (+1 for 'good', -0.5 for 'ok', -2 for 'bad')." + }, + "total": { + "type": "number", + "description": "Total number of ratings done by end users." + }, + "rating": { + "type": "string", + "deprecated": true, + "description": "Summary of the rating based on the score ('good', 'ok', or 'bad')" + }, + "ponderedScore": { + "type": "number", + "description": "Score multiplied by the number of ratings to give more importance to highly rated content." + }, + "bad": { + "type": "number", + "description": "Number of 'bad' ratings." + }, + "ok": { + "type": "number", + "description": "Number of 'ok' ratings." + }, + "good": { + "type": "number", + "description": "Number of 'good' ratings." + } + } } - }, - "required": ["channel", "organization", "entityType"] + } }, - "OrganizationSchemasChannel": { + "Collection": { "type": "object", - "description": "Subscription channel for all entity schemas in an organization.", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-schemas"] + "description": "Type of Object, always equals to \"collection\"", + "enum": ["collection"] }, - "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] - }, - "OrganizationCapturesChannel": { - "type": "object", - "properties": { - "channel": { + "id": { "type": "string", - "enum": ["organization-captures"] + "description": "Unique identifier for the collection" }, - "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] - }, - "OrganizationIntegrationsChannel": { - "type": "object", - "properties": { - "channel": { + "title": { + "$ref": "#/components/schemas/CollectionTitle" + }, + "description": { + "$ref": "#/components/schemas/CollectionDescription" + }, + "path": { "type": "string", - "enum": ["organization-integrations"] + "description": "Path in the published URL" }, - "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] - }, - "OrganizationInstallationsChannel": { - "type": "object", - "properties": { - "channel": { + "visibility": { + "$ref": "#/components/schemas/ContentVisibility" + }, + "publishingType": { "type": "string", - "enum": ["organization-installations"] + "enum": ["variants"] }, "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] - }, - "IntegrationChannel": { - "type": "object", - "properties": { - "channel": { "type": "string", - "enum": ["integration"] + "description": "ID of the organization owning this collection" }, - "integration": { - "type": "string" - } - }, - "required": ["channel", "integration"] - }, - "IntegrationInstallationChannel": { - "type": "object", - "properties": { - "channel": { + "parent": { "type": "string", - "enum": ["integration-installation"] - }, - "integration": { - "type": "string" + "description": "ID of the parent collection, if any" }, - "installation": { - "type": "string" - } - }, - "required": ["channel", "integration", "installation"] - }, - "IntegrationSpaceInstallationChannel": { - "type": "object", - "properties": { - "channel": { + "collection": { "type": "string", - "enum": ["integration-space-installation"] - }, - "integration": { - "type": "string" + "deprecated": true, + "description": "ID of the parent collection, if any" }, - "installation": { - "type": "string" + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" }, - "space": { - "type": "string" + "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"] } }, - "required": ["channel", "integration", "installation", "space"] + "required": [ + "object", + "id", + "title", + "organization", + "visibility", + "urls", + "defaultLevel" + ] }, - "IntegrationSpaceInstallationsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["integration-space-installations"] - }, - "integration": { - "type": "string" - }, - "installation": { - "type": "string" - } - }, - "required": ["channel", "integration", "installation"] + "CollectionTitle": { + "type": "string", + "description": "Title of the collection", + "minLength": 0, + "maxLength": 50 }, - "CustomField": { + "CollectionDescription": { + "type": "string", + "description": "Description of the collection", + "minLength": 0, + "maxLength": 100 + }, + "Integration": { "type": "object", - "description": "Custom field", "properties": { - "id": { - "type": "string" + "object": { + "type": "string", + "enum": ["integration"] }, "name": { - "$ref": "#/components/schemas/CustomFieldName" + "type": "string", + "description": "Unique named identifier for the integration" + }, + "version": { + "type": "number", + "description": "Version of the integration" }, "title": { - "$ref": "#/components/schemas/CustomFieldTitle" + "$ref": "#/components/schemas/IntegrationTitle" }, "description": { - "$ref": "#/components/schemas/CustomFieldDescription" + "$ref": "#/components/schemas/IntegrationDescription" }, - "type": { - "$ref": "#/components/schemas/CustomFieldType" + "summary": { + "$ref": "#/components/schemas/IntegrationSummary" }, - "placeholder": { - "$ref": "#/components/schemas/CustomFieldPlaceholder" + "previewImages": { + "type": "array", + "description": "URLs of images to showcase the integration", + "maxItems": 3, + "items": { + "type": "string" + } }, - "options": { - "$ref": "#/components/schemas/CustomFieldOptions" + "target": { + "$ref": "#/components/schemas/IntegrationTarget" }, - "createdAt": { - "$ref": "#/components/schemas/Date" + "verified": { + "type": "boolean", + "description": "If true, the integration has been verified by the GitBook team" }, - "updatedAt": { - "$ref": "#/components/schemas/Date" + "visibility": { + "$ref": "#/components/schemas/IntegrationVisibility" + }, + "scopes": { + "$ref": "#/components/schemas/IntegrationScopes" + }, + "categories": { + "$ref": "#/components/schemas/IntegrationCategories" + }, + "blocks": { + "$ref": "#/components/schemas/IntegrationBlocks" + }, + "configurations": { + "$ref": "#/components/schemas/IntegrationConfigurations" + }, + "externalLinks": { + "$ref": "#/components/schemas/IntegrationExternalLinks" + }, + "owner": { + "$ref": "#/components/schemas/Organization" }, "urls": { "type": "object", @@ -6807,221 +6889,8714 @@ "properties": { "location": { "type": "string", - "description": "URL of the custom field in the API", + "description": "URL of the integration in the API", "format": "uri" - } - }, - "required": ["location"] - } - }, - "required": [ - "id", - "name", - "title", - "description", - "placeholder", - "type", - "createdAt", - "updatedAt", + }, + "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" ] }, - "CustomFieldName": { + "IntegrationTitle": { "type": "string", - "pattern": "^[a-z_\\-0-9]+$", - "minLength": 1, - "maxLength": 50 + "description": "Title of the integration", + "minLength": 2, + "maxLength": 30 }, - "CustomFieldTitle": { + "IntegrationDescription": { "type": "string", + "description": "Description of the integration", "maxLength": 100 }, - "CustomFieldDescription": { + "IntegrationSummary": { "type": "string", - "maxLength": 200 + "description": "Long form markdown summary of the integration", + "maxLength": 2048 }, - "CustomFieldType": { + "IntegrationScopes": { + "type": "array", + "description": "Permissions that should be granted to the integration", + "items": { + "$ref": "#/components/schemas/IntegrationScope" + } + }, + "IntegrationScope": { "type": "string", - "enum": ["text", "number", "boolean", "tags", "select:multi", "select:single"] + "enum": [ + "entities:write", + "snippets:read", + "capture:write", + "space:views:read", + "space:content:read", + "space:content:write", + "space:metadata:read", + "space:metadata:write", + "space:script:inject", + "space:script:cookies", + "space:git:sync", + "space:visitor:auth", + "site:visitor:auth" + ] }, - "CustomFieldValue": { + "IntegrationSearchQuery": { + "name": "search", + "in": "query", + "description": "A search string to filter integrations by name\n", + "schema": { + "type": "string" + } + }, + "IntegrationCategories": { + "type": "array", + "description": "Categories for which the integration is listed in the marketplace", + "items": { + "$ref": "#/components/schemas/IntegrationCategory" + } + }, + "IntegrationBlockMarkdown": { "oneOf": [ { - "type": "string", - "maxLength": 256 + "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"] + } + ] + }, + "IntegrationBlocks": { + "type": "array", + "description": "Custom blocks defined by this integration.", + "items": { + "$ref": "#/components/schemas/IntegrationBlock" + } + }, + "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"] + }, + "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"] + } + }, + "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" + } + } + } + }, + "IntegrationInstallationSpaceSelection": { + "type": "string", + "description": "Describe whether all spaces have been selected or there's a selection involved", + "enum": ["all", "selected"] + }, + "IntegrationCategory": { + "type": "string", + "enum": [ + "analytics", + "captures", + "collaboration", + "content", + "gitsync", + "marketing", + "other" + ] + }, + "IntegrationConfigurations": { + "type": "object", + "properties": { + "account": { + "$ref": "#/components/schemas/IntegrationConfiguration" + }, + "space": { + "$ref": "#/components/schemas/IntegrationConfiguration" + } + } + }, + "IntegrationConfiguration": { + "oneOf": [ + { + "$ref": "#/components/schemas/IntegrationConfigurationSchema" + }, + { + "$ref": "#/components/schemas/IntegrationConfigurationComponent" + } + ] + }, + "IntegrationConfigurationSchema": { + "type": "object", + "description": "Schema for a configuration", + "properties": { + "properties": { + "type": "object", + "additionalProperties": { + "allOf": [ + { + "type": "object", + "properties": { + "title": { + "type": "string", + "maxLength": 30 + }, + "description": { + "type": "string", + "maxLength": 100 + } + } + }, + { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["string"] + }, + "default": { + "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"] + }, + "IntegrationConfigurationComponent": { + "type": "object", + "description": "ContentKit component for configuration", + "properties": { + "componentId": { + "type": "string", + "description": "ID of the ContentKit component defined in the integration" + } + }, + "required": ["componentId"] + }, + "IntegrationVisibility": { + "type": "string", + "enum": ["public", "private", "unlisted"] + }, + "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" + }, + "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" + } + }, + "required": [ + "id", + "status", + "space_selection", + "spaces", + "configuration", + "urls", + "externalIds", + "target", + "createdAt", + "updatedAt" + ] + }, + "IntegrationSpaceInstallation": { + "type": "object", + "description": "Installation of an integration at a space level", + "properties": { + "integration": { + "description": "Unique name identifier of the integration", + "type": "string" + }, + "installation": { + "description": "ID of the integration installation", + "type": "string" + }, + "space": { + "description": "ID of the space the integration is installed on.", + "type": "string" + }, + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + }, + "configuration": { + "description": "Configuration of the integration for this space", + "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 space installation in the API", + "format": "uri" + }, + "publicEndpoint": { + "type": "string", + "description": "Public HTTP endpoint for the integration's space installation", + "format": "uri" + } + }, + "required": ["location", "publicEndpoint"] + } + }, + "required": [ + "integration", + "installation", + "space", + "status", + "configuration", + "externalIds", + "urls" + ] + }, + "IntegrationSiteInstallation": { + "type": "object", + "description": "Installation of an integration at a site level", + "properties": { + "integration": { + "description": "Unique name identifier of the integration", + "type": "string" + }, + "installation": { + "description": "ID of the integration installation", + "type": "string" + }, + "site": { + "description": "ID of the site the integration is installed on.", + "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 site installation in the API", + "format": "uri" + }, + "publicEndpoint": { + "type": "string", + "description": "Public HTTP endpoint for the integration's site installation", + "format": "uri" + } + }, + "required": ["location", "publicEndpoint"] + } + }, + "required": [ + "integration", + "installation", + "site", + "status", + "configuration", + "externalIds", + "urls" + ] + }, + "IntegrationInstallationStatus": { + "type": "string", + "enum": ["active", "pending", "paused"] + }, + "IntegrationSecrets": { + "type": "object", + "description": "Secrets stored on the integration and passed at runtime.", + "properties": {}, + "maxProperties": 20, + "additionalProperties": { + "type": "string" + } + }, + "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/IntegrationSpaceInstallation" + }, + "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." + } + }, + "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"] + } + }, + "required": ["apiEndpoint", "apiTokens", "integration", "signingSecrets", "secrets"] + }, + "IntegrationTarget": { + "type": "string", + "enum": ["organization", "all"] + }, + "IntegrationInstallationTarget": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationTarget" + } + ] + }, + "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" + } + }, + "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" + } + } + } + ] + }, + "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" + } + } + } + } + }, + "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"] + }, + "UpsertEntity": { + "type": "object", + "description": "Entity to create or update in an integration's installation.", + "properties": { + "entityId": { + "$ref": "#/components/schemas/EntityId" + }, + "properties": { + "type": "object", + "description": "Map of values stored as properties on the entity", + "additionalProperties": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "object", + "properties": { + "entityId": { + "type": "string" + } + }, + "required": ["entityId"] + } + ] + } + } + }, + "required": ["entityId", "properties"] + }, + "Entity": { + "allOf": [ + { + "$ref": "#/components/schemas/UpsertEntity" + }, + { + "type": "object", + "description": "Entity created and managed by an integration, representing an external element.", + "properties": { + "id": { + "type": "string", + "description": "Unique ID for the entity in GitBook" + }, + "type": { + "deprecated": true, + "description": "Type of an entity. Deprecated, use entityType.", + "$ref": "#/components/schemas/EntityType" + }, + "entityType": { + "$ref": "#/components/schemas/EntityType" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the entity in the API", + "format": "uri" + } + }, + "required": ["location"] + } + }, + "required": ["id", "type", "entityType", "urls"] + } + ] + }, + "EntityType": { + "type": "string", + "description": "Type of an entity", + "minLength": 1, + "maxLength": 64 + }, + "EntityId": { + "type": "string", + "description": "Unique ID of the entity in the context of the integration's entity type", + "minLength": 1, + "maxLength": 256 + }, + "EntitySchemaTitle": { + "type": "string", + "maxLength": 50 + }, + "EntityRawSchema": { + "type": "object", + "description": "Schema for a type of entities", + "properties": { + "type": { + "$ref": "#/components/schemas/EntityType" + }, + "title": { + "type": "object", + "description": "Title of the entity type", + "properties": { + "singular": { + "$ref": "#/components/schemas/EntitySchemaTitle" + }, + "plural": { + "$ref": "#/components/schemas/EntitySchemaTitle" + } + }, + "required": ["singular", "plural"] + }, + "properties": { + "type": "array", + "description": "Ordered list of all properties stored in entities.", + "items": { + "$ref": "#/components/schemas/EntityPropertySchema" + } + } + }, + "required": ["type", "title", "properties"] + }, + "EntitySchema": { + "allOf": [ + { + "$ref": "#/components/schemas/EntityRawSchema" + }, + { + "type": "object", + "properties": { + "entities": { + "description": "Count of entities created in this schema.", + "type": "number" + }, + "integration": { + "description": "Integration managing this schema.", + "$ref": "#/components/schemas/Integration" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the entity schema in the API", + "format": "uri" + } + }, + "required": ["location"] + } + }, + "required": ["entities", "urls"] + } + ] + }, + "EntityPropertySchema": { + "allOf": [ + { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the property in the object" + }, + "title": { + "type": "string", + "description": "Title displayed to the users" + }, + "description": { + "type": "string", + "description": "Description of the property" + }, + "deprecated": { + "type": "boolean", + "description": "If true, the property is no longer required and not taken into consideration" + } + }, + "required": ["name", "title"] + }, + { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["text"] + }, + "role": { + "type": "string", + "enum": ["title"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["longtext"] + }, + "role": { + "type": "string", + "enum": ["body"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["url"] + }, + "role": { + "type": "string", + "enum": ["target", "icon"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["number"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["boolean"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["enum"] + }, + "values": { + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "required": ["label", "value"] + } + } + }, + "required": ["type", "values"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["date"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["user"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "description": "reference to another entity, creating a relation", + "properties": { + "type": { + "type": "string", + "enum": ["relation"] + }, + "entity": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/EntityType" + } + }, + "required": ["type"] + } + }, + "required": ["type", "entity"] + } + ] + } + ] + }, + "Event": { + "description": "Any event that can be received from GitBook.", + "oneOf": [ + { + "$ref": "#/components/schemas/InstallationSetupEvent" + }, + { + "$ref": "#/components/schemas/SpaceInstallationSetupEvent" + }, + { + "$ref": "#/components/schemas/SpaceInstallationDeletedEvent" + }, + { + "$ref": "#/components/schemas/SpaceViewEvent" + }, + { + "$ref": "#/components/schemas/SpaceContentUpdatedEvent" + }, + { + "$ref": "#/components/schemas/SpaceGitSyncCompletedEvent" + }, + { + "$ref": "#/components/schemas/SpaceGitSyncStartedEvent" + }, + { + "$ref": "#/components/schemas/SpaceVisibilityUpdatedEvent" + }, + { + "$ref": "#/components/schemas/FetchEvent" + }, + { + "$ref": "#/components/schemas/FetchPublishedScriptEvent" + }, + { + "$ref": "#/components/schemas/FetchVisitorAuthenticationEvent" + }, + { + "$ref": "#/components/schemas/UIRenderEvent" + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "SpaceViewEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/SpaceEvent" + }, + { + "type": "object", + "description": "Event received when a page has been visited.", + "properties": { + "type": { + "type": "string", + "enum": ["space_view"] + }, + "pageId": { + "type": "string", + "description": "Unique identifier of the visited 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" + } + }, + "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"] + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "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" + }, + "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/SpaceEvent" + }, + { + "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/SpaceEvent" + }, + { + "type": "object", + "description": "Common properties for all events related to visitor authentication from an installation", + "properties": { + "type": { + "type": "string", + "enum": ["fetch_visitor_authentication"] + }, + "location": { + "type": "string" + } + }, + "required": ["type"] + } + ] + }, + "UIRenderEvent": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/SpaceEvent" + }, + { + "$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"] + } + ] + }, + "BillingInterval": { + "type": "string", + "description": "Interval for a billing subscription", + "enum": ["monthly", "yearly"] + }, + "BillingPortal": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL to the billing portal for an organization" + } + }, + "required": ["url"] + }, + "BillingProduct": { + "type": "string", + "description": "Name of the product", + "enum": [ + "free", + "plus", + "pro", + "team", + "business", + "legacy", + "startup", + "enterprise" + ] + }, + "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"] + } + ] + }, + "BillingInvoicePreview": { + "type": "object", + "properties": { + "amount": { + "description": "Amount of the invoice", + "type": "number" + }, + "amountDueToday": { + "description": "Amount that will be immediately charged.", + "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"] + } + } + }, + "required": [ + "amount", + "amountDueToday", + "customerBalance", + "remainingCustomerBalance", + "lines" + ] + }, + "APIIntegrationScope": { + "type": "string", + "enum": [ + "integration:read", + "integration:update", + "integration:installation:read", + "integration:installation:update" + ] + }, + "APIScope": { + "anyOf": [ + { + "$ref": "#/components/schemas/IntegrationScope" + }, + { + "$ref": "#/components/schemas/APIIntegrationScope" + } + ] + }, + "CloudflareHostnameStatus": { + "type": "string", + "description": "The Cloudflare Hostname status", + "enum": ["pending", "active", "blocked", "moved", "deleted"] + }, + "CloudflareHostnameTLSCertificate": { + "type": "object", + "description": "The Cloudflare Hostname TLS certificate", + "properties": { + "issuer": { + "type": "string" + }, + "expiresOn": { + "type": "string" + }, + "issuedOn": { + "type": "string" + } + } + }, + "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"] + }, + "CloudflareHostnameTLSStatus": { + "type": "string", + "description": "The Cloudflare Hostname TLS status", + "enum": [ + "initializing", + "pending_validation", + "pending_issuance", + "pending_deployment", + "active", + "pending_deletion", + "pending_cleanup", + "deleted" + ] + }, + "CloudflareHostnameTLSValidationError": { + "type": "object", + "description": "The Cloudflare Hostname TLS validation error", + "properties": { + "message": { + "type": "string" + } + }, + "required": ["message"] + }, + "CloudflareHostnameTLSValidationMethod": { + "type": "string", + "description": "The Cloudflare Hostname TLS validation method", + "enum": ["http", "txt", "email"] + }, + "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"] + }, + "PurgeCDNCacheContextType": { + "type": "string", + "description": "The type of purge, e.g by tags or hosts", + "enum": ["tags", "hosts"] + }, + "StaffUserInfo": { + "type": "object", + "description": "The GitBook Staff User info.", + "properties": { + "id": { + "type": "string" + }, + "searchKey": { + "type": "string" + } + }, + "required": ["id", "searchKey"] + }, + "UserBackOfficeInfo": { + "type": "object", + "description": "The GitBook User info shown in the BackOffice.", + "properties": { + "id": { + "type": "string" + }, + "riskEvaluation": { + "$ref": "#/components/schemas/UserRiskEvaluation" + }, + "authProviders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FirebaseUserInfo" + } + }, + "createdAt": { + "type": "string" + }, + "lastSignInAt": { + "type": "string" + }, + "disabled": { + "type": "boolean" + } + }, + "required": [ + "id", + "riskEvaluation", + "authProviders", + "createdAt", + "lastSignInAt", + "disabled" + ] + }, + "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"] + } + ] + }, + "UserImpersonationInfo": { + "type": "object", + "description": "The GitBook User impersonation info.", + "properties": { + "authURL": { + "type": "string" + }, + "impersonatorId": { + "type": "string" + } + }, + "required": ["authURL", "impersonatorId"] + }, + "UserPermissions": { + "type": "object", + "description": "All the permissions of a user", + "properties": { + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "searchKey": { + "type": "string" + }, + "organizations": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The organizations permissions of a user", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "teams": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The teams permissions of a user", + "properties": { + "role": { + "$ref": "#/components/schemas/TeamMemberRole" + } + }, + "required": ["role"] + }, + "required": ["role"] + }, + "disabled": { + "type": "boolean" + } + }, + "required": ["role", "teams"] + } + }, + "collections": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The collections permissions of a user", + "properties": { + "organization": { + "type": "string" + }, + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "collection": { + "type": "string" + } + }, + "required": ["organization", "level"] + } + }, + "spaces": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The spaces permissions of a user", + "properties": { + "organization": { + "type": "string" + }, + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "collection": { + "type": "string" + } + }, + "required": ["organization", "level"] + } + } + }, + "required": ["updatedAt", "searchKey", "organizations", "collections", "spaces"] + }, + "UserRiskEvaluation": { + "type": "object", + "description": "The GitBook User risk evaluation.", + "properties": { + "wasRisky": { + "description": "True if the user was originally considered as risky", + "type": "boolean" + }, + "isRisky": { + "description": "True if the user is currently considered as risky", + "type": "boolean" + }, + "isVerified": { + "description": "True if the user went through the verification process", + "type": "boolean" + }, + "riskScore": { + "description": "Risk score of the user", + "type": "number" + }, + "completedSteps": { + "description": "Number of verification steps completed by the user", + "type": "number" + }, + "expectedSteps": { + "description": "Total number of verification steps expected", + "type": "number" + }, + "googleLogin": { + "description": "User completed the Google Account verification step", + "type": "boolean" + }, + "githubLogin": { + "description": "User completed the GitHub Account verification step", + "type": "boolean" + }, + "emailVerified": { + "description": "User completed the Email verification step", + "type": "boolean" + }, + "activeDaysRemaining": { + "type": "number" + } + }, + "required": [ + "wasRisky", + "isRisky", + "isVerified", + "riskScore", + "completedSteps", + "expectedSteps", + "googleLogin", + "githubLogin", + "emailVerified", + "activeDaysRemaining" + ] + }, + "SpaceBlockReason": { + "type": "string", + "description": "Reason for a space to be blocked", + "enum": [ + "DMCA", + "THREAT_TYPE_UNSPECIFIED", + "MALWARE", + "SOCIAL_ENGINEERING", + "UNWANTED_SOFTWARE" + ] + }, + "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"] + }, + "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"] + } + } + }, + "APITemporaryToken": { + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "Temporary access token to authenticate with the API" + } + }, + "required": ["token"] + }, + "ContentKitContextBase": { + "type": "object", + "description": "Common properties for ContentKit context.", + "properties": { + "theme": { + "type": "string", + "enum": ["dark", "light"] + } + }, + "required": ["theme"] + }, + "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/ContentKitContextDocument" + } + ] + }, + "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"] + } + ] + }, + "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"] + } + ] + }, + "ContentKitDynamicBinding": { + "type": "object", + "description": "Binding between a property and a state value.", + "properties": { + "$state": { + "type": "string", + "description": "Key in the state" + } + }, + "required": ["$state"] + }, + "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"] + }, + "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"] + }, + "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"], + "default": "text" + } + }, + "required": ["type", "state"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "ContentKitAction": { + "anyOf": [ + { + "type": "object", + "description": "Custom action to re-render the block.", + "properties": { + "action": { + "type": "string" + } + }, + "additionalProperties": true, + "required": ["action"] + }, + { + "$ref": "#/components/schemas/ContentKitDefaultAction" + } + ] + }, + "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": { + "type": "object" + } + }, + "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": { + "type": "object" + } + }, + "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": { + "type": "object" + } + }, + "required": ["action", "props"] + } + ] + }, + "ContentKitIcon": { + "type": "string", + "enum": [ + "close", + "edit", + "github", + "gitlab", + "maximize", + "email", + "settings", + "search", + "delete", + "star", + "warning", + "link", + "link-external", + "eye", + "lock" + ] + }, + "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"] + }, + "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"] + }, + "ContentKitRenderOutput": { + "type": "object", + "description": "Output of the integration when rendering an UI.", + "properties": { + "element": { + "$ref": "#/components/schemas/ContentKitRootElement" + }, + "state": { + "type": "object" + }, + "props": { + "type": "object" + } + }, + "required": ["element", "state", "props"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "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": "Array of options to display in the select.", + "oneOf": [ + { + "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"] + }, + "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"] + }, + "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"] + }, + "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"] + }, + "ContentKitRootElement": { + "description": "Element used as root", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitBlock" + }, + { + "$ref": "#/components/schemas/ContentKitModal" + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "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" + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "ContentKitInlineElement": { + "description": "Any element that is inline.", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitText" + }, + { + "$ref": "#/components/schemas/ContentKitImage" + }, + { + "$ref": "#/components/schemas/ContentKitLink" + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "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"] + }, + "SubscriptionChannel": { + "description": "Channel to subscribe to for API updates.", + "oneOf": [ + { + "$ref": "#/components/schemas/SpaceInfoChannel" + }, + { + "$ref": "#/components/schemas/SpaceGitInfoChannel" + }, + { + "$ref": "#/components/schemas/SpacePublishingAuthChannel" + }, + { + "$ref": "#/components/schemas/SpacePublishingCustomizationChannel" + }, + { + "$ref": "#/components/schemas/SpaceEntitiesChannel" + }, + { + "$ref": "#/components/schemas/SpaceCustomFieldsChannel" + }, + { + "$ref": "#/components/schemas/BackofficeUserInfoChannel" + }, + { + "$ref": "#/components/schemas/SpaceIntegrationsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationCustomFieldsChannel" + }, + { + "$ref": "#/components/schemas/UserAPITokensChannel" + }, + { + "$ref": "#/components/schemas/UserOrganizationsChannel" + }, + { + "$ref": "#/components/schemas/UserProfileChannel" + }, + { + "$ref": "#/components/schemas/ChangeRequestChannel" + }, + { + "$ref": "#/components/schemas/ChangeRequestsChannel" + }, + { + "$ref": "#/components/schemas/ChangeRequestReviewsChannel" + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request-broken-links"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + } + }, + "required": ["channel", "space", "changeRequest"] + }, + { + "$ref": "#/components/schemas/CollectionChannel" + }, + { + "$ref": "#/components/schemas/CollectionPublishingCustomizationChannel" + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + { + "$ref": "#/components/schemas/OrganizationMembersChannel" + }, + { + "$ref": "#/components/schemas/OrganizationMemberChannel" + }, + { + "$ref": "#/components/schemas/OrganizationTeamsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationTeamChannel" + }, + { + "$ref": "#/components/schemas/OrganizationTeamMembersChannel" + }, + { + "$ref": "#/components/schemas/OrganizationTeamMemberChannel" + }, + { + "$ref": "#/components/schemas/OrganizationSpacesChannel" + }, + { + "$ref": "#/components/schemas/OrganizationCollectionsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationEntitiesChannel" + }, + { + "$ref": "#/components/schemas/OrganizationSchemasChannel" + }, + { + "$ref": "#/components/schemas/OrganizationCapturesChannel" + }, + { + "$ref": "#/components/schemas/OrganizationContentAuditsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationIntegrationsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationInstallationsChannel" + }, + { + "$ref": "#/components/schemas/OrganizationSitesChannel" + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-experimental-features"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + { + "$ref": "#/components/schemas/OrganizationSyncedBlockChannel" + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comments"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + }, + "comment": { + "type": "string" + } + }, + "required": ["channel", "space", "comment"] + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment-reply"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + }, + "comment": { + "type": "string" + }, + "commentReply": { + "type": "string" + } + }, + "required": ["channel", "space", "comment", "commentReply"] + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment-replies"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + }, + "comment": { + "type": "string" + } + }, + "required": ["channel", "space", "comment"] + }, + { + "$ref": "#/components/schemas/IntegrationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationInstallationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSpaceInstallationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSpaceInstallationsChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSiteInstallationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSiteInstallationsChannel" + }, + { + "$ref": "#/components/schemas/SiteChannel" + }, + { + "$ref": "#/components/schemas/SiteSpaceChannel" + }, + { + "$ref": "#/components/schemas/SiteSpacesChannel" + }, + { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-publishing-auth"] + }, + "site": { + "type": "string" + } + }, + "required": ["channel", "site"] + }, + { + "$ref": "#/components/schemas/CustomHostnameChannel" + } + ], + "discriminator": { + "propertyName": "channel" + } + }, + "SpaceInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpaceGitInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-git-info"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpacePublishingAuthChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-publishing-auth"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpacePublishingCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-publishing-customization"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpaceEntitiesChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-entities"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpaceCustomFieldsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-customfields"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "BackofficeUserInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["backoffice-user-info"] + }, + "user": { + "type": "string" + } + }, + "required": ["channel", "user"] + }, + "SpaceIntegrationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-integrations"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "UserAPITokensChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-api-tokens"] + }, + "user": { + "type": "string" + } + }, + "required": ["channel", "user"] + }, + "UserOrganizationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-organizations"] + }, + "user": { + "type": "string" + } + }, + "required": ["channel", "user"] + }, + "UserProfileChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-profile"] + }, + "user": { + "type": "string" + } + }, + "required": ["channel", "user"] + }, + "CollectionChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["collection"] + }, + "collection": { + "type": "string" + } + }, + "required": ["channel", "collection"] + }, + "CollectionPublishingCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["collection-publishing-customization"] + }, + "collection": { + "type": "string" + } + }, + "required": ["channel", "collection"] + }, + "ChangeRequestChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + } + }, + "required": ["channel", "space", "changeRequest"] + }, + "ChangeRequestsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-requests"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "ChangeRequestReviewsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request-reviews"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + } + }, + "required": ["channel", "space", "changeRequest"] + }, + "OrganizationCustomFieldsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-customfields"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationMembersChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-members"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationMemberChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-member"] + }, + "organization": { + "type": "string" + }, + "user": { + "type": "string" + } + }, + "required": ["channel", "organization", "user"] + }, + "OrganizationTeamsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-teams"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationTeamChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team"] + }, + "organization": { + "type": "string" + }, + "team": { + "type": "string" + } + }, + "required": ["channel", "organization", "team"] + }, + "OrganizationSyncedBlockChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-synced-block"] + }, + "organization": { + "type": "string" + }, + "syncedBlock": { + "type": "string" + } + }, + "required": ["channel", "organization", "syncedBlock"] + }, + "OrganizationTeamMembersChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team-members"] + }, + "organization": { + "type": "string" + }, + "team": { + "type": "string" + } + }, + "required": ["channel", "organization", "team"] + }, + "OrganizationTeamMemberChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team-member"] + }, + "organization": { + "type": "string" + }, + "team": { + "type": "string" + }, + "member": { + "type": "string" + } + }, + "required": ["channel", "organization", "member"] + }, + "OrganizationSpacesChannel": { + "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"] + }, + "OrganizationCollectionsChannel": { + "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"] + }, + "OrganizationEntitiesChannel": { + "type": "object", + "description": "Subscription channel for entities in an organization.", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-entities"] + }, + "organization": { + "type": "string" + }, + "entityType": { + "type": "string" + } + }, + "required": ["channel", "organization", "entityType"] + }, + "OrganizationSchemasChannel": { + "type": "object", + "description": "Subscription channel for all entity schemas in an organization.", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-schemas"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationCapturesChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-captures"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationContentAuditsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-content-audits"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationIntegrationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-integrations"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-installations"] + }, + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationSitesChannel": { + "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"] + }, + "IntegrationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration"] + }, + "integration": { + "type": "string" + } + }, + "required": ["channel", "integration"] + }, + "IntegrationInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-installation"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation"] + }, + "IntegrationSpaceInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-space-installation"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation", "space"] + }, + "IntegrationSpaceInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-space-installations"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation"] + }, + "IntegrationSiteInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-site-installation"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + }, + "site": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation", "site"] + }, + "IntegrationSiteInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-site-installations"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation"] + }, + "SiteChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site"] + }, + "site": { + "type": "string" + } + }, + "required": ["channel", "site"] + }, + "SiteSpaceChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-space"] + }, + "site": { + "type": "string" + }, + "siteSpace": { + "type": "string" + } + }, + "required": ["channel", "site", "siteSpace"] + }, + "SiteSpacesChannel": { + "type": "object", + "description": "Subscription channel for changes in site spaces in an organization.", + "properties": { + "channel": { + "type": "string", + "enum": ["site-spaces"] + }, + "site": { + "type": "string" + } + }, + "required": ["channel", "site"] + }, + "CustomHostnameChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["custom-hostname"] + }, + "customHostname": { + "type": "string" + } + }, + "required": ["channel", "customHostname"] + }, + "CustomField": { + "type": "object", + "description": "Custom field", + "properties": { + "id": { + "type": "string" + }, + "name": { + "$ref": "#/components/schemas/CustomFieldName" + }, + "title": { + "$ref": "#/components/schemas/CustomFieldTitle" + }, + "description": { + "$ref": "#/components/schemas/CustomFieldDescription" + }, + "type": { + "$ref": "#/components/schemas/CustomFieldType" + }, + "placeholder": { + "$ref": "#/components/schemas/CustomFieldPlaceholder" + }, + "options": { + "$ref": "#/components/schemas/CustomFieldOptions" + }, + "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 custom field in the API", + "format": "uri" + } + }, + "required": ["location"] + } + }, + "required": [ + "id", + "name", + "title", + "description", + "placeholder", + "type", + "createdAt", + "updatedAt", + "urls" + ] + }, + "CustomFieldName": { + "type": "string", + "pattern": "^[a-z_\\-0-9]+$", + "minLength": 1, + "maxLength": 50 + }, + "CustomFieldTitle": { + "type": "string", + "maxLength": 100 + }, + "CustomFieldDescription": { + "type": "string", + "maxLength": 200 + }, + "CustomFieldType": { + "type": "string", + "enum": ["text", "number", "boolean", "tags", "select:multi", "select:single"] + }, + "CustomFieldValue": { + "oneOf": [ + { + "type": "string", + "maxLength": 256 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 256 + } + } + ] + }, + "CustomFieldValues": { + "type": "array", + "items": { + "type": "object", + "properties": { + "customField": { + "$ref": "#/components/schemas/CustomField" + }, + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } + }, + "required": ["customField"] + } + }, + "UpdateCustomFieldValues": { + "type": "object", + "properties": { + "values": { + "type": "object", + "additionalProperties": { + "type": "object", + "maxProperties": 100, + "minProperties": 1, + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } + }, + "required": ["value"] + } + } + }, + "required": ["values"] + }, + "CustomFieldOptions": { + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 40 + } + }, + "CustomFieldPlaceholder": { + "type": "string", + "maxLength": 100 + }, + "CustomizationSettings": { + "type": "object", + "properties": { + "inherit": { + "type": "boolean", + "description": "Inherit customization settings from the parent collection." + }, + "title": { + "type": "string", + "description": "Title to use for the published content. If not defined, it'll fallback to the content title." + }, + "styling": { + "type": "object", + "properties": { + "primaryColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "corners": { + "$ref": "#/components/schemas/CustomizationCorners" + }, + "font": { + "$ref": "#/components/schemas/CustomizationFont" + }, + "background": { + "$ref": "#/components/schemas/CustomizationBackground" + } + }, + "required": ["primaryColor", "corners", "font"] + }, + "internationalization": { + "type": "object", + "properties": { + "locale": { + "$ref": "#/components/schemas/CustomizationLocale" + }, + "inherit": { + "type": "boolean", + "description": "Inherit locale from the parent collection." + } + }, + "required": ["locale", "inherit"] + }, + "favicon": { + "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 + } + ] + }, + "header": { + "type": "object", + "properties": { + "preset": { + "$ref": "#/components/schemas/CustomizationHeaderPreset" + }, + "logo": { + "$ref": "#/components/schemas/CustomizationThemedURL" + }, + "backgroundColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "linkColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationHeaderLink" + } + } + }, + "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"] + }, + "themes": { + "type": "object", + "properties": { + "default": { + "$ref": "#/components/schemas/CustomizationThemeMode" + }, + "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 content." + } + }, + "required": ["enabled"] + }, + "feedback": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, feedback gathering is enabled" + } + }, + "required": ["enabled"] + }, + "aiSearch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, AI search is enabled" + } + }, + "required": ["enabled"] + }, + "git": { + "type": "object", + "properties": { + "showEditLink": { + "type": "boolean", + "description": "Whether the public content should show a link to edit the content on the git provider set up in the GitSync" + } + }, + "required": ["showEditLink"] + }, + "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" + } + } + } + }, + "required": [ + "inherit", + "styling", + "internationalization", + "favicon", + "header", + "footer", + "themes", + "pdf", + "feedback", + "aiSearch", + "trademark", + "pagination", + "git", + "privacyPolicy", + "socialPreview" + ] + }, + "CustomizationCollectionSettings": { + "allOf": [ + { + "$ref": "#/components/schemas/CustomizationSettings" + }, + { + "type": "object", + "properties": { + "collection": { + "type": "object", + "properties": { + "defaultSpace": { + "type": "string", + "description": "ID of the space used by default in the collection" + } + } + } + }, + "required": ["collection"] + } + ] + }, + "CustomizationLocale": { + "type": "string", + "description": "Language for the UI element", + "enum": ["en", "fr", "es", "zh", "ja"] + }, + "CustomizationFont": { + "type": "string", + "enum": [ + "ABCFavorit", + "Inter", + "Roboto", + "RobotoSlab", + "OpenSans", + "SourceSansPro", + "Lato", + "Ubuntu", + "Raleway", + "Merriweather", + "Overpass", + "NotoSans", + "IBMPlexSerif", + "Poppins", + "FiraSans" + ] + }, + "CustomizationHeaderPreset": { + "type": "string", + "enum": ["default", "bold", "contrast", "custom", "none"] + }, + "CustomizationThemeMode": { + "type": "string", + "enum": ["light", "dark"] + }, + "CustomizationHeaderLink": { + "allOf": [ + { + "$ref": "#/components/schemas/CustomizationContentLink" + }, + { + "type": "object", + "properties": { + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationContentLink" + } + } + } + } + ] + }, + "CustomizationContentLink": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "to": { + "$ref": "#/components/schemas/ContentRef" + } + }, + "required": ["title", "to"] + }, + "CustomizationFooterGroup": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationContentLink" + } + } + }, + "required": ["title", "links"] + }, + "CustomizationCorners": { + "type": "string", + "enum": ["straight", "rounded"] + }, + "CustomizationBackground": { + "type": "string", + "enum": ["plain", "match"] + }, + "CustomizationThemedURL": { + "type": "object", + "properties": { + "light": { + "$ref": "#/components/schemas/URL" + }, + "dark": { + "$ref": "#/components/schemas/URL" + } + }, + "required": ["light", "dark"] + }, + "CustomizationThemedColor": { + "type": "object", + "properties": { + "light": { + "$ref": "#/components/schemas/Color" + }, + "dark": { + "$ref": "#/components/schemas/Color" + } + }, + "required": ["light", "dark"] + }, + "PageFeedback": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equal to \"page-feedback\"", + "enum": ["page-feedback"] + }, + "visitorId": { + "type": "string" + }, + "rating": { + "$ref": "#/components/schemas/PageFeedbackRating" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "revision": { + "type": "string", + "description": "ID of the revision when the rating was created" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the page feedback in the API", + "format": "uri" + } + }, + "required": ["location"] + } + }, + "required": ["object", "visitorId", "rating", "createdAt", "revision", "urls"] + }, + "PageFeedbackRating": { + "type": "string", + "enum": ["bad", "ok", "good"] + }, + "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" + } + }, + "required": ["object", "id", "createdAt"] + }, + "ShareLinkName": { + "type": "string", + "description": "Name of the share link", + "minLength": 0, + "maxLength": 50 + }, + "Site": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["site"] + }, + "id": { + "type": "string", + "description": "Unique identifier of the site" + }, + "title": { + "$ref": "#/components/schemas/SiteTitle" + }, + "hostname": { + "$ref": "#/components/schemas/SiteHostname" + }, + "basename": { + "$ref": "#/components/schemas/SiteBasename" + }, + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "siteSpaces": { + "type": "number" + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "subscription": { + "$ref": "#/components/schemas/SiteSubscription" + }, + "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 visibility is not \"unpublished.\"", + "format": "uri" + } + }, + "required": ["app", "location"] + } + }, + "required": [ + "object", + "id", + "title", + "basename", + "visibility", + "createdAt", + "siteSpaces", + "defaultSpace", + "subscription", + "urls" + ] + }, + "SiteTitle": { + "type": "string", + "description": "Title of the site", + "minLength": 2, + "maxLength": 50 + }, + "SiteCustomizationSettings": { + "type": "object", + "properties": { + "styling": { + "type": "object", + "properties": { + "primaryColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "corners": { + "$ref": "#/components/schemas/CustomizationCorners" + }, + "font": { + "$ref": "#/components/schemas/CustomizationFont" + }, + "background": { + "$ref": "#/components/schemas/CustomizationBackground" + } + }, + "required": ["primaryColor", "corners", "font", "background"] + }, + "internationalization": { + "type": "object", + "properties": { + "locale": { + "$ref": "#/components/schemas/CustomizationLocale" + } + }, + "required": ["locale"] + }, + "favicon": { + "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 + } + ] + }, + "header": { + "type": "object", + "properties": { + "preset": { + "$ref": "#/components/schemas/CustomizationHeaderPreset" + }, + "logo": { + "$ref": "#/components/schemas/CustomizationThemedURL" + }, + "backgroundColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "linkColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationHeaderLink" + } + } + }, + "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"] + }, + "themes": { + "type": "object", + "properties": { + "default": { + "$ref": "#/components/schemas/CustomizationThemeMode" + }, + "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"] + }, + "aiSearch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, AI search 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"] + }, + "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" + } + } + } + }, + "required": [ + "styling", + "internationalization", + "favicon", + "header", + "footer", + "themes", + "pdf", + "feedback", + "aiSearch", + "trademark", + "pagination", + "git", + "privacyPolicy", + "socialPreview" + ] + }, + "SiteVisibility": { + "type": "string", + "description": "* `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* `unpublished`: The site is not accessible to anyone.\n", + "enum": ["public", "unlisted", "share-link", "visitor-auth", "unpublished"] + }, + "SitePublishingAuth": { + "allOf": [ + { + "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 visitor auth secret is invalid." + } + }, + "required": ["object", "privateKey"] + }, + { + "$ref": "#/components/schemas/SpaceVisitorAuth" + } + ] + }, + "SiteBasename": { + "type": "string", + "description": "Basename for the site. For e.g. api", + "minLength": 1, + "maxLength": 100 + }, + "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]$" + }, + "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" + }, + "space": { + "$ref": "#/components/schemas/Space" + }, + "default": { + "type": "boolean", + "description": "Whether this is the default space for the site" + } + }, + "required": ["id", "space", "path"] + }, + "SiteSpacePath": { + "type": "string", + "description": "Path to the space on the site", + "minLength": 1, + "maxLength": 100 + }, + "SiteSubscriptionStatus": { + "type": "string", + "enum": ["active", "inactive"] + }, + "SiteSubscriptionType": { + "type": "string", + "enum": ["basic", "premium"] + }, + "SiteSubscription": { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/SiteSubscriptionType" + }, + "status": { + "$ref": "#/components/schemas/SiteSubscriptionStatus" + } + }, + "required": ["type", "status"] + }, + "CustomHostname": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["custom-hostname"] + }, + "hostname": { + "$ref": "#/components/schemas/SiteHostname" + }, + "target": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationPointer" + }, + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + } + ] + }, + "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"] + }, + "CustomHostnameStatus": { + "type": "string", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomHostnameDnsStatus" + }, + { + "$ref": "#/components/schemas/CustomHostnameSslStatus" + }, + { + "$ref": "#/components/schemas/CustomHostnameErrorStatus" + } + ] + }, + "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"] + }, + "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"] + }, + "SeatsUsage": { + "type": "object", + "description": "A summary of the seats usage and availability in the organization.", + "properties": { + "total": { + "description": "The total amount of seats in the organization.", + "type": "number" + }, + "available": { + "description": "How many seats are still available.", + "type": "number" + } + }, + "required": ["total", "available"] + } + }, + "responses": { + "BadRequestError": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["error"], + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "enum": [400] + }, + "message": { + "type": "string" + } + }, + "required": ["code", "message"] + } + } + } + } + } + }, + "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"] + } + } + } + } + } + }, + "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"] + } + } + } + } + } + }, + "UnexpectedError": { + "description": "Unexpected Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "paths": { + "/": { + "get": { + "operationId": "getApiInformation", + "tags": ["api"], + "summary": "Get information about the state of the GitBook API", + "description": "Access the release version and build date of the GitBook codebase", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiInformation" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/search": { + "get": { + "operationId": "searchContent", + "summary": "Search content across spaces that is accessible by the currently authenticated target", + "tags": ["search"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "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/SearchSpaceResult" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/search/ask": { + "get": { + "operationId": "askQueryWithGet", + "summary": "Ask a question to an AI across spaces that is accessible by the currently authenticated target.", + "deprecated": true, + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "askQuery", + "summary": "Ask a question to an AI across spaces that is accessible by the currently authenticated target.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "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" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/search/questions": { + "post": { + "operationId": "getRecommendedQuestions", + "summary": "Get a list of questions recommended by AI for a list of content. Deprecated, use getRecommendedQuestionsInOrganization instead.", + "deprecated": true, + "security": [ + { + "user": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + } + }, + "required": ["documents"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestions" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/user": { + "get": { + "operationId": "getAuthenticatedUser", + "summary": "Get profile of authenticated user", + "tags": ["users"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/users/{userId}": { + "get": { + "operationId": "getUserById", + "summary": "Get a user by its ID", + "tags": ["users"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}": { + "get": { + "operationId": "getSpaceById", + "summary": "Get the details about a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateSpaceById", + "summary": "Update the details of 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" + }, + "visibility": { + "$ref": "#/components/schemas/ContentVisibility" + }, + "visitorAuth": { + "$ref": "#/components/schemas/SpaceVisitorAuth", + "description": "The integration property, if set, is ignored." + }, + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" + } + } + }, + { + "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": "string", + "nullable": true, + "enum": [null] + }, + "icon": { + "type": "string", + "nullable": true, + "enum": [null] + } + } + } + ] + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "The space has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "deleteSpaceById", + "summary": "Soft-deletes a space. Soft-deleted spaces will be permanently removed after 7 days.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "205": { + "description": "Space has been deleted" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/hive/token": { + "post": { + "operationId": "generateSpaceHiveReadAccessToken", + "summary": "Returns a token to authenticate with Hive to read content from a given space.", + "tags": ["hive"], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "The JWT to access the space content in Hive.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HiveAccessToken" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/duplicate": { + "post": { + "operationId": "duplicateSpace", + "summary": "Create a duplicate of the 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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/restore": { + "post": { + "operationId": "restoreSpace", + "summary": "Restore a recently soft-deleted space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "Space restored", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/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", + "nullable": true + }, + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/transfer": { + "post": { + "operationId": "transferSpace", + "summary": "Transfer a space to another organization, collection or both.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "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": "Space transferred", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } + }, + "404": { + "description": "No matching Space found for given ID", + "$ref": "#/components/responses/NotFoundError" + }, + "409": { + "description": "Transfer would not result in any update", + "$ref": "#/components/responses/ConflictError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/search": { + "get": { + "operationId": "searchSpaceContent", + "summary": "Search content in a space", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/search/ask": { + "get": { + "operationId": "askQueryInSpaceWithGet", + "summary": "Ask a question to an AI within the context of the space.", + "deprecated": true, + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "askQueryInSpace", + "summary": "Ask a question to an AI within the context of the space.", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "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" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/search/ask/stream": { + "get": { + "operationId": "streamAskInSpace", + "summary": "Ask a question to an AI within the context of the space and stream the answer as a Server-Sent Events URL.", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SearchAIAnswerStream" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/search/questions": { + "get": { + "operationId": "getRecommendedQuestionsInSpace", + "summary": "Get a list of questions that can be asked in a space.", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestions" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/search/questions/stream": { + "get": { + "operationId": "streamRecommendedQuestionsInSpace", + "summary": "Stream a list of questions that can be asked in a space.", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/git/import": { + "post": { + "operationId": "importGitRepository", + "summary": "Import a Git repository", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Operation to import the repository has been started." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestImportGitRepository" + } + } + } + } + } + }, + "/spaces/{spaceId}/git/export": { + "post": { + "operationId": "exportToGitRepository", + "summary": "Export the space content to a Git repository.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Operation to export the space has been started." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestExportToGitRepository" + } + } + } + } + } + }, + "/spaces/{spaceId}/git/sync": { + "post": { + "operationId": "syncGitRepository", + "summary": "Synchronize a Git repository with the space content.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Operation to synchronize the repository has been started." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestSyncGitRepository" + } + } + } + } + } + }, + "/spaces/{spaceId}/git/info": { + "get": { + "operationId": "getSpaceGitInfo", + "summary": "Get metadata about the Git Sync provider currently set up on the space", + "tags": ["spaces"], + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/insights/content": { + "get": { + "operationId": "getContentAnalyticsForSpaceById", + "summary": "Get content analytics for a given space.", + "tags": ["analytics", "spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "Content analytics per page.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsContentPages" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/insights/search": { + "get": { + "operationId": "getSearchAnalyticsForSpaceById", + "summary": "Get an overview of the top search queries in a space.", + "tags": ["analytics", "spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "name": "period", + "required": false, + "in": "query", + "schema": { + "$ref": "#/components/schemas/AnalyticsSearchPeriod" + } + } + ], + "responses": { + "200": { + "description": "Top queries searched on this space.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsTopSearches" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/insights/traffic": { + "get": { + "operationId": "getTrafficAnalyticsForSpaceById", + "summary": "Get traffic page views for a given space", + "description": "Get the total number of views and breakdown per day or week for the last 14 days. Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.", + "tags": ["analytics", "spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "name": "interval", + "required": false, + "in": "query", + "schema": { + "$ref": "#/components/schemas/AnalyticsTrafficInterval" + } + } + ], + "responses": { + "200": { + "description": "Traffic over time for the given space.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsTrafficPageViews" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/insights/track_view": { + "post": { + "operationId": "trackViewInSpaceById", + "description": "Track a page view in a space.", + "tags": ["analytics", "spaces"], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Page view has been tracked." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestSpaceTrackPageView" + } + } + } + } + } + }, + "/spaces/{spaceId}/content": { + "get": { + "operationId": "getCurrentRevision", + "summary": "Get the current primary content revision for a space", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Revision" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/content/import": { + "post": { + "summary": "Import content in a space.", + "operationId": "importContent", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "201": { + "description": "Content imported in a new revision", + "headers": { + "Location": { + "description": "API URL for the newly created revision", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContentResult" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestImportContent" + } + } + } + } + } + }, + "/spaces/{spaceId}/content/pages": { + "get": { + "summary": "List all pages for the main revision content of a space", + "operationId": "listPages", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + } + }, + "required": ["pages"] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/content/files": { + "get": { + "summary": "List all files for the main revision content of a space", + "operationId": "listFiles", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/content/files/{fileId}": { + "get": { + "summary": "Get a file by its ID in the main revision of a space", + "operationId": "getFileById", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/fileId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionFile" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/content/page/{pageId}": { + "get": { + "operationId": "getPageById", + "summary": "Get a page by its ID in the primary content.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/pageId" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/content/page/{pageId}/import": { + "post": { + "operationId": "importContentInPageById", + "summary": "Import external content into a page by its ID.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/pageId" + } + ], + "responses": { + "201": { + "description": "Content imported in a new revision", + "headers": { + "Location": { + "description": "API URL for the newly created revision", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContentResult" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestImportContent" + } + } + } + } + } + }, + "/spaces/{spaceId}/content/path/{pagePath}": { + "get": { + "operationId": "getPageByPath", + "summary": "Get a page by its path in the primary content.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/pagePath" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/documents/{documentId}": { + "get": { + "operationId": "getDocumentById", + "summary": "Get a document by its ID in a space.", + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests": { + "post": { + "operationId": "createChangeRequest", + "summary": "Create a new change request for a space.", + "tags": ["spaces"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestCreateChangeRequest" + } + } + } + } + }, + "get": { + "operationId": "listChangeRequestsForSpace", + "summary": "List change requests for a space.", + "tags": ["spaces"], + "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" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}": { + "get": { + "operationId": "getChangeRequestById", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "summary": "Get the change request with the given id.", + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateChangeRequestById", + "summary": "Update the details of a change request", + "tags": ["spaces"], + "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" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The change request has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeRequest" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": { + "post": { + "operationId": "mergeChangeRequest", + "summary": "Merge a change request in the primary content of a space.", + "tags": ["spaces"], + "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"] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/update": { + "post": { + "operationId": "updateChangeRequest", + "summary": "Update a change-request with changes from primary content.", + "tags": ["spaces"], + "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"] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": { + "get": { + "operationId": "getReviewsByChangeRequestId", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + } + ], + "summary": "Get all reviews for a change request.", + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "submitChangeRequestReview", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "summary": "Submit a review for a change request.", + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "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}/requested-reviewers": { + "get": { + "operationId": "getRequestedReviewersByChangeRequestId", + "summary": "Get all requested reviewers for a change request.", + "tags": ["spaces"], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "requestReviewersForChangeRequest", + "summary": "Request reviewers on a change request. Note that requesting a review from teams is not yet supported.", + "tags": ["spaces"], + "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" + } + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "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." + } + }, + "required": ["users"] + } + } + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/links": { + "get": { + "operationId": "listChangeRequestLinks", + "summary": "Get all links in the context of a change request including their status and location where they appear.", + "tags": ["spaces", "links"], + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments": { + "get": { + "operationId": "listCommentsInChangeRequest", + "summary": "List all the comments in a change request.", + "tags": ["spaces"], + "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/pageFormat" + }, + { + "$ref": "#/components/parameters/commentStatus" + }, + { + "$ref": "#/components/parameters/commentTargetPage" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "postCommentInChangeRequest", + "summary": "Post a new comment in a change request.", + "tags": ["spaces"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}": { + "get": { + "operationId": "getCommentInChangeRequest", + "summary": "Get a comment in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "responses": { + "200": { + "description": "The returned comment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "deleteCommentInChangeRequest", + "summary": "Delete a comment in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/commentId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateCommentInChangeRequest", + "summary": "Update a comment in a change request.", + "tags": ["spaces"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies": { + "get": { + "operationId": "listCommentRepliesInChangeRequest", + "summary": "List all the replies to a comment in a change request.", + "tags": ["spaces"], + "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/pageFormat" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "postCommentReplyInChangeRequest", + "summary": "Post a new reply to a comment in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies/{commentReplyId}": { + "get": { + "operationId": "getCommentReplyInChangeRequest", + "summary": "Get a comment reply in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], + "responses": { + "200": { + "description": "The returned comment reply.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentReply" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateCommentReplyInChangeRequest", + "summary": "Update a comment reply in a change request.", + "tags": ["spaces"], + "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" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "deleteCommentReplyInChangeRequest", + "summary": "Delete a comment reply in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": { + "get": { + "operationId": "getContributorsByChangeRequestId", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "summary": "Get all contributors for the change request with the given id.", + "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/UserContributor" + } + } + } + } + ] + } + } + } + }, + "404": { + "description": "The change request could not be found.", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content": { + "get": { + "operationId": "getRevisionOfChangeRequestById", + "summary": "Get the latest content revision for a change request.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Revision" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/import": { + "post": { + "summary": "Import content in a change request.", + "operationId": "importContentInChangeRequest", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "responses": { + "201": { + "description": "Content imported in a new revision", + "headers": { + "Location": { + "description": "API URL for the newly created revision", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContentResult" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestImportContent" + } + } + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/pages": { + "get": { + "summary": "List all pages in the content of a change request", + "operationId": "listPagesInChangeRequest", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + } + }, + "required": ["pages"] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files": { + "get": { + "summary": "List all files in a change request content", + "operationId": "listFilesInChangeRequestById", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}": { + "get": { + "summary": "Get a file by its ID in the content of a change request", + "operationId": "getFileInChangeRequestById", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/fileId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionFile" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}": { + "get": { + "operationId": "getPageInChangeRequestById", + "summary": "Get a page by its ID in a change request.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/pageId" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import": { + "post": { + "operationId": "importContentInChangeRequestPageById", + "summary": "Import external content into a page of a change-request by its ID.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/pageId" + } + ], + "responses": { + "201": { + "description": "Content imported in a new revision", + "headers": { + "Location": { + "description": "API URL for the newly created revision", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContentResult" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestImportContent" + } + } + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}": { + "get": { + "operationId": "getPageInChangeRequestByPath", + "summary": "Get a page by its path in a change request.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "type": "number" + "$ref": "#/components/parameters/changeRequestId" }, { - "type": "boolean" + "$ref": "#/components/parameters/pagePath" }, { - "type": "array", - "items": { - "type": "string", - "maxLength": 256 - } - } - ] - }, - "CustomFieldValues": { - "type": "array", - "items": { - "type": "object", - "properties": { - "customField": { - "$ref": "#/components/schemas/CustomField" - }, - "value": { - "$ref": "#/components/schemas/CustomFieldValue" - } + "$ref": "#/components/parameters/pageFormat" }, - "required": ["customField"] - } - }, - "UpdateCustomFieldValues": { - "type": "object", - "properties": { - "values": { - "type": "object", - "additionalProperties": { - "type": "object", - "maxProperties": 100, - "minProperties": 1, - "properties": { - "value": { - "$ref": "#/components/schemas/CustomFieldValue" + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] } - }, - "required": ["value"] + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["values"] - }, - "CustomFieldOptions": { - "type": "array", - "minItems": 1, - "maxItems": 50, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 40 } - }, - "CustomFieldPlaceholder": { - "type": "string", - "maxLength": 100 } }, - "responses": { - "UnexpectedError": { - "description": "Unexpected Error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" + "/spaces/{spaceId}/change-requests/{changeRequestId}/touched-content": { + "post": { + "operationId": "touchContentInChangeRequest", + "summary": "Touch Hive content, marking it as modified as part of this change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "responses": { + "200": { + "description": "Content marked as touched.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeRequest" + } + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - } - }, - "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" - } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "contentId": { + "type": "string", + "description": "The content id of the touched content." }, - "required": ["code", "message"] - } + "branchId": { + "type": "string", + "description": "The branch id of the touched content." + }, + "relation": { + "type": "string", + "description": "The relation of the touched content to the change request.", + "enum": ["synced-block"] + } + }, + "required": ["contentId", "branchId", "relation"] } } } } - }, - "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"] + } + }, + "/spaces/{spaceId}/revisions/{revisionId}": { + "get": { + "operationId": "getRevisionById", + "summary": "Get a specific revision in a space", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Revision" } } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "ContentFilesResponse": { - "description": "OK", - "content": { - "application/json": { + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/changes": { + "get": { + "summary": "Return the semantic changes between a revision and its parent.", + "operationId": "getRevisionSemanticChanges", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + }, + { + "name": "limit", + "in": "query", + "description": "Limit the number of changes returned", "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { + "type": "number", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { "type": "object", - "required": ["items"], "properties": { - "items": { + "changes": { "type": "array", "items": { - "$ref": "#/components/schemas/RevisionFile" + "$ref": "#/components/schemas/RevisionSemanticChange" } + }, + "more": { + "type": "number", + "description": "How many changes were omitted because above the result limit" } - } + }, + "required": ["changes"] } - ] + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } } - } - }, - "paths": { - "/": { + }, + "/spaces/{spaceId}/revisions/{revisionId}/pages": { "get": { - "operationId": "getApiInformation", - "tags": ["api"], - "summary": "Get information about the state of the GitBook API", - "description": "Access the release version and build date of the GitBook codebase", + "summary": "List all pages in a revision", + "operationId": "listPagesInRevisionById", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiInformation" + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + } + }, + "required": ["pages"] } } } @@ -7032,11 +15607,10 @@ } } }, - "/search": { + "/spaces/{spaceId}/revisions/{revisionId}/files": { "get": { - "operationId": "searchContent", - "summary": "Search content across spaces that is accessible by the currently authenticated target", - "tags": ["search"], + "summary": "List all files in a revision", + "operationId": "listFilesInRevisionById", "security": [ { "user": [] @@ -7044,18 +15618,19 @@ ], "parameters": [ { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/revisionMetadata" } ], "responses": { @@ -7075,7 +15650,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchSpaceResult" + "$ref": "#/components/schemas/RevisionFile" } } } @@ -7091,11 +15666,10 @@ } } }, - "/search/ask": { + "/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}": { "get": { - "operationId": "askQueryWithGet", - "summary": "Ask a question to an AI across spaces that is accessible by the currently authenticated target.", - "deprecated": true, + "summary": "Get a file in a revision by its ID", + "operationId": "getFileInRevisionById", "security": [ { "user": [] @@ -7103,12 +15677,16 @@ ], "parameters": [ { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/fileId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" } ], "responses": { @@ -7117,12 +15695,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } + "$ref": "#/components/schemas/RevisionFile" } } } @@ -7131,37 +15704,91 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "post": { - "operationId": "askQuery", - "summary": "Ask a question to an AI across spaces that is accessible by the currently authenticated target.", + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": { + "get": { + "operationId": "getPageInRevisionById", + "summary": "Get a page by its ID in a revision.", "security": [ { "user": [] } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchAIQuery" + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/pageId" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}": { + "get": { + "operationId": "getPageInRevisionByPath", + "summary": "Get a page by its path in a revision.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/revisionId" + }, + { + "$ref": "#/components/parameters/pagePath" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" } - } + ] } } } @@ -7172,45 +15799,102 @@ } } }, - "/search/questions": { + "/spaces/{spaceId}/comments": { + "get": { + "operationId": "listCommentsInSpace", + "summary": "List all the comments in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/listOrder" + }, + { + "$ref": "#/components/parameters/commentStatus" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/commentTargetPage" + } + ], + "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" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, "post": { - "operationId": "getRecommendedQuestions", - "summary": "Get a list of questions recommended by AI for a list of content.", + "operationId": "postCommentInSpace", + "summary": "Post a new comment in a space.", + "tags": ["spaces"], "security": [ { "user": [] } ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], "requestBody": { "required": true, "content": { "application/json": { - "schema": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "minItems": 1, - "maxItems": 50, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 100 - } - } - }, - "required": ["documents"] + "schema": { + "$ref": "#/components/schemas/PostCommentSchema" } } } }, "responses": { "200": { - "description": "OK", + "description": "The comment was posted.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestions" + "$ref": "#/components/schemas/Comment" } } } @@ -7221,24 +15905,34 @@ } } }, - "/user": { + "/spaces/{spaceId}/comments/{commentId}": { "get": { - "operationId": "getAuthenticatedUser", - "summary": "Get profile of authenticated user", - "tags": ["users"], + "operationId": "getCommentInSpace", + "summary": "Get a comment in a space.", + "tags": ["spaces"], "security": [ { "user": [] } ], - "description": "Returns details about the user associated with the authentication provided in the request's authorization header.\n", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/pageFormat" + } + ], "responses": { "200": { - "description": "OK", + "description": "The returned comment.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/Comment" } } } @@ -7247,31 +15941,67 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/users/{userId}": { - "get": { - "operationId": "getUserById", - "summary": "Get a user by its ID", - "tags": ["users"], + }, + "delete": { + "operationId": "deleteCommentInSpace", + "summary": "Delete a comment in a space.", + "tags": ["spaces"], "security": [ { "user": [] } ], - "description": "Provides publicly available information about someone with a GitBook account.\n", "parameters": [ { - "$ref": "#/components/parameters/userId" + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateCommentInSpace", + "summary": "Update a comment in a space.", + "tags": ["spaces"], + "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": "OK", + "description": "The comment was updated.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/Comment" } } } @@ -7282,10 +16012,10 @@ } } }, - "/spaces/{spaceId}": { + "/spaces/{spaceId}/comments/{commentId}/replies": { "get": { - "operationId": "getSpaceById", - "summary": "Get the details about a space.", + "operationId": "listCommentRepliesInSpace", + "summary": "List all the replies to a comment in a space.", "tags": ["spaces"], "security": [ { @@ -7295,6 +16025,18 @@ "parameters": [ { "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/pageFormat" } ], "responses": { @@ -7303,7 +16045,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Space" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommentReply" + } + } + } + } + ] } } } @@ -7313,9 +16071,9 @@ } } }, - "patch": { - "operationId": "updateSpaceById", - "summary": "Update the details of a space", + "post": { + "operationId": "postCommentReplyInSpace", + "summary": "Post a new reply to a comment in a space.", "tags": ["spaces"], "security": [ { @@ -7325,6 +16083,9 @@ "parameters": [ { "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" } ], "requestBody": { @@ -7332,23 +16093,18 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" - } - } + "$ref": "#/components/schemas/PostCommentReplySchema" } } } }, "responses": { "200": { - "description": "The space has been updated", + "description": "The reply was posted.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Space" + "$ref": "#/components/schemas/CommentReply" } } } @@ -7359,23 +16115,37 @@ } } }, - "/spaces/{spaceId}/hive/token": { - "post": { - "operationId": "generateSpaceHiveReadAccessToken", - "summary": "Returns a token to authenticate with Hive to read content from a given space.", - "tags": ["hive"], + "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": { + "get": { + "operationId": "getCommentReplyInSpace", + "summary": "Get a comment reply in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], "parameters": [ { "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" + }, + { + "$ref": "#/components/parameters/pageFormat" } ], "responses": { "200": { - "description": "The JWT to access the space content in Hive.", + "description": "The returned comment reply.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HiveAccessToken" + "$ref": "#/components/schemas/CommentReply" } } } @@ -7384,12 +16154,10 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/duplicate": { - "post": { - "operationId": "duplicateSpace", - "summary": "Create a duplicate of the space.", + }, + "put": { + "operationId": "updateCommentReplyInSpace", + "summary": "Update a comment reply in a space.", "tags": ["spaces"], "security": [ { @@ -7399,23 +16167,31 @@ "parameters": [ { "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" } ], - "responses": { - "201": { - "description": "Space duplicated", - "headers": { - "Location": { - "description": "API URL for the newly created space", - "schema": { - "type": "string" - } + "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/Space" + "$ref": "#/components/schemas/CommentReply" } } } @@ -7424,26 +16200,48 @@ "$ref": "#/components/responses/UnexpectedError" } } + }, + "delete": { + "operationId": "deleteCommentReplyInSpace", + "summary": "Delete a comment reply in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } } }, - "/spaces/{spaceId}/search": { + "/spaces/{spaceId}/permissions/aggregate": { "get": { - "operationId": "searchSpaceContent", - "summary": "Search content in a space", + "operationId": "listPermissionsAggregateInSpace", + "summary": "List permissions for all users in a space.", + "tags": ["permissions", "spaces"], "security": [ { "user": [] } ], "parameters": [ - { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } - }, { "$ref": "#/components/parameters/spaceId" }, @@ -7452,11 +16250,19 @@ }, { "$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": "OK", + "description": "Listing of users who can access the space.", "content": { "application/json": { "schema": { @@ -7471,7 +16277,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/SearchPageResult" + "$ref": "#/components/schemas/UserContentPermission" } } } @@ -7487,20 +16293,17 @@ } } }, - "/spaces/{spaceId}/search/ask": { + "/spaces/{spaceId}/publishing/customization": { "get": { - "operationId": "askQueryInSpaceWithGet", - "summary": "Ask a question to an AI within the context of the space.", - "deprecated": true, - "parameters": [ + "operationId": "getSpacePublishingCustomizationById", + "summary": "Get the publishing customization configuration for a space.", + "tags": ["spaces"], + "security": [ { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } - }, + "user": [] + } + ], + "parameters": [ { "$ref": "#/components/parameters/spaceId" } @@ -7511,24 +16314,28 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } + "$ref": "#/components/schemas/CustomizationSettings" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "post": { - "operationId": "askQueryInSpace", - "summary": "Ask a question to an AI within the context of the space.", + "put": { + "operationId": "updateSpacePublishingCustomizationById", + "summary": "Update the publishing customization configuration for a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], "parameters": [ { "$ref": "#/components/parameters/spaceId" @@ -7539,7 +16346,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchAIQuery" + "$ref": "#/components/schemas/CustomizationSettings" } } } @@ -7550,26 +16357,30 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } + "$ref": "#/components/schemas/CustomizationSettings" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/search/questions": { + "/spaces/{spaceId}/publishing/auth": { "get": { - "operationId": "getRecommendedQuestionsInSpace", - "summary": "Get a list of questions that can be asked in a space.", + "operationId": "getSpacePublishingAuthById", + "summary": "Get the publishing authentication configuration for a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], "parameters": [ { "$ref": "#/components/parameters/spaceId" @@ -7581,56 +16392,22 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestions" + "$ref": "#/components/schemas/ContentPublishingAuth" } } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/git/import": { - "post": { - "operationId": "importGitRepository", - "summary": "Import a Git repository", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "204": { - "description": "Operation to import the repository has been started." + "400": { + "$ref": "#/components/responses/BadRequestError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestImportGitRepository" - } - } - } } - } - }, - "/spaces/{spaceId}/git/export": { + }, "post": { - "operationId": "exportToGitRepository", - "summary": "Export the space content to a Git repository.", + "operationId": "updateSpacePublishingAuthById", + "summary": "Update the publishing authentication configuration for a space.", "tags": ["spaces"], "security": [ { @@ -7642,55 +16419,29 @@ "$ref": "#/components/parameters/spaceId" } ], - "responses": { - "204": { - "description": "Operation to export the space has been started." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestExportToGitRepository" + "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" } } } - } - } - }, - "/spaces/{spaceId}/git/info": { - "get": { - "operationId": "getSpaceGitInfo", - "summary": "Get metadata about the Git Sync provider currently set up on the space", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], + }, "responses": { "200": { - "description": "The Git Sync info for the space", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GitSyncState" + "$ref": "#/components/schemas/ContentPublishingAuth" } } } }, - "404": { - "description": "No Git provider currently set up on the space", - "$ref": "#/components/responses/NotFoundError" + "400": { + "$ref": "#/components/responses/BadRequestError" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -7698,11 +16449,11 @@ } } }, - "/spaces/{spaceId}/insights/content": { + "/spaces/{spaceId}/publishing/preview": { "get": { - "operationId": "getContentAnalyticsForSpaceById", - "summary": "Get content analytics for a given space.", - "tags": ["analytics", "spaces"], + "operationId": "getSpacePublishingPreviewById", + "summary": "Get a URL to preview the published content of a space. The URL will be valid for 1 hour.", + "tags": ["spaces"], "security": [ { "user": [] @@ -7715,26 +16466,35 @@ ], "responses": { "200": { - "description": "Content analytics per page.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AnalyticsContentPages" + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" + } + }, + "required": ["url"] } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/insights/search": { + "/spaces/{spaceId}/integrations": { "get": { - "operationId": "getSearchAnalyticsForSpaceById", - "summary": "Get an overview of the top search queries in a space.", - "tags": ["analytics", "spaces"], + "operationId": "listSpaceIntegrations", + "summary": "List integrations enabled in a space.", + "tags": ["integrations", "spaces"], "security": [ { "user": [] @@ -7745,21 +16505,32 @@ "$ref": "#/components/parameters/spaceId" }, { - "name": "period", - "required": false, - "in": "query", - "schema": { - "$ref": "#/components/schemas/AnalyticsSearchPeriod" - } + "$ref": "#/components/schemas/IntegrationSearchQuery" } ], "responses": { "200": { - "description": "Top queries searched on this space.", + "description": "Listing of integrations enabled in the space.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AnalyticsTopSearches" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + ] } } } @@ -7770,81 +16541,41 @@ } } }, - "/spaces/{spaceId}/insights/traffic": { + "/spaces/{spaceId}/integration-blocks": { "get": { - "operationId": "getTrafficAnalyticsForSpaceById", - "summary": "Get traffic page views for a given space", - "description": "Get the total number of views and breakdown per day or week for the last 14 days. Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.", - "tags": ["analytics", "spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "listSpaceIntegrationsBlocks", + "summary": "List integrations blocks for a space", + "tags": ["integrations"], "parameters": [ { "$ref": "#/components/parameters/spaceId" - }, - { - "name": "interval", - "required": false, - "in": "query", - "schema": { - "$ref": "#/components/schemas/AnalyticsTrafficInterval" - } } ], "responses": { "200": { - "description": "Traffic over time for the given space.", + "description": "list of installed integration blocks", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AnalyticsTrafficPageViews" + "$ref": "#/components/schemas/SpaceIntegrationBlocks" } } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/insights/track_view": { - "post": { - "operationId": "trackViewInSpaceById", - "description": "Track a page view in a space.", - "tags": ["analytics", "spaces"], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "204": { - "description": "Page view has been tracked." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestSpaceTrackPageView" - } - } + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/content": { + "/spaces/{spaceId}/integration-scripts": { "get": { - "operationId": "getCurrentRevision", - "summary": "Get the current primary content revision for a space", + "operationId": "listSpaceIntegrationScripts", + "summary": "List the scripts to embed in published content for a space.", + "tags": ["spaces"], "security": [ { "user": [] @@ -7861,21 +16592,28 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Revision" + "type": "array", + "items": { + "$ref": "#/components/schemas/SpaceIntegrationScript" + } } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/content/import": { - "post": { - "summary": "Import content in a space.", - "operationId": "importContent", + "/spaces/{spaceId}/custom-fields": { + "get": { + "operationId": "getSpaceCustomFields", + "summary": "Get the values of the custom fields set on a space", + "tags": ["spaces"], "security": [ { "user": [] @@ -7887,20 +16625,12 @@ } ], "responses": { - "201": { - "description": "Content imported in a new revision", - "headers": { - "Location": { - "description": "API URL for the newly created revision", - "schema": { - "type": "string" - } - } - }, + "200": { + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ImportContentResult" + "$ref": "#/components/schemas/CustomFieldValues" } } } @@ -7908,23 +16638,12 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestImportContent" - } - } - } } - } - }, - "/spaces/{spaceId}/content/files": { - "get": { - "summary": "List all files for the latest primary revision content for a space", - "operationId": "listFiles", + }, + "patch": { + "operationId": "updateSpaceCustomFields", + "summary": "Update the custom fields in a space", + "tags": ["spaces"], "security": [ { "user": [] @@ -7933,17 +16652,21 @@ "parameters": [ { "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateCustomFieldValues" + } + } + } + }, "responses": { - "200": { - "$ref": "#/components/responses/ContentFilesResponse" + "204": { + "description": "Custom fields updated" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -7951,10 +16674,11 @@ } } }, - "/spaces/{spaceId}/content/page/{pageId}": { + "/spaces/{spaceId}/pages/{pageId}/feedbacks/{visitorId}": { "get": { - "operationId": "getPageById", - "summary": "Get a page by its ID in the primary content.", + "operationId": "getPageFeedback", + "summary": "Get a page feedback by a visitor.", + "tags": ["spaces"], "security": [ { "user": [] @@ -7968,7 +16692,7 @@ "$ref": "#/components/parameters/pageId" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/visitorId" } ], "responses": { @@ -7977,7 +16701,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RevisionPage" + "$ref": "#/components/schemas/PageFeedback" } } } @@ -7986,12 +16710,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/content/page/{pageId}/import": { - "post": { - "operationId": "importContentInPageById", - "summary": "Import external content into a page by its ID.", + }, + "put": { + "operationId": "createPageFeedback", + "summary": "Create a page feedback by a visitor.", + "tags": ["spaces"], "security": [ { "user": [] @@ -8003,14 +16726,43 @@ }, { "$ref": "#/components/parameters/pageId" + }, + { + "$ref": "#/components/parameters/visitorId" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "rating": { + "$ref": "#/components/schemas/PageFeedbackRating" + } + }, + "required": ["rating"] + } + } + } + }, "responses": { + "200": { + "description": "Feedback updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } + } + } + }, "201": { - "description": "Content imported in a new revision", + "description": "Feedback created", "headers": { "Location": { - "description": "API URL for the newly created revision", + "description": "URL for the feedback", "schema": { "type": "string" } @@ -8019,7 +16771,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ImportContentResult" + "$ref": "#/components/schemas/PageFeedback" } } } @@ -8027,23 +16779,14 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestImportContent" - } - } - } } } }, - "/spaces/{spaceId}/content/path/{pagePath}": { + "/spaces/{spaceId}/pdf": { "get": { - "operationId": "getPageByPath", - "summary": "Get a page by its path in the primary content.", + "operationId": "getSpacePDF", + "summary": "Generate a URL to export the content of the space as a PDF.", + "tags": ["spaces"], "security": [ { "user": [] @@ -8054,26 +16797,36 @@ "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/parameters/pagePath" + "in": "query", + "name": "only", + "description": "Generate a PDF only for the provided page.", + "schema": { + "type": "boolean" + } }, { - "$ref": "#/components/parameters/pageFormat" + "in": "query", + "name": "page", + "description": "ID of a specific page to generate a PDF for.", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "OK", + "description": "URL of the PDF", "content": { "application/json": { "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" + "type": "object", + "properties": { + "url": { + "description": "Temporary URL to print the content. The URL will work for 1h.", + "$ref": "#/components/schemas/URL" } - ] + }, + "required": ["url"] } } } @@ -8084,10 +16837,10 @@ } } }, - "/spaces/{spaceId}/change-requests": { + "/spaces/{spaceId}/share-links": { "post": { - "operationId": "createChangeRequest", - "summary": "Create a new change request for a space.", + "operationId": "createSpaceShareLink", + "summary": "Creates a new space share link", "tags": ["spaces"], "security": [ { @@ -8099,107 +16852,28 @@ "$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": { - "allOf": [ - { - "$ref": "#/components/schemas/ChangeRequest" - }, - { - "type": "object", - "properties": { - "changeRequest": { - "type": "string", - "deprecated": true - } - }, - "required": ["changeRequest"] - } - ] - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestCreateChangeRequest" - } - } - } - } - }, - "get": { - "operationId": "listChangeRequestsForSpace", - "summary": "List change requests for a space.", - "tags": ["spaces"], - "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" - } - ], - "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" - } - } - } - } - ] + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + }, + "required": ["name"] + } + } + } + }, + "responses": { + "201": { + "description": "The space share link has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" } } } @@ -8210,9 +16884,10 @@ } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}": { - "get": { - "operationId": "getChangeRequestById", + "/spaces/{spaceId}/share-links/{shareLinkId}": { + "patch": { + "operationId": "updateSpaceShareLinkById", + "summary": "Update the details of a space share link", "tags": ["spaces"], "security": [ { @@ -8224,35 +16899,47 @@ "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/shareLinkId" } ], - "summary": "Get the change request with the given id.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "minProperties": 1, + "properties": { + "active": { + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + } + } + } + } + }, "responses": { "200": { - "description": "The matching change request", + "description": "The space share link has been updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChangeRequest" + "$ref": "#/components/schemas/ShareLink" } } } }, - "404": { - "description": "The change request could not be found.", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": { - "post": { - "operationId": "mergeChangeRequest", - "summary": "Merge a change request in the primary content of a space.", + }, + "delete": { + "operationId": "deleteSpaceShareLinkById", + "summary": "Deletes a space share link", "tags": ["spaces"], "security": [ { @@ -8264,7 +16951,32 @@ "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/shareLinkId" + } + ], + "responses": { + "205": { + "description": "Space share link has been deleted" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/collections/{collectionId}": { + "get": { + "operationId": "getCollectionById", + "summary": "Get the details about a collection using its ID", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" } ], "responses": { @@ -8273,18 +16985,7 @@ "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"] + "$ref": "#/components/schemas/Collection" } } } @@ -8293,13 +16994,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/update": { - "post": { - "operationId": "updateChangeRequest", - "summary": "Update a change-request with changes from primary content.", - "tags": ["spaces"], + }, + "patch": { + "operationId": "updateCollectionById", + "summary": "Update the details of a collection", + "tags": ["collections"], "security": [ { "user": [] @@ -8307,30 +17006,40 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "visibility": { + "$ref": "#/components/schemas/ContentVisibility" + }, + "title": { + "$ref": "#/components/schemas/CollectionTitle" + }, + "description": { + "$ref": "#/components/schemas/CollectionDescription" + }, + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" + } + } + } + } + } + }, "responses": { "200": { - "description": "OK", + "description": "The collection has been updated", "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"] + "$ref": "#/components/schemas/Collection" } } } @@ -8339,12 +17048,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": { - "get": { - "operationId": "getReviewsByChangeRequestId", - "tags": ["spaces"], + }, + "delete": { + "operationId": "deleteCollectionById", + "summary": "Deletes a collection", + "tags": ["collections"], "security": [ { "user": [] @@ -8352,13 +17060,32 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/collectionId" + } + ], + "responses": { + "205": { + "description": "Collection has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/collections/{collectionId}/spaces": { + "get": { + "operationId": "listSpacesInCollectionById", + "summary": "List all the spaces in a collection by its ID.", + "tags": ["collections"], + "security": [ { - "$ref": "#/components/parameters/changeRequestId" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/collectionId" }, { "$ref": "#/components/parameters/listPage" @@ -8367,10 +17094,9 @@ "$ref": "#/components/parameters/listLimit" } ], - "summary": "Get all reviews for a change request.", "responses": { "200": { - "description": "All reviews for the given change request.", + "description": "OK", "content": { "application/json": { "schema": { @@ -8385,7 +17111,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/ChangeRequestReview" + "$ref": "#/components/schemas/Space" } } } @@ -8395,18 +17121,17 @@ } } }, - "404": { - "description": "The change request or space could not be found.", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, + } + }, + "/collections/{collectionId}/move": { "post": { - "operationId": "submitChangeRequestReview", - "tags": ["spaces"], + "operationId": "moveCollection", + "summary": "Move a collection to a new position.", + "tags": ["collections"], "security": [ { "user": [] @@ -8414,36 +17139,75 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" } ], - "summary": "Submit a review for a change request.", - "responses": { - "201": { - "headers": { - "Location": { - "description": "API URL for the newly created review", - "schema": { - "type": "string" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "minProperties": 1, + "properties": { + "parent": { + "description": "The unique id of the parent collection", + "type": "string", + "nullable": true + }, + "position": { + "description": "Where to move the collection. By default, it will be moved at the end.", + "$ref": "#/components/schemas/ContentPosition" + } } } - }, - "description": "A new review has been created.", + } + } + }, + "responses": { + "200": { + "description": "Collection moved", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChangeRequestReview" + "$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" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } - }, + } + } + }, + "/collections/{collectionId}/transfer": { + "post": { + "operationId": "transferCollection", + "summary": "Transfer a collection to another organization.", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], "requestBody": { "required": true, "content": { @@ -8451,27 +17215,46 @@ "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" + "organization": { + "type": "string", + "description": "The unique id of the target organization" } }, - "required": ["status"] + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers": { + "/collections/{collectionId}/permissions/aggregate": { "get": { - "operationId": "getRequestedReviewersByChangeRequestId", - "summary": "Get all requested reviewers for a change request.", - "tags": ["spaces"], + "operationId": "listPermissionsAggregateInCollection", + "summary": "List permissions for all users in a collection.", + "tags": ["permissions", "spaces"], "security": [ { "user": [] @@ -8479,21 +17262,26 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$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": "A list of requested reviewers", + "description": "Listing of users who can access the collections.", "content": { "application/json": { "schema": { @@ -8508,7 +17296,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/ChangeRequestRequestedReviewer" + "$ref": "#/components/schemas/UserContentPermission" } } } @@ -8522,11 +17310,13 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "post": { - "operationId": "requestReviewersForChangeRequest", - "summary": "Request reviewers on a change request. Note that requesting a review from teams is not yet supported.", - "tags": ["spaces"], + } + }, + "/collections/{collectionId}/publishing/auth": { + "get": { + "operationId": "getCollectionPublishingAuthById", + "summary": "Get the publishing authentication configuration for a collection.", + "tags": ["collections"], "security": [ { "user": [] @@ -8534,67 +17324,77 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" } ], "responses": { "200": { - "description": "The requests have successfully been sent.", + "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "users": { - "type": "array", - "description": "The user requests that were sent.", - "items": { - "$ref": "#/components/schemas/ChangeRequestRequestedReviewer" - } - } - } + "$ref": "#/components/schemas/ContentPublishingAuth" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } - }, + } + }, + "post": { + "operationId": "updateCollectionPublishingAuthById", + "summary": "Update the publishing authentication configuration for a collection.", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], "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." - } - }, - "required": ["users"] + "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPublishingAuth" + } } } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/comments": { + "/collections/{collectionId}/publishing/customization": { "get": { - "operationId": "listCommentsInChangeRequest", - "summary": "List all the comments in a change request.", - "tags": ["spaces"], + "operationId": "getCollectionPublishingCustomizationById", + "summary": "Get the publishing customization configuration for a collection.", + "tags": ["collections"], "security": [ { "user": [] @@ -8602,22 +17402,7 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" - }, - { - "$ref": "#/components/parameters/pageFormat" - }, - { - "$ref": "#/components/parameters/commentStatus" + "$ref": "#/components/parameters/collectionId" } ], "responses": { @@ -8626,36 +17411,23 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Comment" - } - } - } - } - ] + "$ref": "#/components/schemas/CustomizationCollectionSettings" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "post": { - "operationId": "postCommentInChangeRequest", - "summary": "Post a new comment in a change request.", - "tags": ["spaces"], + "put": { + "operationId": "updateCollectionPublishingCustomizationById", + "summary": "Update the publishing customization configuration for a collection.", + "tags": ["collections"], "security": [ { "user": [] @@ -8663,10 +17435,7 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" } ], "requestBody": { @@ -8674,33 +17443,36 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostCommentSchema" + "$ref": "#/components/schemas/CustomizationCollectionSettings" } } } }, "responses": { "200": { - "description": "The comment was posted.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Comment" + "$ref": "#/components/schemas/CustomizationCollectionSettings" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}": { - "get": { - "operationId": "getCommentInChangeRequest", - "summary": "Get a comment in a change request.", - "tags": ["spaces"], + "/collections/{collectionId}/share-links": { + "post": { + "operationId": "createCollectionShareLink", + "summary": "Creates a new collection share link", + "tags": ["collections"], "security": [ { "user": [] @@ -8708,25 +17480,31 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/commentId" - }, - { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/collectionId" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + }, + "required": ["name"] + } + } + } + }, "responses": { - "200": { - "description": "The returned comment.", + "201": { + "description": "The collection share link has been created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Comment" + "$ref": "#/components/schemas/ShareLink" } } } @@ -8735,54 +17513,24 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "delete": { - "operationId": "deleteCommentInChangeRequest", - "summary": "Delete a comment in a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/commentId" - } - ], - "responses": { - "200": { - "description": "The comment has been deleted." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "put": { - "operationId": "updateCommentInChangeRequest", - "summary": "Update a comment in a change request.", - "tags": ["spaces"], + } + }, + "/collections/{collectionId}/share-links/{shareLinkId}": { + "patch": { + "operationId": "updateCollectionShareLinkById", + "summary": "Update the details of a collection share link", + "tags": ["collections"], "security": [ { "user": [] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, + ], + "parameters": [ { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/shareLinkId" } ], "requestBody": { @@ -8790,18 +17538,27 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" + "type": "object", + "minProperties": 1, + "properties": { + "active": { + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + } } } } }, "responses": { "200": { - "description": "The comment was updated.", + "description": "The collection share link has been updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Comment" + "$ref": "#/components/schemas/ShareLink" } } } @@ -8810,13 +17567,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies": { - "get": { - "operationId": "listCommentRepliesInChangeRequest", - "summary": "List all the replies to a comment in a change request.", - "tags": ["spaces"], + }, + "delete": { + "operationId": "deleteCollectionShareLinkById", + "summary": "Deletes a collection share link", + "tags": ["collections"], "security": [ { "user": [] @@ -8824,14 +17579,28 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/collectionId" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/shareLinkId" + } + ], + "responses": { + "205": { + "description": "Collection share link has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations": { + "get": { + "operationId": "listIntegrations", + "summary": "List all public integrations", + "tags": ["integrations"], + "parameters": [ { "$ref": "#/components/parameters/listPage" }, @@ -8839,12 +17608,30 @@ "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/schemas/IntegrationSearchQuery" + }, + { + "name": "category", + "in": "query", + "description": "Filter the integrations by category", + "schema": { + "$ref": "#/components/schemas/IntegrationCategory" + } + }, + { + "name": "blockDomain", + "in": "query", + "description": "Filter the integrations by block's domains", + "schema": { + "type": "string", + "pattern": "^[a-zA-Z0-9-_.]+$", + "maxLength": 100 + } } ], "responses": { "200": { - "description": "OK", + "description": "Paginated list of integrations", "content": { "application/json": { "schema": { @@ -8859,7 +17646,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/Integration" } } } @@ -8873,62 +17660,42 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "post": { - "operationId": "postCommentReplyInChangeRequest", - "summary": "Post a new reply to a comment in a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + } + }, + "/integrations/{integrationName}": { + "get": { + "operationId": "getIntegrationByName", + "summary": "Get a specific integration by its name", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/commentId" - }, - { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/integrationName" } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PostCommentReplySchema" - } - } - } - }, "responses": { "200": { - "description": "The reply was posted.", + "description": "Integration", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/Integration" } } } }, + "404": { + "description": "No matching integration found for given name", + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies/{commentReplyId}": { - "get": { - "operationId": "getCommentReplyInChangeRequest", - "summary": "Get a comment reply in a change request.", - "tags": ["spaces"], + }, + "post": { + "operationId": "publishIntegration", + "summary": "Publish an integration", + "tags": ["integrations"], "security": [ { "user": [] @@ -8936,41 +17703,43 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/commentId" - }, - { - "$ref": "#/components/parameters/commentReplyId" - }, - { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/integrationName" } ], "responses": { "200": { - "description": "The returned comment reply.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/Integration" } } } }, + "404": { + "description": "Organization could not be found for the given hostname", + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestPublishIntegration" + } + } + } } }, - "put": { - "operationId": "updateCommentReplyInChangeRequest", - "summary": "Update a comment reply in a change request.", - "tags": ["spaces"], + "delete": { + "operationId": "unpublishIntegration", + "summary": "Unpublish an integration", + "tags": ["integrations"], "security": [ { "user": [] @@ -8978,35 +17747,71 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" + } + ], + "responses": { + "204": { + "description": "Integration has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations/{integrationName}/installations": { + "get": { + "operationId": "listIntegrationInstallations", + "summary": "Fetch a list of installations of an integration", + "tags": ["integrations"], + "security": [ { - "$ref": "#/components/parameters/changeRequestId" + "integration": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/parameters/commentReplyId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" - } + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "externalId", + "in": "query", + "description": "External Id to filter by", + "schema": { + "type": "string" } } - }, + ], "responses": { "200": { - "description": "The reply was updated.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CommentReply" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationInstallation" + } + } + } + } + ] } } } @@ -9016,10 +17821,10 @@ } } }, - "delete": { - "operationId": "deleteCommentReplyInChangeRequest", - "summary": "Delete a comment reply in a change request.", - "tags": ["spaces"], + "post": { + "operationId": "installIntegration", + "summary": "Install integration on a target organization", + "tags": ["integrations"], "security": [ { "user": [] @@ -9027,21 +17832,40 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/commentId" - }, - { - "$ref": "#/components/parameters/commentReplyId" + "$ref": "#/components/parameters/integrationName" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationTarget" + } + } } - ], + }, "responses": { - "200": { - "description": "The comment has been deleted." + "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" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -9049,27 +17873,25 @@ } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": { + "/integrations/{integrationName}/events": { "get": { - "operationId": "getContributorsByChangeRequestId", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "listIntegrationEvents", + "summary": "List all integration events", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" } ], - "summary": "Get all contributors for the change request with the given id.", "responses": { "200": { - "description": "Contributors on the change request", + "description": "Paginated list of integration events", "content": { "application/json": { "schema": { @@ -9084,7 +17906,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/UserContributor" + "$ref": "#/components/schemas/IntegrationEvent" } } } @@ -9094,82 +17916,112 @@ } } }, - "404": { - "description": "The change request could not be found.", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content": { + "/integrations/{integrationName}/events/{eventId}": { "get": { - "operationId": "getRevisionOfChangeRequestById", - "summary": "Get the latest content revision for a change request.", - "security": [ - { - "user": [] - } - ], + "operationId": "getIntegrationEvent", + "summary": "Get a specific integration event by its id", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/changeRequestId" + "name": "eventId", + "in": "path", + "required": true, + "description": "ID of the integration event", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "OK", + "description": "Integration event", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Revision" + "type": "object", + "required": ["event"], + "properties": { + "event": { + "$ref": "#/components/schemas/IntegrationEvent" + }, + "trace": { + "$ref": "#/components/schemas/IntegrationEventTrace" + } + } } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content/import": { - "post": { - "summary": "Import content in a change request.", - "operationId": "importContentInChangeRequest", + "/integrations/{integrationName}/spaces": { + "get": { + "operationId": "listIntegrationSpaceInstallations", + "summary": "Fetch a list of space installations of an integration", + "tags": ["integrations"], "security": [ { - "user": [] + "integration": [] } ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "externalId", + "in": "query", + "description": "External Id to filter by", + "schema": { + "type": "string" + } } ], "responses": { - "201": { - "description": "Content imported in a new revision", - "headers": { - "Location": { - "description": "API URL for the newly created revision", - "schema": { - "type": "string" - } - } - }, + "200": { + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ImportContentResult" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } + } + ] } } } @@ -9177,23 +18029,14 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestImportContent" - } - } - } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files": { - "get": { - "summary": "List all files in the latest content of the change-request", - "operationId": "listFilesInChangeRequestById", + "/integrations/{integrationName}/spaces/{spaceId}/dev": { + "put": { + "operationId": "updateIntegrationDevSpace", + "summary": "Update the development space for an integration", + "tags": ["integrations"], "security": [ { "user": [] @@ -9201,32 +18044,47 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/spaceId" } ], + "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 + } + }, + "required": ["tunnelUrl"] + } + } + } + }, "responses": { - "200": { - "$ref": "#/components/responses/ContentFilesResponse" + "204": { + "description": "Updated development space successfully" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}": { - "get": { - "operationId": "getPageInChangeRequestById", - "summary": "Get a page by its ID in a change request.", + }, + "delete": { + "operationId": "removeIntegrationDevSpace", + "summary": "Remove the development space for an integration", + "tags": ["integrations"], "security": [ { "user": [] @@ -9234,25 +18092,58 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Removed development space successfully" + }, + "404": { + "description": "No matching integration dev space found", + "$ref": "#/components/responses/NotFoundError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations/{integrationName}/render": { + "get": { + "operationId": "renderIntegrationUIWithGet", + "summary": "Render an integration UI in the context of an installation.", + "parameters": [ { - "$ref": "#/components/parameters/pageId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/pageFormat" + "name": "request", + "in": "query", + "required": true, + "description": "LZ-string compressed JSON request", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "OK", + "description": "ContentKit element to render", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RevisionPage" + "$ref": "#/components/schemas/ContentKitRenderOutput" + } + } + }, + "headers": { + "Cache-Control": { + "schema": { + "type": "string" } } } @@ -9261,43 +18152,29 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/import": { + }, "post": { - "operationId": "importContentInChangeRequestPageById", - "summary": "Import external content into a page of a change-request by its ID.", - "security": [ - { - "user": [] - } - ], + "operationId": "renderIntegrationUIWithPost", + "summary": "Render an integration UI in the context of an installation.", "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/pageId" + "$ref": "#/components/parameters/integrationName" } ], "responses": { - "201": { - "description": "Content imported in a new revision", - "headers": { - "Location": { - "description": "API URL for the newly created revision", + "200": { + "description": "ContentKit element to render", + "content": { + "application/json": { "schema": { - "type": "string" + "$ref": "#/components/schemas/ContentKitRenderOutput" } } }, - "content": { - "application/json": { + "headers": { + "Cache-Control": { "schema": { - "$ref": "#/components/schemas/ImportContentResult" + "type": "string" } } } @@ -9311,53 +18188,57 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestImportContent" + "$ref": "#/components/schemas/RequestRenderIntegrationUI" } } } } } }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/content/path/{pagePath}": { - "get": { - "operationId": "getPageInChangeRequestByPath", - "summary": "Get a page by its path in a change request.", + "/integrations/{integrationName}/tasks": { + "post": { + "operationId": "queueIntegrationTask", + "summary": "Queue a task for an integration to be executed later", + "tags": ["integrations"], "security": [ { - "user": [] + "integration": [] } ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" - }, - { - "$ref": "#/components/parameters/pagePath" - }, - { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/integrationName" } ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" - } - ] - } + "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" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -9365,10 +18246,11 @@ } } }, - "/spaces/{spaceId}/revisions/{revisionId}": { + "/integrations/{integrationName}/installations/{installationId}": { "get": { - "operationId": "getRevisionById", - "summary": "Get a specific revision in a space", + "operationId": "getIntegrationInstallationById", + "summary": "Get a specific integration's installation by its ID", + "tags": ["integrations"], "security": [ { "user": [] @@ -9376,33 +18258,35 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/revisionId" + "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { - "description": "OK", + "description": "Integration installation", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Revision" + "$ref": "#/components/schemas/IntegrationInstallation" } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/files": { - "get": { - "summary": "List all files in a revision", - "operationId": "listFilesInRevisionById", + }, + "patch": { + "operationId": "updateIntegrationInstallation", + "summary": "Update external IDs and configurations of an integration's installation", + "tags": ["integrations"], "security": [ { "user": [] @@ -9410,32 +18294,42 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/revisionId" - }, - { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { - "$ref": "#/components/responses/ContentFilesResponse" + "description": "The installation has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationInstallation" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestUpdateIntegrationInstallation" + } + } + } } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": { - "get": { - "operationId": "getPageInRevisionById", - "summary": "Get a page by its ID in a revision.", + }, + "delete": { + "operationId": "uninstallIntegration", + "summary": "Uninstall the integration from a target organization", + "tags": ["integrations"], "security": [ { "user": [] @@ -9443,28 +18337,18 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/revisionId" - }, - { - "$ref": "#/components/parameters/pageId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/installationId" } ], "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionPage" - } - } - } + "204": { + "description": "Integration uninstalled successfully" + }, + "404": { + "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -9472,78 +18356,63 @@ } } }, - "/spaces/{spaceId}/revisions/{revisionId}/path/{pagePath}": { - "get": { - "operationId": "getPageInRevisionByPath", - "summary": "Get a page by its path in a revision.", + "/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": [ { - "user": [] + "integration": [] } ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/revisionId" - }, - { - "$ref": "#/components/parameters/pagePath" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/installationId" } ], "responses": { "200": { - "description": "OK", + "description": "The API token for the installation", "content": { "application/json": { "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" - } - ] + "$ref": "#/components/schemas/APITemporaryToken" } } } }, + "404": { + "description": "Installation could not be found", + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/comments": { + "/integrations/{integrationName}/installations/{installationId}/spaces": { "get": { - "operationId": "listCommentsInSpace", - "summary": "List all the comments in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, + "operationId": "listIntegrationInstallationSpaces", + "summary": "List installations on spaces for an integration in an organization", + "tags": ["integrations"], + "parameters": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/parameters/commentStatus" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/listLimit" } ], "responses": { @@ -9563,7 +18432,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Comment" + "$ref": "#/components/schemas/IntegrationSpaceInstallation" } } } @@ -9579,17 +18448,14 @@ } }, "post": { - "operationId": "postCommentInSpace", - "summary": "Post a new comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "installIntegrationOnSpace", + "summary": "Install integration on a space using an existing installation", "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" + }, + { + "$ref": "#/components/parameters/installationId" } ], "requestBody": { @@ -9597,128 +18463,138 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostCommentSchema" + "type": "object", + "required": ["space"], + "properties": { + "space": { + "type": "string", + "description": "ID of the space to install the integration on" + } + } } } } }, "responses": { - "200": { - "description": "The comment was posted.", + "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/Comment" + "$ref": "#/components/schemas/IntegrationSpaceInstallation" } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/comments/{commentId}": { + "/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}": { "get": { - "operationId": "getCommentInSpace", - "summary": "Get a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "getIntegrationSpaceInstallation", + "summary": "Get a specific integration's space installation", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/spaceId" } ], "responses": { "200": { - "description": "The returned comment.", + "description": "Integration space installation", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Comment" + "$ref": "#/components/schemas/IntegrationSpaceInstallation" } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "delete": { - "operationId": "deleteCommentInSpace", - "summary": "Delete a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "patch": { + "operationId": "updateIntegrationSpaceInstallation", + "summary": "Update external IDs and configurations of an integration's installation for a space", "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/installationId" + }, + { + "$ref": "#/components/parameters/spaceId" } ], "responses": { "200": { - "description": "The comment has been deleted." + "description": "The space installation has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" } - } - }, - "put": { - "operationId": "updateCommentInSpace", - "summary": "Update a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/commentId" - } - ], + }, "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" + "$ref": "#/components/schemas/RequestUpdateIntegrationSpaceInstallation" } } } - }, + } + }, + "delete": { + "operationId": "uninstallIntegrationFromSpace", + "summary": "Uninstall the integration from a space", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" + }, + { + "$ref": "#/components/parameters/installationId" + }, + { + "$ref": "#/components/parameters/spaceId" + } + ], "responses": { - "200": { - "description": "The comment was updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Comment" - } - } - } + "204": { + "description": "The space installation has been deleted." }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -9726,31 +18602,23 @@ } } }, - "/spaces/{spaceId}/comments/{commentId}/replies": { + "/integrations/{integrationName}/installations/{installationId}/sites": { "get": { - "operationId": "listCommentRepliesInSpace", - "summary": "List all the replies to a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "listIntegrationInstallationSites", + "summary": "List installations on sites for an integration in an organization", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/installationId" }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" - }, - { - "$ref": "#/components/parameters/pageFormat" } ], "responses": { @@ -9770,7 +18638,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/IntegrationSiteInstallation" } } } @@ -9786,20 +18654,15 @@ } }, "post": { - "operationId": "postCommentReplyInSpace", - "summary": "Post a new reply to a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "installIntegrationOnSite", + "summary": "Install integration on a site using an existing installation", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/installationId" } ], "requestBody": { @@ -9807,105 +18670,102 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PostCommentReplySchema" + "type": "object", + "required": ["siteId"], + "properties": { + "siteId": { + "type": "string", + "description": "ID of the site to install the integration on" + } + } } } } }, "responses": { - "200": { - "description": "The reply was posted.", + "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/CommentReply" + "$ref": "#/components/schemas/IntegrationSiteInstallation" } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": { + "/integrations/{integrationName}/installations/{installationId}/sites/{siteId}": { "get": { - "operationId": "getCommentReplyInSpace", - "summary": "Get a comment reply in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "getIntegrationSiteInstallation", + "summary": "Get a specific integration's site installation", + "tags": ["integrations"], "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentReplyId" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/siteId" } ], "responses": { "200": { - "description": "The returned comment reply.", + "description": "Integration site installation", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/IntegrationSiteInstallation" } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "put": { - "operationId": "updateCommentReplyInSpace", - "summary": "Update a comment reply in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "patch": { + "operationId": "updateIntegrationSiteInstallation", + "summary": "Update external IDs and configurations of an integration's installation for a site", "parameters": [ { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/integrationName" }, - { - "$ref": "#/components/parameters/commentReplyId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentReplySchema" - } - } + { + "$ref": "#/components/parameters/installationId" + }, + { + "$ref": "#/components/parameters/siteId" } - }, + ], "responses": { "200": { - "description": "The reply was updated.", + "description": "The site installation has been updated.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CommentReply" + "$ref": "#/components/schemas/IntegrationSiteInstallation" } } } @@ -9913,31 +18773,35 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestUpdateIntegrationSiteInstallation" + } + } + } } }, "delete": { - "operationId": "deleteCommentReplyInSpace", - "summary": "Delete a comment reply in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], + "operationId": "uninstallIntegrationFromSite", + "summary": "Uninstall the integration from a site", "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/parameters/commentReplyId" + "$ref": "#/components/parameters/siteId" } ], "responses": { - "200": { - "description": "The comment has been deleted." + "204": { + "description": "The site installation has been deleted." }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -9945,38 +18809,27 @@ } } }, - "/spaces/{spaceId}/permissions/aggregate": { + "/orgs": { "get": { - "operationId": "listPermissionsAggregateInSpace", - "summary": "List permissions for all users in a space.", - "tags": ["permissions", "spaces"], + "operationId": "listOrganizationsForAuthenticatedUser", + "summary": "Get the list of organizations for the currently authenticated user", + "tags": ["organizations"], "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.", + "description": "OK", "content": { "application/json": { "schema": { @@ -9986,15 +18839,15 @@ }, { "type": "object", - "required": ["items"], "properties": { "items": { "type": "array", "items": { - "$ref": "#/components/schemas/UserContentPermission" + "$ref": "#/components/schemas/Organization" } } - } + }, + "required": ["items"] } ] } @@ -10005,13 +18858,55 @@ "$ref": "#/components/responses/UnexpectedError" } } + }, + "post": { + "operationId": "createOrganization", + "summary": "Create an organization", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestCreateOrganization" + } + } + } + }, + "responses": { + "201": { + "description": "Organization created", + "headers": { + "Location": { + "description": "API URL for the newly created organization", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } } }, - "/spaces/{spaceId}/publishing/auth": { + "/orgs/{organizationId}": { "get": { - "operationId": "getSpacePublishingAuthById", - "summary": "Get the publishing authentication configuration for a space.", - "tags": ["spaces"], + "operationId": "getOrganizationById", + "summary": "Get an organization by its ID", + "tags": ["organizations"], "security": [ { "user": [] @@ -10019,7 +18914,7 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/organizationId" } ], "responses": { @@ -10028,23 +18923,51 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" + "$ref": "#/components/schemas/Organization" } } } }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "404": { + "description": "No matching organization found for given id", + "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "post": { - "operationId": "updateSpacePublishingAuthById", - "summary": "Update the publishing authentication configuration for a space.", - "tags": ["spaces"], + "delete": { + "operationId": "deleteOrganizationById", + "summary": "Delete an organization by its ID", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "205": { + "description": "The organization has been successfully deleted" + }, + "404": { + "description": "No matching organization found for given id", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateOrganizationById", + "summary": "Update an organization by its ID", + "tags": ["organizations"], "security": [ { "user": [] @@ -10052,7 +18975,7 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/organizationId" } ], "requestBody": { @@ -10060,23 +18983,68 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTitle" + }, + "emailDomains": { + "$ref": "#/components/schemas/OrganizationEmailDomains" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "defaultContent": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationDefaultContent" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "logo": { + "oneOf": [ + { + "$ref": "#/components/schemas/URL" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "sso": { + "type": "boolean" + }, + "ai": { + "type": "boolean" + }, + "aiInsights": { + "type": "boolean" + } + } } } } }, "responses": { "200": { - "description": "OK", + "description": "The organization has been updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" + "$ref": "#/components/schemas/Organization" } } } }, "400": { + "description": "Invalid default content space or collection provided", "$ref": "#/components/responses/BadRequestError" }, "default": { @@ -10085,41 +19053,91 @@ } } }, - "/spaces/{spaceId}/integration-blocks": { + "/orgs/{organizationId}/members": { "get": { - "operationId": "listSpaceIntegrationsBlocks", - "summary": "List integrations blocks for a space", - "tags": ["integrations"], + "operationId": "listMembersInOrganizationById", + "summary": "List organization members", + "description": "Lists members for the specified organization.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "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" + } } ], "responses": { "200": { - "description": "list of installed integration blocks", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SpaceIntegrationBlocks" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationMember" + } + } + } + } + ] } } } }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/spaces/{spaceId}/custom-fields": { + "/orgs/{organizationId}/members/{userId}": { "get": { - "operationId": "getSpaceCustomFields", - "summary": "Get the values of the custom fields set on a space", - "tags": ["spaces"], + "operationId": "getMemberInOrganizationById", + "summary": "Get specified organization member", + "description": "Gets a specific member in an organization.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10127,7 +19145,10 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" } ], "responses": { @@ -10136,7 +19157,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomFieldValues" + "$ref": "#/components/schemas/OrganizationMember" } } } @@ -10147,9 +19168,10 @@ } }, "patch": { - "operationId": "updateSpaceCustomFields", - "summary": "Update the custom fields in a space", - "tags": ["spaces"], + "operationId": "updateMemberInOrganizationById", + "summary": "Update specified organization member", + "description": "Updates a specific member in an organization.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10157,22 +19179,64 @@ ], "parameters": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" } ], + "responses": { + "200": { + "description": "The member has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationMember" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateCustomFieldValues" + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + } + } } } } - }, + } + }, + "delete": { + "operationId": "removeMemberFromOrganizationById", + "summary": "Delete a member from an organization", + "description": "Deletes a specific member from an organization\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" + } + ], "responses": { "204": { - "description": "Custom fields updated" + "description": "The member was deleted from the organization." }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -10180,11 +19244,12 @@ } } }, - "/collections/{collectionId}": { - "get": { - "operationId": "getCollectionById", - "summary": "Get the details about a collection using its ID", - "tags": ["collections"], + "/orgs/{organizationId}/ping": { + "post": { + "operationId": "updateOrganizationMemberLastSeenAt", + "summary": "Update organization member's \"last seen at\" timestamp.", + "description": "Update organization member's \"last seen at\" timestamp.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10192,29 +19257,24 @@ ], "parameters": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/parameters/organizationId" } ], "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" - } - } - } + "204": { + "description": "Organization member has been updated." }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, - "patch": { - "operationId": "updateCollectionById", - "summary": "Update the details of a collection", - "tags": ["collections"], + } + }, + "/orgs/{organizationId}/members/{userId}/sso": { + "post": { + "operationId": "setUserAsSSOMemberForOrganization", + "summary": "Set a user as an SSO member of an organization", + "tags": ["organizations"], "security": [ { "user": [] @@ -10222,31 +19282,19 @@ ], "parameters": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" - } - } - } - } - } - }, "responses": { "200": { - "description": "The collection has been updated", + "description": "The user has been added as an SSO member of the organization.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Collection" + "$ref": "#/components/schemas/OrganizationMember" } } } @@ -10257,11 +19305,11 @@ } } }, - "/collections/{collectionId}/spaces": { + "/orgs/{organizationId}/members/{userId}/spaces": { "get": { - "operationId": "listSpacesInCollectionById", - "summary": "List all the spaces in a collection by its ID.", - "tags": ["collections"], + "operationId": "listSpacesForOrganizationMember", + "summary": "List permissions accross all spaces for a member of an organization", + "tags": ["permissions", "spaces"], "security": [ { "user": [] @@ -10269,7 +19317,10 @@ ], "parameters": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/listPage" @@ -10280,7 +19331,7 @@ ], "responses": { "200": { - "description": "OK", + "description": "Listing of spaces that can be accessed by the user in the organization.", "content": { "application/json": { "schema": { @@ -10295,7 +19346,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Space" + "$ref": "#/components/schemas/MemberContentPermission" } } } @@ -10311,11 +19362,11 @@ } } }, - "/collections/{collectionId}/permissions/aggregate": { + "/orgs/{organizationId}/members/{userId}/teams": { "get": { - "operationId": "listPermissionsAggregateInCollection", - "summary": "List permissions for all users in a collection.", - "tags": ["permissions", "spaces"], + "operationId": "listTeamsForOrganizationMember", + "summary": "List all teams an organization member is part of", + "tags": ["teams"], "security": [ { "user": [] @@ -10323,7 +19374,10 @@ ], "parameters": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/listPage" @@ -10332,17 +19386,17 @@ "$ref": "#/components/parameters/listLimit" }, { - "name": "role", "in": "query", - "description": "If defined, only members with this role will be returned.", + "name": "title", + "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", "schema": { - "$ref": "#/components/schemas/MemberRole" + "type": "string" } } ], "responses": { "200": { - "description": "Listing of users who can access the collections.", + "description": "OK", "content": { "application/json": { "schema": { @@ -10357,7 +19411,16 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/UserContentPermission" + "type": "object", + "required": ["team", "member"], + "properties": { + "team": { + "$ref": "#/components/schemas/OrganizationTeam" + }, + "member": { + "$ref": "#/components/schemas/TeamMember" + } + } } } } @@ -10373,44 +19436,12 @@ } } }, - "/collections/{collectionId}/publishing/auth": { + "/orgs/{organizationId}/teams": { "get": { - "operationId": "getCollectionPublishingAuthById", - "summary": "Get the publishing authentication configuration for a collection.", - "tags": ["collections"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/collectionId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "updateCollectionPublishingAuthById", - "summary": "Update the publishing authentication configuration for a collection.", - "tags": ["collections"], + "operationId": "listTeamsInOrganizationById", + "summary": "List organization teams", + "description": "Lists teams for the specified organization.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10418,45 +19449,8 @@ ], "parameters": [ { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "$ref": "#/components/parameters/organizationId" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations": { - "get": { - "operationId": "listIntegrations", - "summary": "List all public integrations", - "tags": ["integrations"], - "parameters": [ { "$ref": "#/components/parameters/listPage" }, @@ -10464,27 +19458,25 @@ "$ref": "#/components/parameters/listLimit" }, { - "name": "category", "in": "query", - "description": "Filter the integrations by category", + "name": "owner", + "description": "The unique identifier of a member of the organization. Only teams they can manage will be returned.", "schema": { - "$ref": "#/components/schemas/IntegrationCategory" + "type": "string" } }, { - "name": "blockDomain", "in": "query", - "description": "Filter the integrations by block's domains", + "name": "title", + "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", "schema": { - "type": "string", - "pattern": "^[a-zA-Z0-9-_.]+$", - "maxLength": 100 + "type": "string" } } ], "responses": { "200": { - "description": "Paginated list of integrations", + "description": "OK", "content": { "application/json": { "schema": { @@ -10499,7 +19491,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Integration" + "$ref": "#/components/schemas/OrganizationTeam" } } } @@ -10513,42 +19505,12 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/integrations/{integrationName}": { - "get": { - "operationId": "getIntegrationByName", - "summary": "Get a specific 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" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } }, - "post": { - "operationId": "publishIntegration", - "summary": "Publish an integration", - "tags": ["integrations"], + "put": { + "operationId": "createOrganizationTeam", + "summary": "Create organization team", + "description": "Creates a team in the specified organization.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10556,24 +19518,20 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" } ], "responses": { - "200": { - "description": "OK", + "201": { + "description": "Team has been created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Integration" + "$ref": "#/components/schemas/OrganizationTeam" } } } }, - "404": { - "description": "Organization could not be found for the given hostname", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } @@ -10583,63 +19541,42 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestPublishIntegration" + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTeamTitle" + }, + "members": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["title"] } } } } - }, - "delete": { - "operationId": "unpublishIntegration", - "summary": "Unpublish an integration", - "tags": ["integrations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - } - ], - "responses": { - "204": { - "description": "Integration has been deleted" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } } }, - "/integrations/{integrationName}/installations": { + "/orgs/{organizationId}/teams/{teamId}": { "get": { - "operationId": "listIntegrationInstallations", - "summary": "Fetch a list of installations of an integration", - "tags": ["integrations"], + "operationId": "getTeamInOrganizationById", + "summary": "Get specified organization team", + "description": "Gets a specific team in an organization.\n", + "tags": ["organizations"], "security": [ { - "integration": [] + "user": [] } ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/organizationId" }, { - "name": "externalId", - "in": "query", - "description": "External Id to filter by", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/teamId" } ], "responses": { @@ -10648,23 +19585,7 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationInstallation" - } - } - } - } - ] + "$ref": "#/components/schemas/OrganizationTeam" } } } @@ -10674,10 +19595,11 @@ } } }, - "post": { - "operationId": "installIntegration", - "summary": "Install integration on a target organization", - "tags": ["integrations"], + "patch": { + "operationId": "updateTeamInOrganizationById", + "summary": "Update specified organization team", + "description": "Updates a specific team in an organization.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10685,89 +19607,65 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/teamId" } ], - "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", + "200": { + "description": "The team has been updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" + "$ref": "#/components/schemas/OrganizationTeam" } } } }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTeamTitle" + } + }, + "required": ["title"] + } + } + } } - } - }, - "/integrations/{integrationName}/events": { - "get": { - "operationId": "listIntegrationEvents", - "summary": "List all integration events", - "tags": ["integrations"], - "parameters": [ + }, + "delete": { + "operationId": "removeTeamFromOrganizationById", + "summary": "Delete a team in an organization", + "description": "Deletes a specific team in an organization\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/parameters/integrationName" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/organizationId" }, { - "$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" - } - } - } - } - ] - } - } - } + "$ref": "#/components/parameters/teamId" + } + ], + "responses": { + "204": { + "description": "The team was deleted from the organization." }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -10775,81 +19673,88 @@ } } }, - "/integrations/{integrationName}/events/{eventId}": { - "get": { - "operationId": "getIntegrationEvent", - "summary": "Get a specific integration event by its id", - "tags": ["integrations"], + "/orgs/{organizationId}/teams/{teamId}/members": { + "put": { + "operationId": "updateMembersInOrganizationTeam", + "summary": "Updates members of an organization 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": ["organizations"], + "security": [ + { + "user": [] + } + ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "name": "eventId", - "in": "path", - "required": true, - "description": "ID of the integration event", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/teamId" } ], - "responses": { - "200": { - "description": "Integration event", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["event"], - "properties": { - "event": { - "$ref": "#/components/schemas/IntegrationEvent" - }, - "trace": { - "$ref": "#/components/schemas/IntegrationEventTrace" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "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." } } } } } - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + } + }, + "responses": { + "204": { + "description": "Members have been updated" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/integrations/{integrationName}/spaces": { + }, "get": { - "operationId": "listIntegrationSpaceInstallations", - "summary": "Fetch a list of space installations of an integration", - "tags": ["integrations"], + "operationId": "listTeamMembersInOrganizationById", + "summary": "List team members", + "description": "Lists members, and their roles, for the specified organization team.\n", + "tags": ["organizations"], "security": [ { - "integration": [] + "user": [] } ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/teamId" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/listPage" }, { - "name": "externalId", - "in": "query", - "description": "External Id to filter by", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/listLimit" } ], "responses": { @@ -10869,7 +19774,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" + "$ref": "#/components/schemas/OrganizationTeamMember" } } } @@ -10885,11 +19790,12 @@ } } }, - "/integrations/{integrationName}/spaces/{spaceId}/dev": { + "/orgs/{organizationId}/teams/{teamId}/members/{userId}": { "put": { - "operationId": "updateIntegrationDevSpace", - "summary": "Update the development space for an integration", - "tags": ["integrations"], + "operationId": "addMemberToOrganizationTeamById", + "summary": "Add or update a team membership", + "description": "Add or updates member in the specified organization team.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10897,37 +19803,32 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/teamId" + }, + { + "$ref": "#/components/parameters/userId" } ], "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 + "role": { + "$ref": "#/components/schemas/TeamMemberRole" } - }, - "required": ["tunnelUrl"] + } } } } }, "responses": { "204": { - "description": "Updated development space successfully" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "description": "Member has been added to the team" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -10935,9 +19836,10 @@ } }, "delete": { - "operationId": "removeIntegrationDevSpace", - "summary": "Remove the development space for an integration", - "tags": ["integrations"], + "operationId": "deleteMemberFromOrganizationTeamById", + "summary": "Delete members from a team", + "description": "Deletes member from the specified organization team.\n", + "tags": ["organizations"], "security": [ { "user": [] @@ -10945,19 +19847,18 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/teamId" + }, + { + "$ref": "#/components/parameters/userId" } ], "responses": { "204": { - "description": "Removed development space successfully" - }, - "404": { - "description": "No matching integration dev space found", - "$ref": "#/components/responses/NotFoundError" + "description": "Member has been deleted from the team" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -10965,69 +19866,98 @@ } } }, - "/integrations/{integrationName}/render": { - "get": { - "operationId": "renderIntegrationUIWithGet", - "summary": "Render an integration UI in the context of an installation.", - "parameters": [ + "/orgs/{organizationId}/invites": { + "post": { + "operationId": "inviteUsersToOrganization", + "summary": "Invite users to a given organization based on a list of emails", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/parameters/integrationName" - }, + "user": [] + } + ], + "parameters": [ { - "name": "request", - "in": "query", - "required": true, - "description": "LZ-string compressed JSON request", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { - "description": "ContentKit element to render", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentKitRenderOutput" - } - } - }, - "headers": { - "Cache-Control": { - "schema": { - "type": "string" + "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" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RequestInviteUsersToOrganization" + } + } + } } - }, + } + }, + "/orgs/{organizationId}/invites/{inviteId}": { "post": { - "operationId": "renderIntegrationUIWithPost", - "summary": "Render an integration UI in the context of an installation.", + "operationId": "joinOrganizationWithInvite", + "summary": "Use an invite to join an organization.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/inviteId" } ], "responses": { "200": { - "description": "ContentKit element to render", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentKitRenderOutput" - } - } - }, - "headers": { - "Cache-Control": { - "schema": { - "type": "string" + "type": "object", + "properties": {} } } } @@ -11035,32 +19965,22 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestRenderIntegrationUI" - } - } - } } } }, - "/integrations/{integrationName}/tasks": { + "/orgs/{organizationId}/link-invites": { "post": { - "operationId": "queueIntegrationTask", - "summary": "Queue a task for an integration to be executed later", - "tags": ["integrations"], + "operationId": "createOrganizationInvite", + "summary": "Create a new organization invite", + "tags": ["organizations"], "security": [ { - "integration": [] + "user": [] } ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" } ], "requestBody": { @@ -11068,30 +19988,21 @@ "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"] + "$ref": "#/components/schemas/CreateOrganizationInvite" } } } }, "responses": { - "204": { - "description": "Integration task created successfully" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "201": { + "description": "The organization invite has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationInvite" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -11099,11 +20010,11 @@ } } }, - "/integrations/{integrationName}/installations/{installationId}": { - "get": { - "operationId": "getIntegrationInstallationById", - "summary": "Get a specific integration's installation by its ID", - "tags": ["integrations"], + "/orgs/{organizationId}/link-invites/{inviteId}": { + "patch": { + "operationId": "updateOrganizationInviteById", + "summary": "Update an organization invite.", + "tags": ["organizations"], "security": [ { "user": [] @@ -11111,35 +20022,63 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/installationId" + "$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": "Integration installation", + "description": "The organization invite has been updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" + "$ref": "#/components/schemas/OrganizationInvite" } } } }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "patch": { - "operationId": "updateIntegrationInstallation", - "summary": "Update external IDs and configurations of an integration's installation", - "tags": ["integrations"], + "delete": { + "operationId": "deleteOrganizationInviteById", + "summary": "Deletes an organization invite.", + "tags": ["organizations"], "security": [ { "user": [] @@ -11147,19 +20086,44 @@ ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/parameters/inviteId" + } + ], + "responses": { + "205": { + "description": "The organization invite has been deleted" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/billing": { + "post": { + "operationId": "upgradeOrganizationPlan", + "summary": "Upgrade an organization's billing plan", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { - "description": "The installation has been updated.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" + "$ref": "#/components/schemas/BillingUpgrade" } } } @@ -11173,35 +20137,36 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestUpdateIntegrationInstallation" + "$ref": "#/components/schemas/RequestUpgradeOrganizationBilling" } } } } }, - "delete": { - "operationId": "uninstallIntegration", - "summary": "Uninstall the integration from a target organization", - "tags": ["integrations"], + "get": { + "operationId": "getOrganizationBillingPortal", + "summary": "Get the billing portal for an organization", + "tags": ["organizations"], "security": [ { - "user": [] + "user-internal": [] } ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/parameters/organizationId" } ], "responses": { - "204": { - "description": "Integration uninstalled successfully" - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingPortal" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -11209,106 +20174,52 @@ } } }, - "/integrations/{integrationName}/installations/{installationId}/tokens": { + "/orgs/{organizationId}/request_upgrade": { "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"], + "operationId": "requestOrganizationUpgrade", + "summary": "Send a request to ask the organization's admin to upgrade it.", + "tags": ["organizations"], "security": [ { - "integration": [] + "user-internal": [] } ], "parameters": [ { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/parameters/organizationId" } ], "responses": { "200": { - "description": "The API token for the installation", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/APITemporaryToken" + "type": "object", + "properties": {} } } } }, - "404": { - "description": "Installation could not be found", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/integrations/{integrationName}/installations/{installationId}/spaces": { - "get": { - "operationId": "listIntegrationInstallationSpaces", - "summary": "List installations on spaces for an integration in an organization", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" - }, - { - "$ref": "#/components/parameters/listPage" - }, + "/orgs/{organizationId}/transfer": { + "post": { + "operationId": "transferOrganization", + "summary": "Transfer one organization (source) into another organization (target).", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/parameters/listLimit" + "user": [] } ], - "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" - } - } - } - } - ] - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "installIntegrationOnSpace", - "summary": "Install integration on a space using an existing installation", "parameters": [ { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/parameters/organizationId" } ], "requestBody": { @@ -11317,11 +20228,24 @@ "application/json": { "schema": { "type": "object", - "required": ["space"], + "required": ["source"], "properties": { - "space": { + "source": { "type": "string", - "description": "ID of the space to install the integration on" + "description": "The unique id of the organization to transfer into the current one." + }, + "defaultOrgRole": { + "description": "Determine the default role members of the source org will have when they are transferred into the target org. Defaults to null, which means no access.", + "oneOf": [ + { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + { + "type": "string", + "description": "Use SAML's default role for transferred members.", + "enum": ["saml"] + } + ] } } } @@ -11329,89 +20253,85 @@ } }, "responses": { - "201": { - "headers": { - "Location": { - "description": "URL for the installed integration", - "schema": { - "type": "string" - } - } - }, - "description": "Integration installed successfully on space", + "200": { + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" + "type": "object", + "required": ["collection"], + "properties": { + "collection": { + "type": "string", + "description": "The unique id of the collection created in the target organization containing the content of the source organization." + }, + "newSourceHostname": { + "type": "string", + "description": "The new hostname if the source organization needed to change hostname." + } + } } } } }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, - "/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}": { + "/orgs/{organizationId}/search": { "get": { - "operationId": "getIntegrationSpaceInstallation", - "summary": "Get a specific integration's space installation", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" - }, + "operationId": "searchOrganizationContent", + "summary": "Search content in an organization", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/parameters/spaceId" + "user": [] } ], - "responses": { - "200": { - "description": "Integration space installation", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" - } - } + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" } }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "patch": { - "operationId": "updateIntegrationSpaceInstallation", - "summary": "Update external IDs and configurations of an integration's installation for a space", - "parameters": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { - "description": "The space installation has been updated.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchSpaceResult" + } + } + } + } + ] } } } @@ -11419,46 +20339,14 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateIntegrationInstallation" - } - } - } - } - }, - "delete": { - "operationId": "uninstallIntegrationFromSpace", - "summary": "Uninstall the integration from a space", - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" - }, - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "204": { - "description": "The space installation has been deleted." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } } } }, - "/orgs": { + "/orgs/{organizationId}/spaces": { "get": { - "operationId": "listOrganizationsForAuthenticatedUser", - "summary": "Get the list of organizations for the currently authenticated user", + "operationId": "listSpacesInOrganizationById", + "summary": "List organization spaces", + "description": "Lists spaces for the specified organization.\n", "tags": ["organizations"], "security": [ { @@ -11466,11 +20354,22 @@ } ], "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" + }, + { + "name": "visibility", + "in": "query", + "description": "If defined, only content with this visibility will be returned.", + "schema": { + "$ref": "#/components/schemas/ContentVisibility" + } } ], "responses": { @@ -11485,15 +20384,15 @@ }, { "type": "object", + "required": ["items"], "properties": { "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Organization" + "$ref": "#/components/schemas/Space" } } - }, - "required": ["items"] + } } ] } @@ -11506,29 +20405,34 @@ } }, "post": { - "operationId": "createOrganization", - "summary": "Create an organization", - "tags": ["organizations"], + "operationId": "createSpace", + "summary": "Create an organization space", + "tags": ["spaces"], "security": [ { - "user-internal": [] + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestCreateOrganization" + "$ref": "#/components/schemas/RequestCreateSpace" } } } }, "responses": { "201": { - "description": "Organization created", + "description": "Space created", "headers": { "Location": { - "description": "API URL for the newly created organization", + "description": "API URL for the newly created space", "schema": { "type": "string" } @@ -11537,7 +20441,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Organization" + "$ref": "#/components/schemas/Space" } } } @@ -11548,10 +20452,11 @@ } } }, - "/orgs/{organizationId}": { + "/orgs/{organizationId}/spaces/gitsync": { "get": { - "operationId": "getOrganizationById", - "summary": "Get an organization by its ID", + "operationId": "listSpacesWithGitSyncInOrganizationById", + "summary": "List organization spaces including Git sync metadata", + "description": "Lists spaces including Git sync metadata for the specified organization.\n", "tags": ["organizations"], "security": [ { @@ -11561,6 +20466,20 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "status", + "in": "query", + "description": "If defined, only spaces with matching Git sync status are returned", + "schema": { + "$ref": "#/components/schemas/GitSyncOperationState" + } } ], "responses": { @@ -11569,7 +20488,33 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Organization" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "space": { + "$ref": "#/components/schemas/Space" + }, + "gitSync": { + "deprecated": true, + "$ref": "#/components/schemas/GitSyncState" + } + }, + "required": ["space"] + } + } + } + } + ] } } } @@ -11580,11 +20525,11 @@ } } }, - "/orgs/{organizationId}/members": { + "/orgs/{organizationId}/collections": { "get": { - "operationId": "listMembersInOrganizationById", - "summary": "List organization members", - "description": "Lists members for the specified organization.\n", + "operationId": "listCollectionsInOrganizationById", + "summary": "List organization collections", + "description": "Lists collections for the specified organization.\n", "tags": ["organizations"], "security": [ { @@ -11602,27 +20547,12 @@ "$ref": "#/components/parameters/listLimit" }, { - "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", + "name": "nested", "in": "query", - "description": "A query to filter the member list (displayName and email)", + "description": "If true, all nested collections will be listed", "schema": { - "type": "string" + "type": "boolean", + "default": true } } ], @@ -11643,7 +20573,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/OrganizationMember" + "$ref": "#/components/schemas/Collection" } } } @@ -11657,14 +20587,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/members/{userId}": { - "get": { - "operationId": "getMemberInOrganizationById", - "summary": "Get specified organization member", - "description": "Gets a specific member in an organization.\n", - "tags": ["organizations"], + }, + "post": { + "operationId": "createCollection", + "summary": "Create an organization collection", + "tags": ["collections"], "security": [ { "user": [] @@ -11673,18 +20600,42 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/userId" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "maxLength": 50 + }, + "parent": { + "type": "string", + "description": "ID of a parent collection" + } + } + } + } + } + }, "responses": { - "200": { - "description": "OK", + "201": { + "description": "Collection created", + "headers": { + "Location": { + "description": "API URL for the newly created collection", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationMember" + "$ref": "#/components/schemas/Collection" } } } @@ -11693,11 +20644,12 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "patch": { - "operationId": "updateMemberInOrganizationById", - "summary": "Update specified organization member", - "description": "Updates a specific member in an organization.\n", + } + }, + "/orgs/{organizationId}/custom-fields": { + "get": { + "operationId": "listOrganizationCustomFields", + "summary": "Get the custom fields for spaces in an organization", "tags": ["organizations"], "security": [ { @@ -11709,16 +20661,35 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/userId" + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" } ], "responses": { "200": { - "description": "The member has been updated", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationMember" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomField" + } + } + } + } + ] } } } @@ -11726,56 +20697,11 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest" - } - } - } - } - } } }, - "delete": { - "operationId": "removeMemberFromOrganizationById", - "summary": "Delete a member from an organization", - "description": "Deletes a specific member from an organization\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "204": { - "description": "The member was deleted from the organization." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/ping": { "post": { - "operationId": "updateOrganizationMemberLastSeenAt", - "summary": "Update organization member's \"last seen at\" timestamp.", - "description": "Update organization member's \"last seen at\" timestamp.\n", + "operationId": "createOrganizationCustomField", + "summary": "Create a new custom field in an orgamization", "tags": ["organizations"], "security": [ { @@ -11787,9 +20713,55 @@ "$ref": "#/components/parameters/organizationId" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/CustomFieldName" + }, + "type": { + "$ref": "#/components/schemas/CustomFieldType" + }, + "title": { + "$ref": "#/components/schemas/CustomFieldTitle" + }, + "description": { + "$ref": "#/components/schemas/CustomFieldDescription" + }, + "placeholder": { + "$ref": "#/components/schemas/CustomFieldPlaceholder" + }, + "options": { + "$ref": "#/components/schemas/CustomFieldOptions" + } + }, + "required": ["name", "type"] + } + } + } + }, "responses": { - "204": { - "description": "Organization member has been updated." + "201": { + "description": "Custom field created", + "headers": { + "Location": { + "description": "API URL for the newly created custom field", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomField" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -11797,10 +20769,10 @@ } } }, - "/orgs/{organizationId}/members/{userId}/sso": { - "post": { - "operationId": "setUserAsSSOMemberForOrganization", - "summary": "Set a user as an SSO member of an organization", + "/orgs/{organizationId}/custom-fields/{fieldName}": { + "get": { + "operationId": "getOrganizationCustomFieldByName", + "summary": "Get a custom field by its name", "tags": ["organizations"], "security": [ { @@ -11812,31 +20784,39 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/userId" + "name": "fieldName", + "in": "path", + "required": true, + "description": "The name of the custom field", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "The user has been added as an SSO member of the organization.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationMember" + "$ref": "#/components/schemas/CustomField" } } } }, + "404": { + "description": "No matching custom field found", + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/members/{userId}/spaces": { - "get": { - "operationId": "listSpacesForOrganizationMember", - "summary": "List permissions accross all spaces for a member of an organization", - "tags": ["permissions", "spaces"], + }, + "patch": { + "operationId": "updateOrganizationCustomField", + "summary": "Update a custom field in an organization", + "tags": ["organizations"], "security": [ { "user": [] @@ -11847,38 +20827,46 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/userId" - }, - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" + "name": "fieldName", + "in": "path", + "required": true, + "description": "The name of the custom field", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/CustomFieldTitle" + }, + "description": { + "$ref": "#/components/schemas/CustomFieldDescription" + }, + "placeholder": { + "$ref": "#/components/schemas/CustomFieldPlaceholder" + }, + "options": { + "$ref": "#/components/schemas/CustomFieldOptions" + } + } + } + } } - ], + }, "responses": { "200": { - "description": "Listing of spaces that can be accessed by the user in the organization.", + "description": "OK", "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MemberContentPermission" - } - } - } - } - ] + "$ref": "#/components/schemas/CustomField" } } } @@ -11887,13 +20875,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/members/{userId}/teams": { - "get": { - "operationId": "listTeamsForOrganizationMember", - "summary": "List all teams an organization member is part of", - "tags": ["teams"], + }, + "delete": { + "operationId": "deleteOrganizationCustomField", + "summary": "Delete a custom field in an organization", + "tags": ["organizations"], "security": [ { "user": [] @@ -11904,58 +20890,18 @@ "$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.", + "name": "fieldName", + "in": "path", + "required": true, + "description": "The name of the custom field", "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" - } - } - } - } - } - } - ] - } - } - } + "204": { + "description": "Custom field has been deleted" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -11963,17 +20909,11 @@ } } }, - "/orgs/{organizationId}/teams": { + "/orgs/{organizationId}/integrations": { "get": { - "operationId": "listTeamsInOrganizationById", - "summary": "List organization teams", - "description": "Lists teams for the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], + "operationId": "listOrganizationIntegrations", + "summary": "List integrations owned by an organization", + "tags": ["spaces"], "parameters": [ { "$ref": "#/components/parameters/organizationId" @@ -11985,17 +20925,12 @@ "$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" - } + "$ref": "#/components/schemas/IntegrationSearchQuery" } ], "responses": { "200": { - "description": "OK", + "description": "List of integrations.", "content": { "application/json": { "schema": { @@ -12010,7 +20945,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/OrganizationTeam" + "$ref": "#/components/schemas/Integration" } } } @@ -12024,12 +20959,13 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, - "put": { - "operationId": "createOrganizationTeam", - "summary": "Create organization team", - "description": "Creates a team in the specified organization.\n", - "tags": ["organizations"], + } + }, + "/orgs/{organizationId}/integrations/{integrationName}/installation_status": { + "get": { + "operationId": "getOrganizationIntegrationStatus", + "summary": "Get the status of an integration installation in an organization", + "tags": ["integrations"], "security": [ { "user": [] @@ -12038,108 +20974,87 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/integrationName" } ], "responses": { - "201": { - "description": "Team has been created", + "200": { + "description": "Integration installation status", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationTeam" + "properties": { + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + } + }, + "required": ["status"] } } } }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "title": "Title for the new team." - }, - "members": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["title"] - } - } - } } } }, - "/orgs/{organizationId}/teams/{teamId}": { + "/orgs/{organizationId}/installations": { "get": { - "operationId": "getTeamInOrganizationById", - "summary": "Get specified organization team", - "description": "Gets a specific team in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], + "operationId": "listOrganizationInstallations", + "summary": "List installations of integrations in an organization.", + "tags": ["spaces"], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/teamId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationTeam" - } - } - } + "$ref": "#/components/parameters/listPage" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "patch": { - "operationId": "updateTeamInOrganizationById", - "summary": "Update specified organization team", - "description": "Updates a specific team in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/parameters/teamId" + "$ref": "#/components/schemas/IntegrationSearchQuery" } ], "responses": { "200": { - "description": "The team has been updated", + "description": "List of integrations with the associated installations.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationTeam" + "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"] + } + } + } + } + ] } } } @@ -12147,28 +21062,13 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string" - } - }, - "required": ["title"] - } - } - } - } - }, - "delete": { - "operationId": "removeTeamFromOrganizationById", - "summary": "Delete a team in an organization", - "description": "Deletes a specific team in an organization\n", + } + } + }, + "/orgs/{organizationId}/experiments": { + "get": { + "operationId": "listOrgExperimentalFeatures", + "summary": "List experiemental features for the given organization.", "tags": ["organizations"], "security": [ { @@ -12178,26 +21078,30 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/teamId" } ], "responses": { - "204": { - "description": "The team was deleted from the organization." + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationExperimentalFeature" + } + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/teams/{teamId}/members": { - "put": { - "operationId": "updateMembersInOrganizationTeam", - "summary": "Updates members of an organization 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", + }, + "post": { + "operationId": "updateOrgExperimentalFeatures", + "summary": "Toggle on or off experimental features.", "tags": ["organizations"], "security": [ { @@ -12207,9 +21111,6 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/teamId" } ], "requestBody": { @@ -12218,27 +21119,8 @@ "application/json": { "schema": { "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." - } - } + "additionalProperties": { + "type": "boolean" } } } @@ -12246,17 +21128,18 @@ }, "responses": { "204": { - "description": "Members have been updated" + "description": "OK" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, + } + }, + "/orgs/{organizationId}/schemas": { "get": { - "operationId": "listTeamMembersInOrganizationById", - "summary": "List team members", - "description": "Lists members, and their roles, for the specified organization team.\n", + "operationId": "listEntitySchemas", + "summary": "List the entity schemas in an organization.", "tags": ["organizations"], "security": [ { @@ -12267,9 +21150,6 @@ { "$ref": "#/components/parameters/organizationId" }, - { - "$ref": "#/components/parameters/teamId" - }, { "$ref": "#/components/parameters/listPage" }, @@ -12294,7 +21174,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/OrganizationTeamMember" + "$ref": "#/components/schemas/EntitySchema" } } } @@ -12310,11 +21190,10 @@ } } }, - "/orgs/{organizationId}/teams/{teamId}/members/{userId}": { - "put": { - "operationId": "addMemberToOrganizationTeamById", - "summary": "Add or update a team membership", - "description": "Add or updates member in the specified organization team.\n", + "/orgs/{organizationId}/schemas/{entityType}": { + "get": { + "operationId": "getEntitySchema", + "summary": "Get an entity schema by its type.", "tags": ["organizations"], "security": [ { @@ -12326,29 +21205,55 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/teamId" + "$ref": "#/components/parameters/entityType" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EntitySchema" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "setEntitySchema", + "summary": "Create or update an entity schema.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/userId" + "$ref": "#/components/parameters/entityType" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "role": { - "$ref": "#/components/schemas/TeamMemberRole" - } - } + "$ref": "#/components/schemas/EntityRawSchema" } } } }, "responses": { "204": { - "description": "Member has been added to the team" + "description": "OK" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -12356,9 +21261,8 @@ } }, "delete": { - "operationId": "deleteMemberFromOrganizationTeamById", - "summary": "Delete members from a team", - "description": "Deletes member from the specified organization team.\n", + "operationId": "deleteEntitySchema", + "summary": "Delete an entity schema.", "tags": ["organizations"], "security": [ { @@ -12370,15 +21274,12 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/teamId" - }, - { - "$ref": "#/components/parameters/userId" + "$ref": "#/components/parameters/entityType" } ], "responses": { "204": { - "description": "Member has been deleted from the team" + "description": "OK" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -12386,10 +21287,10 @@ } } }, - "/orgs/{organizationId}/invites": { - "post": { - "operationId": "inviteUsersToOrganization", - "summary": "Invite users to a given organization based on a list of emails", + "/orgs/{organizationId}/schemas/{entityType}/entities": { + "get": { + "operationId": "listSchemaEntities", + "summary": "List entities in an organization for a given type.", "tags": ["organizations"], "security": [ { @@ -12399,6 +21300,23 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/entityType" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "query", + "in": "query", + "description": "Query to filter entities with, ex: a == 'something' && b >= 10", + "schema": { + "type": "string" + } } ], "responses": { @@ -12407,55 +21325,97 @@ "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" + "allOf": [ + { + "$ref": "#/components/schemas/List" }, - "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" + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Entity" + } + } } } - }, - "required": ["users", "invited"] + ] } } } }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } - }, + } + }, + "put": { + "operationId": "upsertSchemaEntities", + "summary": "Update/Create/Delete entities in a schema.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/entityType" + } + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestInviteUsersToOrganization" + "type": "object", + "properties": { + "delete": { + "oneOf": [ + { + "type": "boolean", + "description": "If true, all entities not listed in the requests will be deleted" + }, + { + "type": "array", + "description": "List of entityIds to delete", + "items": { + "$ref": "#/components/schemas/EntityId" + } + } + ] + }, + "entities": { + "type": "array", + "description": "Array of entities to create/update.", + "items": { + "$ref": "#/components/schemas/UpsertEntity" + } + } + } } } } + }, + "responses": { + "204": { + "description": "OK" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } } - }, - "/orgs/{organizationId}/invites/{inviteId}": { - "post": { - "operationId": "joinOrganizationWithInvite", - "summary": "Use an invite to join an organization.", + }, + "/orgs/{organizationId}/schemas/{entityType}/entities/{entityId}": { + "get": { + "operationId": "getEntity", + "summary": "Get an entity using its ID.", "tags": ["organizations"], "security": [ { @@ -12467,13 +21427,10 @@ "$ref": "#/components/parameters/organizationId" }, { - "name": "inviteId", - "in": "path", - "required": true, - "description": "The unique id of the invite", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/entityType" + }, + { + "$ref": "#/components/parameters/entityId" } ], "responses": { @@ -12482,8 +21439,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": {} + "$ref": "#/components/schemas/Entity" } } } @@ -12494,19 +21450,39 @@ } } }, - "/orgs/{organizationId}/billing": { - "post": { - "operationId": "upgradeOrganizationPlan", - "summary": "Upgrade an organization's billing plan", + "/orgs/{organizationId}/captures": { + "get": { + "operationId": "listCaptures", + "deprecated": true, + "summary": "List captures. Deprecated, use listSnippets instead.", + "description": "List captures in an organization, newest first.\n", "tags": ["organizations"], "security": [ { - "user-internal": [] + "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/pageFormat" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "context", + "in": "query", + "description": "The context in which the item was captured", + "schema": { + "type": "string", + "enum": ["walkthrough", "thread"] + } } ], "responses": { @@ -12515,7 +21491,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BillingUpgrade" + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Capture" + } + } + } + } + ] } } } @@ -12523,25 +21515,15 @@ "default": { "$ref": "#/components/responses/UnexpectedError" } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpgradeOrganizationBilling" - } - } - } } }, - "get": { - "operationId": "getOrganizationBillingPortal", - "summary": "Get the billing portal for an organization", + "post": { + "operationId": "startCapture", + "summary": "Start a capture", "tags": ["organizations"], "security": [ { - "user-internal": [] + "user": [] } ], "parameters": [ @@ -12549,13 +21531,48 @@ "$ref": "#/components/parameters/organizationId" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/CaptureTitle" + }, + "context": { + "$ref": "#/components/schemas/CaptureContext" + }, + "externalId": { + "type": "string", + "description": "ID in the original source of the capture." + }, + "externalURL": { + "type": "string", + "format": "uri", + "description": "URL of the original source of the capture." + } + }, + "required": ["context"] + } + } + } + }, "responses": { - "200": { - "description": "OK", + "201": { + "description": "Capture started", + "headers": { + "Location": { + "description": "API URL for the newly created capture", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BillingPortal" + "$ref": "#/components/schemas/Capture" } } } @@ -12566,19 +21583,26 @@ } } }, - "/orgs/{organizationId}/request_upgrade": { - "post": { - "operationId": "requestOrganizationUpgrade", - "summary": "Send a request to ask the organization's admin to upgrade it.", + "/orgs/{organizationId}/captures/{captureId}": { + "get": { + "operationId": "getCapture", + "deprecated": true, + "summary": "Get a capture by its ID. Deprecated, use getSnippet instead.", "tags": ["organizations"], "security": [ { - "user-internal": [] + "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/captureId" + }, + { + "$ref": "#/components/parameters/pageFormat" } ], "responses": { @@ -12587,8 +21611,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": {} + "$ref": "#/components/schemas/Capture" } } } @@ -12599,10 +21622,10 @@ } } }, - "/orgs/{organizationId}/transfer": { + "/orgs/{organizationId}/captures/{captureId}/events": { "post": { - "operationId": "transferOrganization", - "summary": "Transfer one organization (source) into another organization (target).", + "operationId": "addEventsToCapture", + "summary": "Add events to a running capture", "tags": ["organizations"], "security": [ { @@ -12612,59 +21635,32 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/captureId" } ], "requestBody": { - "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": ["source"], "properties": { - "source": { - "type": "string", - "description": "The unique id of the organization to transfer into the current one." - }, - "defaultOrgRole": { - "description": "Determine the default role members of the source org will have when they are transferred into the target org. Defaults to null, which means no access.", - "oneOf": [ - { - "$ref": "#/components/schemas/MemberRoleOrGuest" - }, - { - "type": "string", - "description": "Use SAML's default role for transferred members.", - "enum": ["saml"] - } - ] + "events": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CaptureEvent" + } } - } + }, + "required": ["events"] } } } }, "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["collection"], - "properties": { - "collection": { - "type": "string", - "description": "The unique id of the collection created in the target organization containing the content of the source organization." - }, - "newSourceHostname": { - "type": "string", - "description": "The new hostname if the source organization needed to change hostname." - } - } - } - } - } + "204": { + "description": "Events added" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -12672,10 +21668,10 @@ } } }, - "/orgs/{organizationId}/search": { - "get": { - "operationId": "searchOrganizationContent", - "summary": "Search content in an organization", + "/orgs/{organizationId}/captures/{captureId}/stop": { + "post": { + "operationId": "stopCapture", + "summary": "Stop a capture", "tags": ["organizations"], "security": [ { @@ -12683,47 +21679,46 @@ } ], "parameters": [ - { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } - }, { "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/parameters/captureId" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/pageFormat" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": {} + } + } + } + }, "responses": { "200": { - "description": "OK", + "description": "Capture stopped", "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" + "type": "object", + "properties": { + "capture": { + "$ref": "#/components/schemas/Capture" }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchSpaceResult" - } - } + "followupQuestions": { + "description": "Example questions that would be answered by the content of this capture.", + "type": "array", + "items": { + "type": "string" } } - ] + }, + "required": ["capture"] } } } @@ -12734,11 +21729,11 @@ } } }, - "/orgs/{organizationId}/spaces": { + "/orgs/{organizationId}/snippets": { "get": { - "operationId": "listSpacesInOrganizationById", - "summary": "List organization spaces", - "description": "Lists spaces for the specified organization.\n", + "operationId": "listSnippets", + "summary": "Lists snippets.", + "description": "List snippets in an organization, newest first.\n", "tags": ["organizations"], "security": [ { @@ -12756,11 +21751,11 @@ "$ref": "#/components/parameters/listLimit" }, { - "name": "visibility", + "name": "source", "in": "query", - "description": "If defined, only content with this visibility will be returned.", + "description": "If specified, only snippets from the specified source will be returned.", "schema": { - "$ref": "#/components/schemas/ContentVisibility" + "type": "string" } } ], @@ -12781,7 +21776,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Space" + "$ref": "#/components/schemas/Snippet" } } } @@ -12797,9 +21792,9 @@ } }, "post": { - "operationId": "createSpace", - "summary": "Create an organization space", - "tags": ["spaces"], + "operationId": "createSnippet", + "summary": "Create a new snippet", + "tags": ["organizations"], "security": [ { "user": [] @@ -12814,17 +21809,17 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/RequestCreateSpace" + "type": "object" } } } }, "responses": { "201": { - "description": "Space created", + "description": "Snippet created", "headers": { "Location": { - "description": "API URL for the newly created space", + "description": "API URL for the newly created snippet", "schema": { "type": "string" } @@ -12833,7 +21828,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Space" + "$ref": "#/components/schemas/Snippet" } } } @@ -12844,11 +21839,10 @@ } } }, - "/orgs/{organizationId}/spaces/gitsync": { + "/orgs/{organizationId}/snippets/{snippetId}": { "get": { - "operationId": "listSpacesWithGitSyncInOrganizationById", - "summary": "List organization spaces including Git sync metadata", - "description": "Lists spaces including Git sync metadata for the specified organization.\n", + "operationId": "getSnippet", + "summary": "Get a snippet by its ID", "tags": ["organizations"], "security": [ { @@ -12860,18 +21854,7 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" - }, - { - "name": "status", - "in": "query", - "description": "If defined, only spaces with matching Git sync status are returned", - "schema": { - "$ref": "#/components/schemas/GitSyncOperationState" - } + "$ref": "#/components/parameters/snippetId" } ], "responses": { @@ -12880,32 +21863,7 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "space": { - "$ref": "#/components/schemas/Space" - }, - "gitSync": { - "$ref": "#/components/schemas/GitSyncState" - } - }, - "required": ["space"] - } - } - } - } - ] + "$ref": "#/components/schemas/Snippet" } } } @@ -12914,13 +21872,10 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/collections": { - "get": { - "operationId": "listCollectionsInOrganizationById", - "summary": "List organization collections", - "description": "Lists collections for the specified organization.\n", + }, + "delete": { + "operationId": "deleteSnippet", + "summary": "Delete a snippet by its ID.", "tags": ["organizations"], "security": [ { @@ -12932,125 +21887,55 @@ "$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 - } + "$ref": "#/components/parameters/snippetId" } ], "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" - } - } - } - } - ] - } - } - } + "description": "OK" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/dsync": { - "post": { - "operationId": "setupDirectorySync", - "summary": "Set up Directory Sync in an organization.", - "tags": ["organizations", "dsync"], + }, + "put": { + "operationId": "updateSnippet", + "summary": "Update an existing snippet.", + "tags": ["organizations"], "security": [ { - "user-internal": [] + "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "Directory Sync has been properly initialized for the organization.", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["setupUrl"], - "properties": { - "setupUrl": { - "description": "The URL to navigate to to continue Directory Sync setup.", - "type": "string" - } - } - } - } - } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/dsync/groups": { - "get": { - "operationId": "listDirectorySyncGroups", - "summary": "Lists the groups exposed to the synced Directory on an organization.", - "tags": ["organizations", "dsync"], - "security": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/parameters/snippetId" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/parameters/ifUnmodifiedSince" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSnippetSchema" + } + } + } + }, "responses": { "200": { - "description": "A list of all of a Directory's group configured for the given identity provider.\nOnly groups pushed to the SCIM sync will be listed in this result.\n", + "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "description": "All the groups.", - "required": ["groups"], - "properties": { - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationDirectorySyncGroup" - } - } - } + "$ref": "#/components/schemas/Snippet" } } } @@ -13061,20 +21946,22 @@ } } }, - "/orgs/{organizationId}/dsync/teams": { + "/orgs/{organizationId}/snippets/{snippetId}/move": { "post": { - "operationId": "syncDirectorySyncGroupsToTeams", - "summary": "Syncs a list of group/team unique identifiers pairs together.", - "description": "Each pair will lead the team being synced to the group (unless it is already synced to another) and the members of the group will then be synced to the team.\nEach sync is independent, the endpoint will still succeed if some of the syncs fail.\nCheck the response to know more about the success or failure of the entire sync.\n", - "tags": ["organizations", "dsync"], + "operationId": "moveSnippet", + "summary": "Move a snippet into a destination. The snippet will be archived in the process.", + "tags": ["organizations"], "security": [ { - "user-internal": [] + "user": [] } ], "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/snippetId" } ], "requestBody": { @@ -13083,26 +21970,31 @@ "application/json": { "schema": { "type": "object", - "description": "Parameters for syncing a list of Directory Sync groups to a GitBook team, syncing all members of those groups to the assigned teams.\nThe endpoint can be used for one or many groups to team syncs.\n", - "required": ["to_sync"], + "required": ["target"], "properties": { - "to_sync": { - "type": "array", - "description": "A list of groups to teams pairs to sync.\nThe group_id is required and the team_id is optional.\nIf the latter is omitted, a new team will be created from the group's data.\n", - "items": { - "type": "object", - "required": ["group_id"], - "properties": { - "group_id": { - "type": "string", - "description": "The unique identifier of the group for the given identity provider." - }, - "team_id": { - "type": "string", - "description": "The unique identifier of the team for the given identity provider." + "target": { + "type": "object", + "description": "Intended destination for the page", + "properties": { + "space": { + "description": "The id of the target space", + "type": "string" + }, + "position": { + "type": "object", + "properties": { + "parent": { + "description": "The parent of the page in the target space. If undefined, the page will be inserted at the root of the space.", + "type": "string" + }, + "index": { + "description": "The index of the page in the parent. If undefined, the page will be inserted at the end of the parent's current children.", + "type": "number" + } } } - } + }, + "required": ["space"] } } } @@ -13111,19 +22003,18 @@ }, "responses": { "200": { - "description": "A list of the results of the synchronization.\nThis will return regardless of the status of the sync.\nCheck the content to know if the sync was successful.\n", + "description": "The snippet was successfully moved.", "content": { "application/json": { "schema": { "type": "object", - "required": ["synced"], + "required": ["page"], "properties": { - "synced": { - "type": "array", - "description": "The list of synced pairs, mapped to the original pairs given to the sync parameters.\nEither the group_id and team_id will be defined, or the error will be defined to describe why it failed.\nUse the success parameter to know if the pair sync was sucessful or not.\n", - "items": { - "$ref": "#/components/schemas/OrganizationDirectorySyncGroupTeamStatus" - } + "page": { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + "changeRequest": { + "$ref": "#/components/schemas/ChangeRequest" } } } @@ -13134,12 +22025,10 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/custom-fields": { + }, "get": { - "operationId": "listOrganizationCustomFields", - "summary": "Get the custom fields for spaces in an organization", + "operationId": "getSnippetSuggestedLocations", + "summary": "Return possible snippet locations in an organization based on the current user.", "tags": ["organizations"], "security": [ { @@ -13150,16 +22039,43 @@ { "$ref": "#/components/parameters/organizationId" }, + { + "$ref": "#/components/parameters/snippetId" + }, { "$ref": "#/components/parameters/listPage" }, { "$ref": "#/components/parameters/listLimit" + }, + { + "name": "spaceId", + "in": "query", + "description": "If specified, only locations in the given space will be returned. If not specified, GitBook will suggest spaces.", + "schema": { + "type": "string" + } + }, + { + "name": "pageId", + "in": "query", + "description": "If specified, only locations under the given pageId will be returned. You must specify a spaceId too. If pageId is not specified, GitBook will suggest pages at the top level.", + "schema": { + "type": "string" + } + }, + { + "name": "search", + "in": "query", + "description": "If specified, only locations matching the search query will be returned.", + "schema": { + "type": "string" + } } ], "responses": { "200": { - "description": "OK", + "description": "A paginated list of suggested snippet locations.", "content": { "application/json": { "schema": { @@ -13174,7 +22090,28 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomField" + "type": "object", + "required": ["space"], + "properties": { + "aiPowered": { + "type": "boolean", + "description": "If defined and true, this location was suggested by GitBook AI." + }, + "space": { + "$ref": "#/components/schemas/Space" + }, + "parentPage": { + "description": "The parent page of the suggested location.", + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] + } + } } } } @@ -13188,10 +22125,12 @@ "$ref": "#/components/responses/UnexpectedError" } } - }, + } + }, + "/orgs/{organizationId}/synced-blocks": { "post": { - "operationId": "createOrganizationCustomField", - "summary": "Create a new custom field in an orgamization", + "operationId": "createSyncedBlock", + "summary": "Create a new synced block", "tags": ["organizations"], "security": [ { @@ -13209,37 +22148,26 @@ "application/json": { "schema": { "type": "object", + "required": ["document"], "properties": { - "name": { - "$ref": "#/components/schemas/CustomFieldName" - }, - "type": { - "$ref": "#/components/schemas/CustomFieldType" - }, "title": { - "$ref": "#/components/schemas/CustomFieldTitle" - }, - "description": { - "$ref": "#/components/schemas/CustomFieldDescription" - }, - "placeholder": { - "$ref": "#/components/schemas/CustomFieldPlaceholder" + "type": "string", + "description": "Title of synced block" }, - "options": { - "$ref": "#/components/schemas/CustomFieldOptions" + "document": { + "$ref": "#/components/schemas/Document" } - }, - "required": ["name", "type"] + } } } } }, "responses": { "201": { - "description": "Custom field created", + "description": "Synced block created", "headers": { "Location": { - "description": "API URL for the newly created custom field", + "description": "API URL for the newly created synced block", "schema": { "type": "string" } @@ -13248,7 +22176,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomField" + "$ref": "#/components/schemas/SyncedBlock" } } } @@ -13259,10 +22187,10 @@ } } }, - "/orgs/{organizationId}/custom-fields/{fieldName}": { + "/orgs/{organizationId}/synced-blocks/{syncedBlockId}": { "get": { - "operationId": "getOrganizationCustomFieldByName", - "summary": "Get a custom field by its name", + "operationId": "getSyncedBlock", + "summary": "Get a synced block by its ID", "tags": ["organizations"], "security": [ { @@ -13274,13 +22202,7 @@ "$ref": "#/components/parameters/organizationId" }, { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/syncedBlockId" } ], "responses": { @@ -13289,23 +22211,19 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomField" + "$ref": "#/components/schemas/SyncedBlock" } } } }, - "404": { - "description": "No matching custom field found", - "$ref": "#/components/responses/NotFoundError" - }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "patch": { - "operationId": "updateOrganizationCustomField", - "summary": "Update a custom field in an organization", + "put": { + "operationId": "updateSyncedBlock", + "summary": "Update an existing synced block.", "tags": ["organizations"], "security": [ { @@ -13317,13 +22235,7 @@ "$ref": "#/components/parameters/organizationId" }, { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/syncedBlockId" } ], "requestBody": { @@ -13334,16 +22246,8 @@ "type": "object", "properties": { "title": { - "$ref": "#/components/schemas/CustomFieldTitle" - }, - "description": { - "$ref": "#/components/schemas/CustomFieldDescription" - }, - "placeholder": { - "$ref": "#/components/schemas/CustomFieldPlaceholder" - }, - "options": { - "$ref": "#/components/schemas/CustomFieldOptions" + "type": "string", + "description": "A new title for the Synced Block." } } } @@ -13352,24 +22256,18 @@ }, "responses": { "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomField" - } - } - } + "description": "OK" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, - "delete": { - "operationId": "deleteOrganizationCustomField", - "summary": "Delete a custom field in an organization", - "tags": ["organizations"], + } + }, + "/orgs/{organizationId}/ask": { + "post": { + "operationId": "askInOrganization", + "summary": "Ask a question.", "security": [ { "user": [] @@ -13380,18 +22278,34 @@ "$ref": "#/components/parameters/organizationId" }, { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/pageFormat" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIQuery" + } + } + } + }, "responses": { - "204": { - "description": "Custom field has been deleted" + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -13399,45 +22313,58 @@ } } }, - "/orgs/{organizationId}/integrations": { + "/orgs/{organizationId}/ask/questions": { "get": { - "operationId": "listOrganizationIntegrations", - "summary": "List integrations owned by an organization", - "tags": ["spaces"], + "operationId": "getRecommendedQuestionsInOrganization", + "summary": "Get a list of questions recommended to be asked in an organization.", "parameters": [ { "$ref": "#/components/parameters/organizationId" - }, + } + ], + "security": [ { - "$ref": "#/components/parameters/listPage" + "user": [] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestions" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/ask/questions/stream": { + "get": { + "operationId": "streamRecommendedQuestionsInOrganization", + "summary": "Stream a list of questions recommended to be asked in an organization.", + "parameters": [ { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/organizationId" + } + ], + "security": [ + { + "user": [] } ], "responses": { "200": { - "description": "List of integrations.", + "description": "OK", "content": { - "application/json": { + "text/event-stream": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Integration" - } - } - } - } - ] + "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" } } } @@ -13448,54 +22375,38 @@ } } }, - "/orgs/{organizationId}/installations": { + "/orgs/{organizationId}/ask/stream": { "get": { - "operationId": "listOrganizationInstallations", - "summary": "List installations of integrations in an organization.", - "tags": ["spaces"], + "operationId": "streamAskInOrganization", + "summary": "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.", + "security": [ + { + "user": [] + } + ], "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/listPage" + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/pageFormat" } ], "responses": { "200": { - "description": "List of integrations with the associated installations.", + "description": "OK", "content": { - "application/json": { + "text/event-stream": { "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"] - } - } - } - } - ] + "$ref": "#/components/schemas/SearchAIAnswerStream" } } } @@ -13506,11 +22417,11 @@ } } }, - "/orgs/{organizationId}/schemas": { + "/orgs/{organizationId}/insights/audit-relations": { "get": { - "operationId": "listEntitySchemas", - "summary": "List the entity schemas in an organization.", - "tags": ["organizations"], + "operationId": "listContentAuditRelations", + "summary": "List the content relations for in a given organization.", + "tags": ["ai", "spaces"], "security": [ { "user": [] @@ -13525,11 +22436,56 @@ }, { "$ref": "#/components/parameters/listLimit" + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "Status of the audit relation to filter on", + "schema": { + "default": "pending", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentAuditRelationStatus" + }, + { + "type": "string", + "enum": ["all"] + } + ] + } + }, + { + "name": "space", + "in": "query", + "required": false, + "description": "Space concerned by the relation", + "schema": { + "type": "string" + } + }, + { + "name": "type", + "in": "query", + "required": false, + "description": "Type of the audit relation to filter on", + "schema": { + "default": "all", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentAuditRelationType" + }, + { + "type": "string", + "enum": ["all"] + } + ] + } } ], "responses": { "200": { - "description": "OK", + "description": "Content audit relations", "content": { "application/json": { "schema": { @@ -13544,7 +22500,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/EntitySchema" + "$ref": "#/components/schemas/ContentAuditRelation" } } } @@ -13560,10 +22516,10 @@ } } }, - "/orgs/{organizationId}/schemas/{entityType}": { + "/orgs/{organizationId}/insights/audit-relations/{relationId}": { "get": { - "operationId": "getEntitySchema", - "summary": "Get an entity schema by its type.", + "operationId": "getContentAuditRelationById", + "summary": "Get an audit relation by ID", "tags": ["organizations"], "security": [ { @@ -13575,7 +22531,7 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/entityType" + "$ref": "#/components/parameters/relationId" } ], "responses": { @@ -13584,19 +22540,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitySchema" + "$ref": "#/components/schemas/ContentAuditRelation" } } } }, + "404": { + "description": "No matching content relation found for given ID", + "$ref": "#/components/responses/NotFoundError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } }, - "put": { - "operationId": "setEntitySchema", - "summary": "Create or update an entity schema.", + "patch": { + "operationId": "updateContentAuditRelationStatusById", + "summary": "Update an audit relation status", "tags": ["organizations"], "security": [ { @@ -13608,7 +22568,7 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/entityType" + "$ref": "#/components/parameters/relationId" } ], "requestBody": { @@ -13616,23 +22576,36 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntityRawSchema" + "$ref": "#/components/schemas/ContentAuditRelationStatusUpdate" } } } }, "responses": { - "204": { - "description": "OK" + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentAuditRelation" + } + } + } + }, + "404": { + "description": "No matching content relation found for given ID", + "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, - "delete": { - "operationId": "deleteEntitySchema", - "summary": "Delete an entity schema.", + } + }, + "/orgs/{organizationId}/insights/audit-sources/{sourceId}/content": { + "get": { + "operationId": "getContentAuditSourceContentById", + "summary": "Get the content of an audit source", "tags": ["organizations"], "security": [ { @@ -13644,12 +22617,32 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/entityType" + "name": "sourceId", + "in": "path", + "required": true, + "description": "The id of the content audit source", + "schema": { + "type": "string" + } + }, + { + "$ref": "#/components/parameters/pageFormat" } ], "responses": { - "204": { - "description": "OK" + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Document" + } + } + } + }, + "404": { + "description": "No matching content source found for given ID", + "$ref": "#/components/responses/NotFoundError" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -13657,11 +22650,11 @@ } } }, - "/orgs/{organizationId}/schemas/{entityType}/entities": { + "/orgs/{organizationId}/sites": { "get": { - "operationId": "listSchemaEntities", - "summary": "List entities in an organization for a given type.", - "tags": ["organizations"], + "operationId": "listSites", + "summary": "List all the sites created in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -13671,9 +22664,6 @@ { "$ref": "#/components/parameters/organizationId" }, - { - "$ref": "#/components/parameters/entityType" - }, { "$ref": "#/components/parameters/listPage" }, @@ -13681,9 +22671,10 @@ "$ref": "#/components/parameters/listLimit" }, { - "name": "query", + "name": "space", "in": "query", - "description": "Query to filter entities with, ex: a == 'something' && b >= 10", + "description": "Identifier of the space to filter the sites by", + "required": false, "schema": { "type": "string" } @@ -13706,7 +22697,7 @@ "items": { "type": "array", "items": { - "$ref": "#/components/schemas/Entity" + "$ref": "#/components/schemas/Site" } } } @@ -13721,10 +22712,10 @@ } } }, - "put": { - "operationId": "upsertSchemaEntities", - "summary": "Update/Create/Delete entities in a schema.", - "tags": ["organizations"], + "post": { + "operationId": "createSite", + "summary": "Create a site in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -13733,38 +22724,25 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/entityType" } ], "requestBody": { - "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { - "delete": { - "oneOf": [ - { - "type": "boolean", - "description": "If true, all entities not listed in the requests will be deleted" - }, - { - "type": "array", - "description": "List of entityIds to delete", - "items": { - "$ref": "#/components/schemas/EntityId" - } - } - ] + "title": { + "$ref": "#/components/schemas/SiteTitle" }, - "entities": { + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "spaces": { "type": "array", - "description": "Array of entities to create/update.", + "description": "ID of spaces to be added to the site", "items": { - "$ref": "#/components/schemas/UpsertEntity" + "type": "string" } } } @@ -13773,8 +22751,23 @@ } }, "responses": { - "204": { - "description": "OK" + "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" + } + } + } }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -13782,11 +22775,11 @@ } } }, - "/orgs/{organizationId}/schemas/{entityType}/entities/{entityId}": { + "/orgs/{organizationId}/sites/{siteId}": { "get": { - "operationId": "getEntity", - "summary": "Get an entity using its ID.", - "tags": ["organizations"], + "operationId": "getSiteById", + "summary": "Get an organization site by its ID", + "tags": ["sites"], "security": [ { "user": [] @@ -13797,19 +22790,81 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/entityType" + "$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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateSiteById", + "summary": "Update a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/entityId" + "$ref": "#/components/parameters/siteId" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/SiteTitle" + }, + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "hostname": { + "$ref": "#/components/schemas/SiteHostname" + }, + "basename": { + "$ref": "#/components/schemas/SiteBasename" + }, + "defaultSiteSpace": { + "type": "string", + "description": "ID of the site-space to be used as the default" + } + } + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Entity" + "$ref": "#/components/schemas/Site" } } } @@ -13818,14 +22873,11 @@ "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/captures": { - "get": { - "operationId": "listCaptures", - "summary": "List captures", - "description": "List captures in an organization, newest first.\n", - "tags": ["organizations"], + }, + "delete": { + "operationId": "deleteSiteById", + "summary": "Delete a site in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -13836,22 +22888,35 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "205": { + "description": "Site has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/publishing/auth": { + "get": { + "operationId": "getSitePublishingAuthSettings", + "summary": "Get the publishing authentication settings for a site.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/parameters/listPage" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/parameters/organizationId" }, { - "name": "context", - "in": "query", - "description": "The context in which the item was captured", - "schema": { - "type": "string", - "enum": ["walkthrough", "thread"] - } + "$ref": "#/components/parameters/siteId" } ], "responses": { @@ -13860,36 +22925,25 @@ "content": { "application/json": { "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Capture" - } - } - } - } - ] + "$ref": "#/components/schemas/SitePublishingAuth" } } } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - }, + } + }, + "/orgs/{organizationId}/sites/{siteId}/spaces": { "post": { - "operationId": "startCapture", - "summary": "Start a capture", - "tags": ["organizations"], + "operationId": "addSpaceToSite", + "summary": "Add a space to a site in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -13898,41 +22952,34 @@ "parameters": [ { "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/siteId" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { - "title": { - "$ref": "#/components/schemas/CaptureTitle" - }, - "context": { - "$ref": "#/components/schemas/CaptureContext" - }, - "externalId": { - "type": "string", - "description": "ID in the original source of the capture." - }, - "externalURL": { + "spaceId": { "type": "string", - "format": "uri", - "description": "URL of the original source of the capture." + "description": "ID of the space" } }, - "required": ["context"] + "required": ["spaceId"] } } } }, "responses": { "201": { - "description": "Capture started", + "description": "Space added to the site", "headers": { "Location": { - "description": "API URL for the newly created capture", + "description": "API URL for the newly created site-space relationship", "schema": { "type": "string" } @@ -13941,7 +22988,62 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Capture" + "$ref": "#/components/schemas/SiteSpace" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "get": { + "operationId": "listSiteSpaces", + "summary": "List all the site spaces under a site in an organization", + "tags": ["sites"], + "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/SiteSpace" + } + } + } + } + ] } } } @@ -13952,11 +23054,11 @@ } } }, - "/orgs/{organizationId}/captures/{captureId}": { - "get": { - "operationId": "getCapture", - "summary": "Get a capture by its ID", - "tags": ["organizations"], + "/orgs/{organizationId}/sites/{siteId}/spaces/{siteSpaceId}": { + "patch": { + "operationId": "updateSiteSpaceById", + "summary": "Update a space on a site in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -13967,19 +23069,34 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/captureId" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/parameters/siteSpaceId" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "path": { + "$ref": "#/components/schemas/SiteSpacePath" + } + } + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Capture" + "$ref": "#/components/schemas/SiteSpace" } } } @@ -13990,9 +23107,9 @@ } }, "delete": { - "operationId": "deleteCapture", - "summary": "Delete a capture by its ID", - "tags": ["organizations"], + "operationId": "deleteSiteSpaceById", + "summary": "Delete a space on a site in an organization", + "tags": ["sites"], "security": [ { "user": [] @@ -14003,12 +23120,15 @@ "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/parameters/captureId" + "$ref": "#/components/parameters/siteId" + }, + { + "$ref": "#/components/parameters/siteSpaceId" } ], "responses": { - "200": { - "description": "OK" + "205": { + "description": "Site space has been deleted" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -14016,22 +23136,49 @@ } } }, - "/orgs/{organizationId}/captures/{captureId}/events": { - "post": { - "operationId": "addEventsToCapture", - "summary": "Add events to a running capture", - "tags": ["organizations"], + "/custom-hostnames/{hostname}": { + "get": { + "operationId": "getCustomHostname", + "summary": "Get the details about a custom hostname.", + "tags": ["custom-hostnames"], "security": [ { - "user": [] + "user-internal": [] } ], "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/parameters/hostname" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomHostname" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "setupCustomHostname", + "summary": "Setup a custom hostname on a content or an organization. Any previously set custom hostname will continue pointing to the target but marked as available for use with another target.", + "tags": ["custom-hostnames"], + "security": [ { - "$ref": "#/components/parameters/captureId" + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/hostname" } ], "requestBody": { @@ -14040,82 +23187,101 @@ "schema": { "type": "object", "properties": { - "events": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CaptureEvent" - } + "target": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationPointer" + }, + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + } + ] } }, - "required": ["events"] + "required": ["target"] } } } }, "responses": { - "204": { - "description": "Events added" + "201": { + "description": "Custom hostname created", + "headers": { + "Location": { + "description": "API URL for the newly created custom hostname", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomHostname" + } + } + } + }, + "409": { + "description": "Custom hostname is already in use on the target", + "$ref": "#/components/responses/ConflictError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/orgs/{organizationId}/captures/{captureId}/stop": { - "post": { - "operationId": "stopCapture", - "summary": "Stop a capture", - "tags": ["organizations"], + }, + "patch": { + "operationId": "dnsRevalidateCustomHostname", + "summary": "Revalidate a custom hostname's DNS records and status.", + "tags": ["custom-hostnames"], "security": [ { - "user": [] + "user-internal": [] } ], "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/parameters/hostname" + } + ], + "responses": { + "204": { + "description": "DNS validation has been retriggered" }, - { - "$ref": "#/components/parameters/captureId" + "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" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "removeCustomHostname", + "summary": "Remove a custom hostname from a content or organization. The custom hostname will continue to point to the content or organization unless it is used for another one.", + "tags": ["custom-hostnames"], + "security": [ { - "$ref": "#/components/parameters/pageFormat" + "user-internal": [] } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } + "parameters": [ + { + "$ref": "#/components/parameters/hostname" } - }, + ], "responses": { - "200": { - "description": "Capture stopped", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "capture": { - "$ref": "#/components/schemas/Capture" - }, - "followupQuestions": { - "description": "Example questions that would be answered by the content of this capture.", - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["capture"] - } - } - } + "205": { + "description": "Custom hostname has been removed" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -14123,45 +23289,57 @@ } } }, - "/orgs/{organizationId}/ask": { + "/custom-hostnames/{hostname}/test": { "post": { - "operationId": "askInOrganization", - "summary": "Ask a question.", + "operationId": "testCustomHostname", + "summary": "Test if a custom hostname can be used for a content or organization.", + "tags": ["custom-hostnames"], "security": [ { - "user": [] + "user-internal": [] } ], "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/parameters/hostname" } ], "requestBody": { - "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SearchAIQuery" + "type": "object", + "properties": { + "target": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationPointer" + }, + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + } + ] + } + }, + "required": ["target"] } } } }, "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } - } - } - } + "204": { + "description": "The custom hostname is available and valid." + }, + "400": { + "description": "The custom hostname is invalid.", + "$ref": "#/components/responses/BadRequestError" + }, + "409": { + "description": "The custom hostname is already configured for this target or a different one.", + "$ref": "#/components/responses/ConflictError" }, "default": { "$ref": "#/components/responses/UnexpectedError" @@ -14319,6 +23497,52 @@ } } } + }, + "/urls/published": { + "get": { + "operationId": "getPublishedContentByUrl", + "summary": "Resolve a URL of a published content.", + "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 visitor auth session", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublishedContentLookup" + } + } + } + }, + "404": { + "description": "No content found for the URL.", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } } } } diff --git a/tests/gitbook.test.ts b/tests/gitbook.test.ts index b8d2f8f..db30680 100644 --- a/tests/gitbook.test.ts +++ b/tests/gitbook.test.ts @@ -231,3 +231,90 @@ test('GET spaces/space_iphone-doc/content/path/apps%2Fphone', () => { }, }); }); + +test('GET spaces/space_iphone-doc/revisions/somerevision/files', () => { + const result = validateRequest({ + path: '/spaces/space_iphone-doc/revisions/somerevision/files', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: {}, + }); + expect(result).toMatchObject({ + operationId: 'listFilesInRevisionById', + params: { + spaceId: 'space_iphone-doc', + revisionId: 'somerevision', + }, + }); +}); + +test('GET spaces/space_iphone-doc/revisions/somerevision/files?limit=1', () => { + const result = validateRequest({ + path: '/spaces/space_iphone-doc/revisions/somerevision/files', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: { + limit: '1', + }, + }); + expect(result).toMatchObject({ + operationId: 'listFilesInRevisionById', + query: { + limit: 1, + }, + params: { + spaceId: 'space_iphone-doc', + revisionId: 'somerevision', + }, + }); +}); + +test('GET spaces/space_iphone-doc/revisions/somerevision/files?metadata=false', () => { + const result = validateRequest({ + path: '/spaces/space_iphone-doc/revisions/somerevision/files', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: { + metadata: 'false', + }, + }); + expect(result).toMatchObject({ + operationId: 'listFilesInRevisionById', + query: { + metadata: false, + }, + params: { + spaceId: 'space_iphone-doc', + revisionId: 'somerevision', + }, + }); +}); + +test('GET spaces/space_iphone-doc/revisions/somerevision/files?metadata=true', () => { + const result = validateRequest({ + path: '/spaces/space_iphone-doc/revisions/somerevision/files', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: { + metadata: 'true', + }, + }); + expect(result).toMatchObject({ + operationId: 'listFilesInRevisionById', + query: { + metadata: true, + }, + params: { + spaceId: 'space_iphone-doc', + revisionId: 'somerevision', + }, + }); +});