diff --git a/bun.lockb b/bun.lockb index 5bcabd9..20d7ad4 100755 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/src/compileOperation.ts b/src/compileOperation.ts index ea8fe50..e87a83b 100644 --- a/src/compileOperation.ts +++ b/src/compileOperation.ts @@ -140,11 +140,14 @@ export function compileOperation( const parameter = compiler.resolveMaybeRef(refParameter); const paramValueIdentifier = builders.identifier(`queryParam${index}`); const resultIdentifier = builders.identifier(`queryParamResult${index}`); + const schemaFn = compileValueSchema(compiler, parameter.schema); + const isArrayType = 'type' in parameter.schema && parameter.schema.type === 'array'; + // Assign the query parameter to a variable nodes.push( - builders.variableDeclaration('const', [ + builders.variableDeclaration('let', [ builders.variableDeclarator( paramValueIdentifier, builders.memberExpression( @@ -179,6 +182,29 @@ export function compileOperation( : [], ), builders.blockStatement([ + // If expected type is array, convert to array if it's a string + ...(isArrayType + ? [ + builders.ifStatement( + // typeof paramValue === 'string' + builders.binaryExpression( + '===', + builders.unaryExpression('typeof', paramValueIdentifier), + builders.literal('string'), + ), + builders.blockStatement([ + // paramValue = [paramValue] + builders.expressionStatement( + builders.assignmentExpression( + '=', + paramValueIdentifier, + builders.arrayExpression([paramValueIdentifier]), + ), + ), + ]), + ), + ] + : []), // Validate the value builders.variableDeclaration('const', [ builders.variableDeclarator( diff --git a/src/compileValidateRequest.ts b/src/compileValidateRequest.ts index 3aaa6db..123b5d3 100644 --- a/src/compileValidateRequest.ts +++ b/src/compileValidateRequest.ts @@ -9,9 +9,9 @@ import { annotateWithJSDocComment } from './comments'; const COMMENT = ` Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} `; /** diff --git a/src/tests/__snapshots__/compileValueSchema.test.ts.snap b/src/tests/__snapshots__/compileValueSchema.test.ts.snap index 9e6ad9d..584bfdf 100644 --- a/src/tests/__snapshots__/compileValueSchema.test.ts.snap +++ b/src/tests/__snapshots__/compileValueSchema.test.ts.snap @@ -3,9 +3,9 @@ exports[`Number basic 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -42,9 +42,9 @@ function obj0(path, value, context) { exports[`Number maximum 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -84,9 +84,9 @@ function obj0(path, value, context) { exports[`Number maximum exclusiveMaximum 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -126,9 +126,9 @@ function obj0(path, value, context) { exports[`Number minimum 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -168,9 +168,9 @@ function obj0(path, value, context) { exports[`Number minimim exclusiveMinimum 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -210,9 +210,9 @@ function obj0(path, value, context) { exports[`Integer basic 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -249,9 +249,9 @@ function obj0(path, value, context) { exports[`Nullable nullable: true 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -291,9 +291,9 @@ function obj0(path, value, context) { exports[`String with enum 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -327,9 +327,9 @@ function obj0(path, value, context) { exports[`String with pattern 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -367,9 +367,9 @@ function obj0(path, value, context) { exports[`String with pattern 2`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -407,9 +407,9 @@ function obj0(path, value, context) { exports[`Objects with a required prop 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -485,9 +485,9 @@ function obj0(path, value, context) { exports[`Objects with a default value 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -545,9 +545,9 @@ function obj0(path, value, context) { exports[`Objects as free form object 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -582,9 +582,9 @@ function obj0(path, value, context) { exports[`Objects with additionalProperties: true 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -642,9 +642,9 @@ function obj0(path, value, context) { exports[`Objects with additionalProperties: {} 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -718,9 +718,9 @@ function obj0(path, value, context) { exports[`Objects with minProperties/maxProperties 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -761,9 +761,9 @@ function obj0(path, value, context) { exports[`Array minItems / maxItems 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -819,9 +819,9 @@ function obj0(path, value, context) { exports[`Array uniqueItems 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -876,9 +876,9 @@ function obj0(path, value, context) { exports[`anyOf 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -932,9 +932,9 @@ function obj0(path, value, context) { exports[`oneOf 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -995,9 +995,9 @@ function obj0(path, value, context) { exports[`allOf 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); diff --git a/src/tests/__snapshots__/compiler.test.ts.snap b/src/tests/__snapshots__/compiler.test.ts.snap index 29c55cd..f0ec8e4 100644 --- a/src/tests/__snapshots__/compiler.test.ts.snap +++ b/src/tests/__snapshots__/compiler.test.ts.snap @@ -3,9 +3,9 @@ exports[`components ref 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); @@ -79,9 +79,9 @@ function obj1(path, value, context) { exports[`recursive refs 1`] = ` "/** Validate a request against the OpenAPI spec -@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate +@param {{ method: string; path: string; body?: any; query: Record; headers: Record; }} request - Input request to validate @param {{ stringFormats?: { [format: string]: (value: string, path: string[]) => ValidationError | null } }} [context] - Context object to pass to validation functions -@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} +@returns {{ operationId?: string; params: Record; query: Record; body?: any; headers: Record; }} */ export function validateRequest(request, context) { return new RequestError(404, 'no operation match path'); diff --git a/tests/gitbook.json b/tests/gitbook.json index c8ea624..39e7550 100644 --- a/tests/gitbook.json +++ b/tests/gitbook.json @@ -38,23510 +38,27220 @@ "integration-installation": [] } ], - "components": { - "securitySchemes": { - "user": { - "type": "http", - "scheme": "bearer" - }, - "user-internal": { - "type": "http", - "scheme": "bearer" - }, - "user-staff": { - "type": "http", - "scheme": "bearer" - }, - "integration": { - "type": "http", - "scheme": "bearer" - }, - "integration-installation": { - "type": "http", - "scheme": "bearer" + "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" + } + } } }, - "parameters": { - "listLimit": { - "name": "limit", - "in": "query", - "description": "The number of results per page", - "schema": { - "type": "number", - "maximum": 100, - "minimum": 0 - } - }, - "listPage": { - "name": "page", - "in": "query", - "description": "Identifier of the page results to fetch.", - "schema": { - "type": "string" - } - }, - "listOrder": { - "name": "order", - "in": "query", - "description": "An order for the items in the list", - "schema": { - "type": "string", - "default": "desc", - "enum": ["asc", "desc"] - } - }, - "pageFormat": { - "name": "format", - "in": "query", - "description": "Output format for the content.", - "schema": { - "type": "string", - "enum": ["document", "markdown"] - } - }, - "documentSchema": { - "name": "schema", - "in": "query", - "description": "Version of the schema used for the document.", - "schema": { - "type": "string", - "enum": ["current", "next"] + "/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" + } } - }, - "commentStatus": { - "name": "status", - "in": "query", - "description": "When provided, only comments with the given status are returned. Defaults to \"all\".", - "schema": { - "type": "string", - "default": "all", - "enum": ["all", "open", "resolved"] + } + }, + "/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/documentFormat" + }, + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } }, - "commentTargetPage": { - "name": "targetPage", - "in": "query", - "description": "The target page of the comment", - "schema": { - "type": "string" + "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/documentFormat" + }, + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIQuery" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "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": { - "name": "spaceId", - "in": "path", - "required": true, - "description": "The unique id of the space", - "schema": { - "type": "string" - } - }, - "collectionId": { - "name": "collectionId", - "in": "path", - "required": true, - "description": "The unique id of the collection", - "schema": { - "type": "string" - } - }, - "revisionId": { - "name": "revisionId", - "in": "path", - "required": true, - "description": "The unique id of the revision", - "schema": { - "type": "string" - } - }, - "changeRequestId": { - "name": "changeRequestId", - "in": "path", - "required": true, - "description": "The unique ID of the change request or its number identifier in the space", - "schema": { - "type": "string" - } - }, - "commentId": { - "name": "commentId", - "in": "path", - "required": true, - "description": "The unique id of the comment", - "schema": { - "type": "string" - } - }, - "commentReplyId": { - "name": "commentReplyId", - "in": "path", - "required": true, - "description": "The unique id of the comment reply", - "schema": { - "type": "string" - } - }, - "integrationName": { - "name": "integrationName", - "in": "path", - "required": true, - "description": "Name of the integration.", - "schema": { - "type": "string", - "pattern": "^[a-zA-Z0-9-_.]+$", - "maxLength": 100 - } - }, - "installationId": { - "name": "installationId", - "in": "path", - "required": true, - "description": "Identifier of the installation", - "schema": { - "type": "string" - } - }, - "siteId": { - "name": "siteId", - "in": "path", - "required": true, - "description": "The unique id of the site", - "schema": { - "type": "string" - } - }, - "siteSpaceId": { - "name": "siteSpaceId", - "in": "path", - "required": true, - "description": "The unique id of the site-space relationship", - "schema": { - "type": "string" - } - }, - "organizationId": { - "name": "organizationId", - "in": "path", - "required": true, - "description": "The unique id of the organization", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "captureId": { - "name": "captureId", - "in": "path", - "required": true, - "description": "The unique id of a capture", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "snippetId": { - "name": "snippetId", - "in": "path", - "required": true, - "description": "The unique id of a snippet", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "syncedBlockId": { - "name": "syncedBlockId", - "in": "path", - "required": true, - "description": "The unique id of a synced block", - "schema": { - "type": "string" + } + }, + "/spaces/{spaceId}": { + "get": { + "operationId": "getSpaceById", + "summary": "Get the details about a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/siteShareKey" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } }, - "userId": { - "name": "userId", - "in": "path", - "required": true, - "description": "The unique ID of the User", - "schema": { - "type": "string" + "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" + }, + "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" + } } }, - "teamId": { - "name": "teamId", - "in": "path", - "required": true, - "description": "The unique ID of the Team", - "schema": { - "type": "string" + "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" + } } - }, - "pageId": { - "name": "pageId", - "in": "path", - "required": true, - "description": "The unique id of the page", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "fileId": { - "name": "fileId", - "in": "path", - "required": true, - "description": "The unique id of the file", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "pagePath": { - "name": "pagePath", - "in": "path", - "required": true, - "description": "The path of the page in the revision.", - "schema": { - "type": "string" + } + }, + "/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" + }, + "412": { + "description": "The space cannot be moved.", + "$ref": "#/components/responses/PreconditionFailedError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/embed": { + "get": { + "operationId": "getEmbedByUrlInSpace", + "summary": "Resolve a URL to an embed in a given space", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "name": "url", + "in": "query", + "required": true, + "description": "URL to resolve", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Embed" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "entityId": { - "name": "entityId", - "in": "path", - "required": true, - "description": "ID of the entity in the space", - "schema": { - "$ref": "#/components/schemas/EntityId" + } + }, + "/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" + } } - }, - "entityType": { - "name": "entityType", - "in": "path", - "required": true, - "description": "Type of the entity", - "schema": { - "$ref": "#/components/schemas/EntityType" + } + }, + "/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/documentFormat" + }, + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } }, - "relationId": { - "name": "relationId", - "in": "path", - "required": true, - "description": "The id of the content audit relation", - "schema": { - "type": "string" + "post": { + "operationId": "askQueryInSpace", + "summary": "Ask a question to an AI within the context of the space.", + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + }, + { + "$ref": "#/components/parameters/documentFormat" + }, + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIQuery" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "visitorId": { - "name": "visitorId", - "in": "path", - "required": true, - "description": "The id of the visitor", - "schema": { - "type": "string" + } + }, + "/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/documentFormat" + }, + { + "name": "details", + "in": "query", + "description": "Ensure that the response is never null", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SearchAIAnswerStream" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "inviteId": { - "name": "inviteId", - "in": "path", - "required": true, - "description": "The unique id of the invite", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "shareLinkId": { - "name": "shareLinkId", - "in": "path", - "required": true, - "description": "The unique id of the share link", - "schema": { - "type": "string" + } + }, + "/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" + } } - }, - "hostname": { - "name": "hostname", - "in": "path", - "required": true, - "description": "The custom hostname, for example \"docs.gitbook.com\"", - "schema": { - "type": "string" + } + }, + "/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/ImportGitRepository" + } + } + } } - }, - "backofficeHostname": { - "name": "hostname", - "in": "path", - "required": true, - "description": "The custom hostname", - "schema": { - "type": "string" + } + }, + "/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/ExportToGitRepository" + } + } + } } - }, - "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" + } + }, + "/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/SyncGitRepository" + } + } + } } } }, - "schemas": { - "Error": { - "type": "object", - "required": ["error"], - "properties": { - "error": { - "type": "object", - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" + "/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" + } } - }, - "required": ["code", "message"] + } + }, + "404": { + "description": "No Git provider currently set up on the space", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "List": { - "type": "object", - "properties": { - "next": { - "type": "object", - "properties": { - "page": { - "type": "string", - "description": "Unique identifier to query the next results page" + } + }, + "/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" + } } - }, - "required": ["page"] + } }, - "count": { - "type": "number", - "description": "Total count of objects in the list" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "URL": { - "type": "string", - "format": "uri" - }, - "Color": { - "type": "string", - "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$" - }, - "Timestamp": { - "type": "string", - "format": "date-time" - }, - "Emoji": { - "type": "string", - "maxLength": 50, - "description": "Unicode codepoint or character of the emoji", - "example": "🎉" - }, - "EmojiReaction": { - "type": "object", - "description": "An emoji reaction by one or many users", - "properties": { - "emoji": { - "type": "string", - "description": "The Emoji of the reaction" - }, - "count": { - "type": "number", - "description": "The number of users who reacted with this emoji" + } + }, + "/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" }, - "users": { - "type": "array", - "description": "The users who reacted with this emoji", - "items": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/User" - }, - "reactedAt": { - "$ref": "#/components/schemas/Timestamp" + { + "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" } - }, - "required": ["user", "reactedAt"] + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["emoji", "count", "users"] - }, - "EmojiReactions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EmojiReaction" } - }, - "RequestSpaceTrackPageView": { - "type": "object", - "properties": { - "pageId": { - "type": "string", - "description": "Unique identifier of the page." + } + }, + "/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" }, - "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" + { + "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" } - }, - "ip": { - "type": "string", - "description": "IP address of the visitor.\nIf undefined, it'll default to the IP executing the request.\n" - }, - "userAgent": { - "type": "string", - "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" - }, - "language": { - "type": "string", - "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" } - }, - "required": ["anonymousId", "cookies", "userAgent"] + } }, - "url": { - "type": "string", - "description": "The GitBook content's URL visited (including URL params)." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/insights/track_view": { + "post": { + "operationId": "trackViewInSpaceById", + "summary": "Track a page view in a space", + "description": "Track a page view in a space.", + "tags": ["analytics", "spaces"], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "Page view has been tracked." }, - "referrer": { - "type": "string", - "description": "The URL of referrer that linked to the page." + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["visitor", "url", "referrer"] - }, - "RequestPublishIntegration": { - "type": "object", - "properties": { - "icon": { - "type": "string", - "format": "byte", - "description": "Base64 content of the icon" - }, - "title": { - "$ref": "#/components/schemas/IntegrationTitle" - }, - "description": { - "$ref": "#/components/schemas/IntegrationDescription" - }, - "summary": { - "$ref": "#/components/schemas/IntegrationSummary" - }, - "previewImages": { - "type": "array", - "maxItems": 3, - "items": { - "type": "string", - "format": "byte", - "description": "Base64 content of the image" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SpaceTrackPageView" + } } + } + } + } + }, + "/spaces/{spaceId}/permissions": { + "post": { + "operationId": "inviteToSpace", + "summary": "Invite to a space (only teams supported for now)", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "OK" }, - "visibility": { - "$ref": "#/components/schemas/IntegrationVisibility" - }, - "target": { - "description": "Allowed installation target for the integration. If not specified, the integration can be installed at `all` targets (org, spaces etc)", - "$ref": "#/components/schemas/IntegrationTarget" - }, - "scopes": { - "$ref": "#/components/schemas/IntegrationScopes" - }, - "categories": { - "$ref": "#/components/schemas/IntegrationCategories" - }, - "blocks": { - "$ref": "#/components/schemas/IntegrationBlocks" - }, - "externalLinks": { - "$ref": "#/components/schemas/IntegrationExternalLinks" - }, - "configurations": { - "$ref": "#/components/schemas/IntegrationConfigurations" - }, - "script": { - "type": "string", - "description": "Content of the script to use" - }, - "organization": { - "type": "string", - "description": "The ID or subdomain of the organization under which the integration should be published" - }, - "secrets": { - "$ref": "#/components/schemas/IntegrationSecrets" - }, - "contentSecurityPolicy": { - "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" + "404": { + "description": "No team with the provided Id", + "$ref": "#/components/responses/NotFoundError" }, - "entities": { - "type": "array", - "maxItems": 100, - "items": { - "$ref": "#/components/schemas/EntityRawSchema" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["organization", "title", "description", "script", "scopes"] - }, - "RequestUpdateIntegrationInstallation": { - "type": "object", - "properties": { - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" - }, - "configuration": { - "$ref": "#/components/schemas/IntegrationInstallationConfiguration" - }, - "space_selection": { - "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteEmailsUsersTeamsToSpace" + } + } } } - }, - "RequestUpdateIntegrationSpaceInstallation": { - "type": "object", - "properties": { - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" - }, - "configuration": { - "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + } + }, + "/spaces/{spaceId}/permissions/teams/{teamId}": { + "delete": { + "operationId": "removeTeamFromSpace", + "summary": "Remove a team from a space", + "tags": ["spaces"], + "security": [ + { + "user": [] } - } - }, - "RequestUpdateIntegrationSiteInstallation": { - "type": "object", - "properties": { - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "configuration": { - "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + { + "$ref": "#/components/parameters/teamId" } - } - }, - "RequestUpgradeOrganizationBilling": { - "type": "object", - "properties": { - "product": { - "$ref": "#/components/schemas/BillingProduct" + ], + "responses": { + "205": { + "description": "The team has been removed from the space" }, - "interval": { - "$ref": "#/components/schemas/BillingInterval" + "400": { + "description": "Team does not have access to space", + "$ref": "#/components/responses/BadRequestError" }, - "reason": { - "type": "string", - "description": "Reason that triggered the billing upgrade" + "404": { + "description": "No team found with the given ID", + "$ref": "#/components/responses/NotFoundError" }, - "mode": { - "type": "string", - "description": "Mode to use for the upgrade (default value is `commit`): - `auto`: user is redirect to checkout if possible, other a preview of the auto-upgrade is returned. - `commit`: a checkout session is returned or an auto-upgrade is done - `preview`: a preview invoice is always returned\n", - "enum": ["auto", "commit", "preview"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["product", "interval"] - }, - "RequestInviteUsersToOrganization": { - "type": "object", - "properties": { - "emails": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string", - "description": "The email address of the user to invite as a member" - }, - { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address of the user to invite as a member" - }, - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest" - } - }, - "required": ["email", "role"] + } + } + }, + "/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" } - ] + } } }, - "role": { - "description": "Default role to set on newly invited members.", - "$ref": "#/components/schemas/MemberRoleOrGuest" + "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" + } + } + } }, - "sso": { - "description": "If true, invites the user as an SSO user of the organization. Defaults to false.", - "type": "boolean" + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["emails"] - }, - "RequestImportGitRepository": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "URL of the Git repository to import. It can contain basic auth credentials." - }, - "ref": { - "type": "string", - "description": "Git ref to import in the format \"refs/heads/main\"" - }, - "repoCacheID": { - "type": "string", - "description": "Unique identifier to use to cache the Git repository across multiple operations." - }, - "repoTreeURL": { - "type": "string", - "description": "URL to use as a prefix for external file references." - }, - "repoCommitURL": { - "type": "string", - "description": "URL to use as a prefix for the commit URL." - }, - "repoProjectDirectory": { - "type": "string", - "description": "Path to a root directory for the project in the repository." - }, - "timestamp": { - "description": "The timestamp of the event that triggered this import. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.\n", - "$ref": "#/components/schemas/Timestamp" - }, - "force": { - "type": "boolean" - }, - "standalone": { - "type": "boolean", - "description": "If true, the import will generate a revision without updating the space primary content." + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContent" + } + } + } + } + } + }, + "/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" }, - "gitInfo": { - "description": "Optional metadata to store on the space about the Git provider", - "$ref": "#/components/schemas/RequestUpdateSpaceGitInfo" + { + "$ref": "#/components/parameters/revisionMetadata" } - }, - "required": ["url", "ref"] - }, - "RequestSyncGitRepository": { - "type": "object", - "properties": { - "ref": { - "type": "string", - "description": "Git ref in the format \"refs/heads/main\"" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + } + }, + "required": ["pages"] + } + } + } }, - "repoURL": { - "type": "string", - "description": "URL of the Git repository used for synchronization. It can contain basic auth credentials." + "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" }, - "repoTreeURL": { - "type": "string", - "description": "URL to use as a prefix for external file references." + { + "$ref": "#/components/parameters/listPage" }, - "repoCommitURL": { - "type": "string", - "description": "URL to use as a prefix for the commit URL." + { + "$ref": "#/components/parameters/listLimit" }, - "repoProjectDirectory": { - "type": "string", - "description": "Path to a root directory for the project in the repository." + { + "$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" + } + } + } + } + ] + } + } + } }, - "commitMessageTemplate": { - "type": "string", - "description": "Template message for the commit generated during the synchronization." + "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" }, - "standalone": { - "type": "boolean", - "description": "If true, the synchronization of the ref will generate a revision without updating the space primary content." + { + "$ref": "#/components/parameters/fileId" }, - "force": { - "type": "object", - "description": "Whether to force the synchronization", - "properties": { - "priority": { - "type": "string", - "enum": ["gitbook", "git"] + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionFile" + } } - }, - "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" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": [ - "ref", - "repoURL", - "repoTreeURL", - "repoCommitURL", - "commitMessageTemplate" - ] - }, - "RequestExportToGitRepository": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "URL of the Git repository to export to. It can contain basic auth credentials." - }, - "ref": { - "type": "string", - "description": "Git ref to push the commit to in the format \"refs/heads/main\"" - }, - "commitMessage": { - "type": "string", - "description": "Message for the commit generated by the export" + } + } + }, + "/spaces/{spaceId}/content/files/{fileId}/backlinks": { + "get": { + "operationId": "listSpaceFileBacklinks", + "summary": "Get backlink locations for a file existing in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "repoCacheID": { - "type": "string", - "description": "Unique identifier to use to cache the Git repository across multiple operations." + { + "$ref": "#/components/parameters/fileId" }, - "repoTreeURL": { - "type": "string", - "description": "URL to use as a prefix for external file references." + { + "$ref": "#/components/parameters/listPage" }, - "repoCommitURL": { - "type": "string", - "description": "URL to use as a prefix for the commit URL." + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocation" + } + } + } + } + ] + } + } + } }, - "repoProjectDirectory": { - "type": "string", - "description": "Path to a root directory for the project in the repository." + "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" }, - "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" + { + "$ref": "#/components/parameters/pageId" }, - "force": { - "type": "boolean" + { + "$ref": "#/components/parameters/documentFormat" }, - "gitInfo": { - "description": "Optional metadata to store on the space about the Git provider", - "$ref": "#/components/schemas/RequestUpdateSpaceGitInfo" + { + "$ref": "#/components/parameters/revisionMetadata" } - }, - "required": ["url", "ref", "commitMessage"] - }, - "RequestImportContent": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "URL of the content to import." + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } + } + } }, - "source": { - "$ref": "#/components/schemas/ImportContentSource" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["url", "source"] - }, - "RequestCreateSpace": { - "type": "object", - "properties": { - "title": { - "type": "string", - "maxLength": 50 + } + } + }, + "/spaces/{spaceId}/content/pages/{pageId}/backlinks": { + "get": { + "operationId": "listSpacePageBacklinks", + "summary": "Get backlink locations for a page existing in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "emoji": { - "$ref": "#/components/schemas/Emoji" + { + "$ref": "#/components/parameters/pageId" }, - "private": { - "description": "Private spaces are no longer supported by GitBook.", - "deprecated": true, - "type": "boolean" + { + "$ref": "#/components/parameters/listPage" }, - "parent": { - "type": "string", - "description": "ID of a parent collection" + { + "$ref": "#/components/parameters/listLimit" } - } - }, - "RequestCreateChangeRequest": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "Subject of the change-request" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocation" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "RequestRenderIntegrationUI": { - "type": "object", - "properties": { - "componentId": { - "type": "string", - "description": "ID of the component to render in the integration." - }, - "props": { - "type": "object", - "description": "Current properties of the UI." - }, - "state": { - "type": "object", - "description": "Current local state of the UI." + } + }, + "/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" }, - "context": { - "$ref": "#/components/schemas/ContentKitContext" + { + "$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" + } + } + } }, - "action": { - "$ref": "#/components/schemas/ContentKitAction" + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["componentId", "props", "context"] - }, - "RequestUpdateContentPublishingAuth": { - "type": "object", - "properties": { - "fallbackURL": { - "type": "string", - "format": "uri", - "description": "A fallback URL that will be used if authentication fails." + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContent" + } + } } } - }, - "RequestCreateOrganization": { - "type": "object", - "properties": { - "title": { - "$ref": "#/components/schemas/OrganizationTitle" + } + }, + "/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" }, - "emailDomains": { - "$ref": "#/components/schemas/OrganizationEmailDomains" + { + "$ref": "#/components/parameters/pagePath" }, - "type": { - "$ref": "#/components/schemas/OrganizationType" + { + "$ref": "#/components/parameters/documentFormat" }, - "useCase": { - "$ref": "#/components/schemas/OrganizationUseCase" + { + "$ref": "#/components/parameters/revisionMetadata" } - }, - "required": ["title"] - }, - "RequestUpdateSpaceGitInfo": { - "type": "object", - "description": "Update metadata about the Git provider on the space", - "properties": { - "provider": { - "type": "string", - "description": "The git provider", - "enum": ["github", "gitlab"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] + } + } + } }, - "url": { - "type": "string", - "description": "The repository's tree URL" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/documents/{documentId}": { + "get": { + "operationId": "getDocumentById", + "summary": "Get a document by its ID in a space.", + "security": [ + { + "user": [] } - } - }, - "CreateOrganizationInvite": { - "oneOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/CreateInviteToOrganization" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/CreateInviteToSpace" + "name": "documentId", + "in": "path", + "required": true, + "description": "ID of the document in the space", + "schema": { + "type": "string" + } }, { - "$ref": "#/components/schemas/CreateInviteToCollection" + "$ref": "#/components/parameters/documentSchema" } - ] - }, - "CreateInviteToSpace": { - "type": "object", - "properties": { - "level": { - "$ref": "#/components/schemas/MemberRoleOrGuest", - "description": "The level of the member in the target space" + ], + "responses": { + "200": { + "description": "Document", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/JSONDocument" + } + } + } }, - "space": { - "type": "string", - "description": "The ID of space the member has been invited to" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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" + } + } + }, + "/spaces/{spaceId}/change-requests": { + "post": { + "operationId": "createChangeRequest", + "summary": "Create a new change request for a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] } - }, - "required": ["level", "collection"] - }, - "CreateInviteToOrganization": { - "type": "object", - "properties": { - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest", - "description": "The role of the member in the organization" + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" } - }, - "required": ["role"] - }, - "ApiInformation": { - "type": "object", - "properties": { - "version": { - "type": "string", - "description": "Current release of GitBook" + ], + "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" + } + } + } }, - "build": { - "type": "string", - "description": "Date of the latest release in ISO format" - } - }, - "required": ["version", "build"] - }, - "BlockContext": { - "type": "object", - "description": "The context to send when blocking/unblocking", - "properties": { - "block": { - "type": "boolean" + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["block"] - }, - "RequestPurgeCDNCacheContext": { - "type": "object", - "description": "The context to send when purging the CDN Cache", - "properties": { - "type": { - "$ref": "#/components/schemas/PurgeCDNCacheContextType" - }, - "values": { - "type": "array", - "description": "The list of tags or hosts to purge", - "items": { - "type": "string" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChangeRequest" + } } } - }, - "required": ["type", "values"] + } }, - "TriggerContentIndexingContext": { - "type": "object", - "description": "The context to send when triggering a content indexing.", - "properties": { - "spaceId": { - "type": "string", - "description": "The unique identifier of the Space to index." + "get": { + "operationId": "listChangeRequestsForSpace", + "summary": "List change requests for a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/listPage" }, - "force": { - "type": "boolean", - "description": "Whether to force a complete re-indexing of the Space." + { + "$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" } - }, - "required": ["spaceId", "force"] - }, - "User": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"user\"", - "enum": ["user"] + ], + "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" + } + } + } + } + ] + } + } + } }, - "id": { - "type": "string", - "description": "Unique identifier for the user" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}": { + "get": { + "operationId": "getChangeRequestById", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "displayName": { - "type": "string", - "description": "Full name for the user" + { + "$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" + } + } + } }, - "email": { - "type": "string", - "description": "Email address of the user" + "404": { + "description": "The change request could not be found.", + "$ref": "#/components/responses/NotFoundError" }, - "photoURL": { - "type": "string", - "description": "URL of the user's profile picture" + "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" }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the user in the API", - "format": "uri" + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/ChangeRequestSubject" + }, + "status": { + "type": "string", + "enum": ["draft", "open", "archived"] + } + } } - }, - "required": ["location"] + } } }, - "required": ["object", "id", "displayName", "urls"] - }, - "UserAPIToken": { - "type": "object", - "description": "The API token details, excluding the token itself.", - "properties": { - "id": { - "type": "string", - "description": "The API token ID." - }, - "label": { - "type": "string", - "description": "The API token name." + "responses": { + "200": { + "description": "The change request has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeRequest" + } + } + } }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp", - "description": "The API token creation date." + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["id", "label", "createdAt"] - }, - "UserAPITokenExtended": { - "description": "The API token details, including the token itself.", - "allOf": [ + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": { + "post": { + "operationId": "mergeChangeRequest", + "summary": "Merge a change request in the primary content of a space.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/UserAPIToken" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "The actual token value." - } - }, - "required": ["token"] + "$ref": "#/components/parameters/changeRequestId" } - ] - }, - "Team": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"team\"", - "enum": ["team"] + ], + "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"] + } + } + } }, - "id": { - "type": "string", - "description": "Unique identifier for the team" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "id"] - }, - "ContentVisibility": { - "type": "string", - "description": "* `public`: Anyone can access the content, and the content is indexed by search engines.\n* `unlisted`: Anyone can access the content, and the content is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the content.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the content.\n* `in-collection`: Anyone who can access the parent collection can access the content.\n Only available for spaces in a collection.\n* `private`: Authorized members can access the content.\n", - "enum": [ - "public", - "unlisted", - "share-link", - "visitor-auth", - "in-collection", - "private" - ] - }, - "UserContributor": { - "type": "object", - "description": "Contributor towards content.", - "properties": { - "updatedAt": { - "$ref": "#/components/schemas/Timestamp" + } + } + }, + "/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" }, - "count": { - "type": "integer" + { + "$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"] + } + } + } }, - "user": { - "$ref": "#/components/schemas/User" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["updatedAt", "count", "user"] - }, - "ContentPublishingAuth": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"publishing-auth\"", - "enum": ["publishing-auth"] + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": { + "get": { + "operationId": "getReviewsByChangeRequestId", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "id": { - "type": "string", - "description": "Unique identifier for the content." + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/documentFormat" }, - "privateKey": { - "type": "string", - "description": "Private key used to sign JWT tokens." + { + "$ref": "#/components/parameters/listPage" }, - "fallbackURL": { - "type": "string", - "format": "uri", - "description": "URL to redirect to when the visitor auth secret is invalid." + { + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["object", "id", "privateKey"] - }, - "ImportContentResult": { - "type": "object", - "required": ["revision", "importedResources", "totalResources"], - "properties": { - "revision": { - "type": "string", - "description": "ID of the newly created revision." + ], + "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" + } + } + } + } + ] + } + } + } }, - "importedResources": { - "type": "number", - "description": "How many resources were imported" + "404": { + "description": "The change request or space could not be found.", + "$ref": "#/components/responses/NotFoundError" }, - "totalResources": { - "type": "number", - "description": "How many resources were processed" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "Embed": { - "allOf": [ + "post": { + "operationId": "submitChangeRequestReview", + "tags": ["spaces"], + "security": [ { - "type": "object", - "properties": { - "title": { - "type": "string" - }, - "site": { - "type": "string" - }, - "icon": { - "type": "string" - } - }, - "required": ["title", "site"] + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "oneOf": [ - { - "type": "object", - "title": "Link", - "properties": { - "type": { - "type": "string", - "enum": ["link"] - } - }, - "required": ["type"] - }, - { - "type": "object", - "title": "HTML", - "properties": { - "type": { - "type": "string", - "enum": ["rich"] - }, - "html": { - "type": "string" - } - }, - "required": ["type", "html"] - } - ] + "$ref": "#/components/parameters/changeRequestId" } - ] - }, - "Comment": { - "allOf": [ - { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"comment\"", - "enum": ["comment"] - }, - "id": { - "description": "Unique identifier for the comment.", - "type": "string" - }, - "postedBy": { - "description": "The user who posted the comment.", - "$ref": "#/components/schemas/User" - }, - "postedAt": { - "description": "When the comment was posted.", - "$ref": "#/components/schemas/Timestamp" - }, - "editedAt": { - "description": "Date when the comment was edited, if it has been edited.", - "$ref": "#/components/schemas/Timestamp" - }, - "reactions": { - "description": "Any emoji reactions to the comment.", - "$ref": "#/components/schemas/EmojiReactions" - }, - "replies": { - "description": "The number of replies to this comment.", - "type": "number" - }, - "body": { - "description": "The content of the comment.", - "$ref": "#/components/schemas/Document" - }, - "target": { - "description": "Information about the target of the comment.", - "type": "object", - "properties": { - "node": { - "description": "The node this comment is attached to.", - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "preview": { - "type": "string" - } - }, - "required": ["id"] - }, - "changeRequest": { - "description": "The change request containing this comment, if the comment was made inside a change request.", - "type": "string" - }, - "review": { - "description": "The review containing this comment, if this comment was made as part of a review.", - "type": "string" - }, - "page": { - "description": "Information about the page, if this comment refers to a specific page.", - "allOf": [ - { - "$ref": "#/components/schemas/RevisionPageBase" - }, - { - "type": "object", - "properties": { - "path": { - "description": "The fully qualified path to the page", - "type": "string" - }, - "outdated": { - "description": "True if the target of this comment no longer exists in the primary content", - "type": "boolean" - } - }, - "required": ["path", "outdated"] - } - ] - }, - "space": { - "description": "The space containing this comment.", - "type": "string" - }, - "revision": { - "description": "The revision in which the target can be found in.", - "type": "string" - } - }, - "required": ["space", "revision"] - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the comment in the API", - "format": "uri" - } - }, - "required": ["location"] + ], + "summary": "Submit a review for a change request.", + "responses": { + "201": { + "headers": { + "Location": { + "description": "API URL for the newly created review", + "schema": { + "type": "string" + } } }, - "required": [ - "object", - "id", - "replies", - "body", - "postedBy", - "postedAt", - "reactions", - "target", - "urls" - ] + "description": "A new review has been created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeRequestReview" + } + } + } }, - { - "oneOf": [ - { + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "type": "object", - "title": "Resolved", "properties": { "status": { - "description": "Status of the comment.", - "type": "string", - "enum": ["resolved"] - }, - "resolvedAt": { - "description": "If the comment has been resolved, the date at which it was resolved. If this field is not defined, the comment is not resolved.", - "$ref": "#/components/schemas/Timestamp" + "description": "The status of the submitted review.", + "$ref": "#/components/schemas/ChangeRequestReviewStatus" }, - "resolvedBy": { - "description": "If the comment has been resolved, the user who resolved it. If this field is not defined, the comment is not resolved.", - "$ref": "#/components/schemas/User" - } - }, - "required": ["status", "resolvedAt", "resolvedBy"] - }, - { - "type": "object", - "title": "Open", - "properties": { - "status": { - "description": "Status of the comment.", - "type": "string", - "enum": ["open"] + "comment": { + "description": "Optionally, provide a comment along with the review.", + "$ref": "#/components/schemas/Document" } }, "required": ["status"] } - ] + } } - ] - }, - "CommentReply": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"comment-reply\"", - "enum": ["comment-reply"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the reply." - }, - "postedBy": { - "$ref": "#/components/schemas/User" - }, - "postedAt": { - "$ref": "#/components/schemas/Timestamp" - }, - "editedAt": { - "description": "Date when the reply was edited, if it has been edited.", - "$ref": "#/components/schemas/Timestamp" - }, - "reactions": { - "$ref": "#/components/schemas/EmojiReactions" + } + } + }, + "/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" }, - "body": { - "$ref": "#/components/schemas/Document" + { + "$ref": "#/components/parameters/changeRequestId" }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the comment reply in the API", - "format": "uri" - } - }, - "required": ["location"] - } - }, - "required": ["object", "id", "body", "postedBy", "postedAt", "reactions", "urls"] - }, - "PublishedContentLookup": { - "oneOf": [ { - "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"] + "$ref": "#/components/parameters/listPage" }, { - "type": "object", - "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"] + "$ref": "#/components/parameters/listLimit" } - ] - }, - "SpacePointer": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["space"] + ], + "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" + } + } + } + } + ] + } + } + } }, - "space": { - "type": "string", - "description": "Unique identifier for the space" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "space"] + } }, - "CollectionPointer": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["collection"] + "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" }, - "collection": { - "type": "string", - "description": "Unique identifier for the collection" + { + "$ref": "#/components/parameters/changeRequestId" } - }, - "required": ["type", "collection"] - }, - "ContentPosition": { - "type": "object", - "description": "Position at which to insert an item", - "properties": { - "before": { - "oneOf": [ - { - "$ref": "#/components/schemas/SpacePointer" - }, - { - "$ref": "#/components/schemas/CollectionPointer" + ], + "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" + } + } + } + } } - ] + } }, - "after": { - "oneOf": [ - { - "$ref": "#/components/schemas/SpacePointer" - }, - { - "$ref": "#/components/schemas/CollectionPointer" + "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"] } - ] + } } } - }, - "DefaultLevel": { - "description": "Default level for a piece of content", - "oneOf": [ + } + }, + "/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": [ { - "$ref": "#/components/schemas/MemberRoleOrGuest" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "type": "string", - "enum": ["inherit"] - } - ] - }, - "Document": { - "oneOf": [ + "$ref": "#/components/parameters/changeRequestId" + }, { - "$ref": "#/components/schemas/MarkdownDocument", - "title": "Markdown" + "$ref": "#/components/parameters/listPage" }, { - "type": "object", - "title": "JSON Document", - "properties": { - "document": { - "$ref": "#/components/schemas/JSONDocument" - } - }, - "required": ["document"] + "$ref": "#/components/parameters/listLimit" }, { - "type": "object", - "title": "Empty", - "properties": {}, - "additionalProperties": false - } - ] - }, - "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"] + "name": "status", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ContentReferenceStatus" + } }, - "data": { - "type": "object", - "properties": { - "schemaVersion": { - "description": "The schema version of the document. If undefined, the document is considered to be of the latest schema version.", - "type": "integer" + { + "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"] + } + ] + } } - }, - "additionalProperties": true - }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlocksTopLevels" } + }, + "404": { + "description": "The change request could not be found.", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "data", "nodes"] - }, - "DocumentBlock": { - "oneOf": [ + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments": { + "get": { + "operationId": "listCommentsInChangeRequest", + "summary": "List all the comments in a change request.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentBlockParagraph" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockHeading" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockListOrdered" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockListUnordered" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/DocumentBlockListTasks" + "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/schemas/DocumentBlockListItem" + "$ref": "#/components/parameters/listOrder" }, { - "$ref": "#/components/schemas/DocumentBlockDivider" + "$ref": "#/components/parameters/documentFormat" }, { - "$ref": "#/components/schemas/DocumentBlockQuote" + "$ref": "#/components/parameters/status" }, { - "$ref": "#/components/schemas/DocumentBlockHint" + "$ref": "#/components/parameters/targetPage" + } + ], + "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": [ { - "$ref": "#/components/schemas/DocumentBlockImages" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockImage" + "$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": [ { - "$ref": "#/components/schemas/DocumentBlockFile" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockDrawing" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockEmbed" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockCode" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentBlockCodeLine" + "$ref": "#/components/parameters/documentFormat" + } + ], + "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": [ { - "$ref": "#/components/schemas/DocumentBlockMath" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockExpandable" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockTabs" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockTabsItem" + "$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": [ { - "$ref": "#/components/schemas/DocumentBlockTable" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockSwagger" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockContentRef" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockIntegration" + "$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": [ { - "$ref": "#/components/schemas/DocumentBlockSyncedBlock" + "user": [] } - ] - }, - "DocumentInline": { - "oneOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentInlineLink" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentInlineEmoji" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentInlineMath" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentInlineImage" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/DocumentInlineAnnotation" + "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/schemas/DocumentInlineMention" + "$ref": "#/components/parameters/documentFormat" } - ] - }, - "DocumentText": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["text"] - }, - "key": { - "type": "string" - }, - "leaves": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentTextLeaf" + ], + "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" + } + } + } + } + ] + } + } } - } - }, - "required": ["object", "leaves"] - }, - "DocumentFragment": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["fragment"] - }, - "key": { - "type": "string" - }, - "fragment": { - "type": "string" }, - "type": { - "type": "string" - }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlocksEssentials" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "nodes"] + } }, - "DocumentBlocksEssentials": { - "oneOf": [ + "post": { + "operationId": "postCommentReplyInChangeRequest", + "summary": "Post a new reply to a comment in a change request.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentBlockParagraph" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockHeading" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockListOrdered" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockListUnordered" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentBlockListTasks" + "$ref": "#/components/parameters/documentFormat" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostCommentReplySchema" + } + } + } + }, + "responses": { + "200": { + "description": "The reply was posted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentReply" + } + } + } }, - { - "$ref": "#/components/schemas/DocumentBlockDivider" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "DocumentBlocksTopLevels": { - "oneOf": [ + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/comments/{commentId}/replies/{commentReplyId}": { + "get": { + "operationId": "getCommentReplyInChangeRequest", + "summary": "Get a comment reply in a change request.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentBlocksEssentials" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockQuote" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockHint" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockImages" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentBlockFile" + "$ref": "#/components/parameters/commentReplyId" }, { - "$ref": "#/components/schemas/DocumentBlockDrawing" + "$ref": "#/components/parameters/documentFormat" + } + ], + "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": [ { - "$ref": "#/components/schemas/DocumentBlockEmbed" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockCode" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockMath" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockExpandable" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentBlockTabs" + "$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": [ { - "$ref": "#/components/schemas/DocumentBlockTable" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentBlockSwagger" + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentBlockContentRef" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentBlockIntegration" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentBlockSyncedBlock" - } - ] - }, - "DocumentTextLeaf": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["leaf"] - }, - "text": { - "type": "string" - }, - "marks": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentTextMark" - } - } - }, - "required": ["object", "text", "marks"] - }, - "DocumentMarkBold": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["mark"] - }, - "type": { - "type": "string", - "enum": ["bold"] + "$ref": "#/components/parameters/commentReplyId" } - }, - "required": ["object", "type"] - }, - "DocumentMarkItalic": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["mark"] + ], + "responses": { + "205": { + "description": "The comment has been deleted." }, - "type": { - "type": "string", - "enum": ["italic"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type"] - }, - "DocumentMarkCode": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["mark"] - }, - "type": { - "type": "string", - "enum": ["code"] + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": { + "get": { + "operationId": "getContributorsByChangeRequestId", + "tags": ["spaces"], + "security": [ + { + "user": [] } - }, - "required": ["object", "type"] - }, - "DocumentMarkStrikethrough": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["mark"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["strikethrough"] + { + "$ref": "#/components/parameters/changeRequestId" } - }, - "required": ["object", "type"] - }, - "DocumentMarkColor": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["mark"] - }, - "type": { - "type": "string", - "enum": ["color"] - }, - "data": { - "type": "object", - "properties": { - "text": { - "type": "string", - "enum": [ - "default", - "green", - "blue", - "red", - "orange", - "yellow", - "purple" - ] - }, - "background": { - "type": "string", - "enum": [ - "default", - "green", - "blue", - "red", - "orange", - "yellow", - "purple" - ] + ], + "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" + } + } + } + } + ] + } } - }, - "required": ["text", "background"] - } - }, - "required": ["object", "type", "data"] - }, - "DocumentTextMark": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentMarkBold" + } }, - { - "$ref": "#/components/schemas/DocumentMarkItalic" + "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": [ { - "$ref": "#/components/schemas/DocumentMarkCode" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentMarkStrikethrough" + "$ref": "#/components/parameters/changeRequestId" }, { - "$ref": "#/components/schemas/DocumentMarkColor" + "$ref": "#/components/parameters/revisionMetadata" } - ] - }, - "DocumentInlineLink": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] - }, - "type": { - "type": "string", - "enum": ["link"] - }, - "key": { - "type": "string" - }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentText" - }, - { - "$ref": "#/components/schemas/DocumentInlineImage" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Revision" } - ] - } - }, - "data": { - "type": "object", - "properties": { - "ref": { - "$ref": "#/components/schemas/ContentRef" } - }, - "required": ["ref"] + } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "nodes", "data"] - }, - "DocumentInlineMath": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] - }, - "type": { - "type": "string", - "enum": ["inline-math"] - }, - "key": { - "type": "string" - }, - "data": { - "type": "object", - "properties": { - "formula": { - "type": "string" - } - }, - "required": ["formula"] - }, - "isVoid": { - "type": "boolean", - "enum": [true] + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/import": { + "post": { + "summary": "Import content in a change request.", + "operationId": "importContentInChangeRequest", + "security": [ + { + "user": [] } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentInlineEmoji": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] - }, - "type": { - "type": "string", - "enum": ["emoji"] - }, - "key": { - "type": "string" + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "data": { - "type": "object", - "properties": { - "code": { - "type": "string" + { + "$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" + } } }, - "required": ["code"] + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContentResult" + } + } + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentInlineImage": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] - }, - "type": { - "type": "string", - "enum": ["inline-image"] - }, - "key": { - "type": "string" - }, - "data": { - "type": "object", - "properties": { - "ref": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentRefURL" - }, - { - "$ref": "#/components/schemas/ContentRefFile" - } - ] - }, - "refDark": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentRefURL" - }, - { - "$ref": "#/components/schemas/ContentRefFile" - } - ] - }, - "caption": { - "type": "string" - }, - "size": { - "type": "string", - "enum": ["original", "line"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContent" } - }, - "required": ["ref"] - }, - "isVoid": { - "type": "boolean", - "enum": [true] + } } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentInlineMention": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] - }, - "type": { - "type": "string", - "enum": ["mention"] + } + } + }, + "/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" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/changeRequestId" }, - "data": { - "type": "object", - "properties": { - "ref": { - "$ref": "#/components/schemas/ContentRef" + { + "$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"] + } } - }, - "required": ["ref"] + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentInlineAnnotation": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["inline"] + } + } + }, + "/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" }, - "type": { - "type": "string", - "enum": ["annotation"] + { + "$ref": "#/components/parameters/changeRequestId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "fragments": { - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/DocumentFragment" - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["annotation-body"] + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlocksEssentials" - }, - { - "$ref": "#/components/schemas/DocumentBlockCode" + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionFile" } - ] - }, - "minItems": 1 + } + } } - }, - "required": ["nodes", "type"] + ] } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "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" }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentText" + { + "$ref": "#/components/parameters/changeRequestId" + }, + { + "$ref": "#/components/parameters/fileId" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionFile" + } + } } }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "fragments", "isVoid", "nodes"] - }, - "DocumentBlockParagraph": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/files/{fileId}/backlinks": { + "get": { + "operationId": "listChangeRequestFileBacklinks", + "summary": "Get backlink locations for a file existing in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["paragraph"] + { + "$ref": "#/components/parameters/changeRequestId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/fileId" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentInline" - }, - { - "$ref": "#/components/schemas/DocumentText" + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocation" + } + } + } + } + ] } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [false] - }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockHeading": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/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" }, - "type": { - "type": "string", - "enum": ["heading-1", "heading-2", "heading-3"] + { + "$ref": "#/components/parameters/changeRequestId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/pageId" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentInline" - }, - { - "$ref": "#/components/schemas/DocumentText" - } - ] - } + { + "$ref": "#/components/parameters/documentFormat" }, - "data": { - "type": "object", - "properties": { - "id": { - "type": "string", - "pattern": "^[-a-z0-9.+_]+$" + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } } } }, - "meta": { - "type": "object", - "properties": { - "id": { - "description": "Unique ID to be used in an URL for the block.", - "type": "string" - } - }, - "required": ["id"] - }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "nodes", "data"] - }, - "DocumentBlockQuote": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["blockquote"] + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/content/page/{pageId}/backlinks": { + "get": { + "operationId": "listChangeRequestPageBacklinks", + "summary": "Get backlink locations for a page existing in a change request.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/changeRequestId" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlocksEssentials" - }, - { - "$ref": "#/components/schemas/DocumentBlockQuote" - } - ] - } + { + "$ref": "#/components/parameters/pageId" }, - "isVoid": { - "type": "boolean", - "enum": [false] + { + "$ref": "#/components/parameters/listPage" }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + { + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockHint": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["hint"] - }, - "key": { - "type": "string" - }, - "data": { - "type": "object", - "properties": { - "style": { - "type": "string", - "enum": ["info", "warning", "danger", "success"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocation" + } + } + } + } + ] + } } - }, - "required": ["style"] - }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlocksEssentials" } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "nodes"] - }, - "DocumentBlockListUnordered": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["list-unordered"] + } + } + }, + "/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" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/changeRequestId" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlockListItem" + { + "$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" } - ] + } } }, - "data": { - "type": "object", - "additionalProperties": false - }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockListOrdered": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ImportContent" + } + } + } + } + } + }, + "/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": { - "type": "string", - "enum": ["list-ordered"] + { + "$ref": "#/components/parameters/changeRequestId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/pagePath" }, - "data": { - "type": "object", - "properties": { - "start": { - "type": "number", - "description": "An integer to start counting from for the list items." - } - } + { + "$ref": "#/components/parameters/documentFormat" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlockListItem" + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "nodes"] - }, - "DocumentBlockListTasks": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["list-tasks"] - }, - "key": { - "type": "string" + } + } + }, + "/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" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlockListItem" + { + "$ref": "#/components/parameters/changeRequestId" + } + ], + "responses": { + "200": { + "description": "Content marked as touched.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChangeRequest" } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [false] - }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockListItem": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "contentId": { + "type": "string", + "description": "The content id of the touched content." + }, + "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"] + } + } + } + } + } + }, + "/spaces/{spaceId}/change-requests/{changeRequestId}/pdf": { + "get": { + "operationId": "getChangeRequestPDF", + "summary": "Generate a URL to export the content of a change request as a PDF.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["list-item"] + { + "$ref": "#/components/parameters/changeRequestId" }, - "key": { - "type": "string" + { + "in": "query", + "name": "only", + "description": "Generate a PDF only for the provided page.", + "schema": { + "type": "boolean" + } }, - "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" + { + "in": "query", + "name": "page", + "description": "ID of a specific page to generate a PDF for.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "URL of the PDF", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "description": "Temporary URL to print the content. The URL will work for 1h.", + "$ref": "#/components/schemas/URL" + } + }, + "required": ["url"] } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}": { + "get": { + "operationId": "getRevisionById", + "summary": "Get a specific revision in a space", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "data": { - "type": "object", - "properties": { - "checked": { - "type": "boolean" + { + "$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" } - }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockImages": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/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" }, - "type": { - "type": "string", - "enum": ["images"] + { + "$ref": "#/components/parameters/revisionId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/revisionMetadata" }, - "data": { - "type": "object", - "properties": { - "align": { - "type": "string", - "enum": ["center", "left", "right"] - }, - "fullWidth": { - "type": "boolean" + { + "name": "limit", + "in": "query", + "description": "Limit the number of changes returned", + "schema": { + "type": "number", + "default": 10 + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionSemanticChanges" + } } } }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlockImage" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/pages": { + "get": { + "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": { + "type": "object", + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + } + }, + "required": ["pages"] + } + } } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "nodes", "isVoid"] - }, - "DocumentBlockImage": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/files": { + "get": { + "summary": "List all files in a revision", + "operationId": "listFilesInRevisionById", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["image"] + { + "$ref": "#/components/parameters/revisionId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "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"] + { + "$ref": "#/components/parameters/listLimit" }, - "fragments": { - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/DocumentFragment" - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["caption"] + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlockParagraph" + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionFile" + } + } } } - }, - "required": ["nodes", "type"] + ] } - ] + } } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "fragments", "isVoid"] - }, - "DocumentBlockImageDimension": { - "oneOf": [ - { - "type": "number" - }, + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}": { + "get": { + "summary": "Get a file in a revision by its ID", + "operationId": "getFileInRevisionById", + "security": [ { - "type": "object", - "properties": { - "unit": { - "type": "string" - }, - "value": { - "type": "number" - } - }, - "required": ["unit", "value"] + "user": [] } - ] - }, - "DocumentBlockFile": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["file"] + { + "$ref": "#/components/parameters/revisionId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/fileId" }, - "data": { - "type": "object", - "properties": { - "ref": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentRefFile" - } - ] + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionFile" + } } - }, - "required": ["ref"] + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockDrawing": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": { + "get": { + "operationId": "getPageInRevisionById", + "summary": "Get a page by its ID in a revision.", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["drawing"] + { + "$ref": "#/components/parameters/revisionId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/pageId" }, - "data": { - "type": "object", - "properties": { - "ref": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentRefFile" - } - ] + { + "$ref": "#/components/parameters/documentFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevisionPage" + } } } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockEmbed": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/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" }, - "type": { - "type": "string", - "enum": ["embed"] + { + "$ref": "#/components/parameters/revisionId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/pagePath" }, - "data": { - "type": "object", - "properties": { - "url": { - "type": "string" - }, - "fullWidth": { - "type": "boolean" + { + "$ref": "#/components/parameters/documentFormat" + }, + { + "$ref": "#/components/parameters/revisionMetadata" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] + } } - }, - "required": ["url"] + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockCode": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/spaces/{spaceId}/comments": { + "get": { + "operationId": "listCommentsInSpace", + "summary": "List all the comments in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["code"] + { + "$ref": "#/components/parameters/listPage" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" }, - "data": { - "type": "object", - "properties": { - "syntax": { - "type": "string" - }, - "title": { - "type": "string" - }, - "overflow": { - "type": "string", - "default": "scroll", - "enum": ["scroll", "wrap"] - }, - "lineNumbers": { - "type": "boolean" - }, - "fullWidth": { - "type": "boolean" + { + "$ref": "#/components/parameters/listOrder" + }, + { + "$ref": "#/components/parameters/status" + }, + { + "$ref": "#/components/parameters/documentFormat" + }, + { + "$ref": "#/components/parameters/targetPage" + } + ], + "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" + } + } + } + } + ] + } } } }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlockCodeLine" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "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": { + "$ref": "#/components/schemas/PostCommentSchema" + } } - }, - "isVoid": { - "type": "boolean", - "enum": [false] } }, - "required": ["object", "type", "data", "nodes"] - }, - "DocumentBlockCodeLine": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + "responses": { + "200": { + "description": "The comment was posted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment" + } + } + } }, - "type": { - "type": "string", - "enum": ["code-line"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/comments/{commentId}": { + "get": { + "operationId": "getCommentInSpace", + "summary": "Get a comment in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/commentId" }, - "nodes": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentText" - }, - { - "$ref": "#/components/schemas/DocumentInlineAnnotation" + { + "$ref": "#/components/parameters/documentFormat" + } + ], + "responses": { + "200": { + "description": "The returned comment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment" } - ] - } - }, - "data": { - "type": "object", - "properties": { - "highlighted": { - "type": "boolean" } } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "nodes", "data"] + } }, - "DocumentBlockMath": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + "delete": { + "operationId": "deleteCommentInSpace", + "summary": "Delete a comment in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["math"] + { + "$ref": "#/components/parameters/commentId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." }, - "key": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateCommentInSpace", + "summary": "Update a comment in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "data": { - "type": "object", - "properties": { - "formula": { - "type": "string" + { + "$ref": "#/components/parameters/commentId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateCommentSchema" } - }, - "required": ["formula"] - }, - "isVoid": { - "type": "boolean", - "enum": [true] + } } }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockExpandable": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + "responses": { + "200": { + "description": "The comment was updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment" + } + } + } }, - "type": { - "type": "string", - "enum": ["expandable"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/comments/{commentId}/replies": { + "get": { + "operationId": "listCommentRepliesInSpace", + "summary": "List all the replies to a comment in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/commentId" }, - "isVoid": { - "type": "boolean", - "enum": [true] + { + "$ref": "#/components/parameters/listPage" }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + { + "$ref": "#/components/parameters/listLimit" }, - "fragments": { - "type": "array", - "items": { - "oneOf": [ - { - "allOf": [ - { - "$ref": "#/components/schemas/DocumentFragment" - }, - { - "type": "object", - "properties": { - "fragment": { - "type": "string", - "enum": ["expandable-title"] - }, - "type": { - "type": "string", - "enum": ["expandable-title"] - }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlockParagraph" - }, - "minItems": 1, - "maxItems": 1 - } - }, - "required": ["nodes", "fragment", "type"] - } - ] - }, - { + { + "$ref": "#/components/parameters/documentFormat" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { "allOf": [ { - "$ref": "#/components/schemas/DocumentFragment" + "$ref": "#/components/schemas/List" }, { "type": "object", + "required": ["items"], "properties": { - "fragment": { - "type": "string", - "enum": ["expandable-body"] - }, - "type": { - "type": "string", - "enum": ["expandable-body"] - }, - "nodes": { + "items": { "type": "array", "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/DocumentBlocksEssentials" - }, - { - "$ref": "#/components/schemas/DocumentBlockCode" - } - ] - }, - "minItems": 1 + "$ref": "#/components/schemas/CommentReply" + } } - }, - "required": ["nodes", "fragment", "type"] + } } ] } - ] + } } }, - "meta": { - "type": "object", - "properties": { - "id": { - "description": "Unique ID to be used in an URL for the block.", - "type": "string" - } - }, - "required": ["id"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "isVoid", "fragments", "data"] + } }, - "DocumentBlockTabs": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["tabs"] - }, - "key": { - "type": "string" + "post": { + "operationId": "postCommentReplyInSpace", + "summary": "Post a new reply to a comment in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "nodes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentBlockTabsItem" + { + "$ref": "#/components/parameters/commentId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostCommentReplySchema" + } } - }, - "isVoid": { - "type": "boolean", - "enum": [false] - }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false } }, - "required": ["object", "type", "nodes"] - }, - "DocumentBlockSwagger": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["swagger"] - }, - "key": { - "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" + "responses": { + "200": { + "description": "The reply was posted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentReply" + } } - }, - "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"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": { + "get": { + "operationId": "getCommentReplyInSpace", + "summary": "Get a comment reply in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockTable": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["table"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/commentId" }, - "isVoid": { - "type": "boolean", - "enum": [true] + { + "$ref": "#/components/parameters/commentReplyId" }, - "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" + { + "$ref": "#/components/parameters/documentFormat" + } + ], + "responses": { + "200": { + "description": "The returned comment reply.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentReply" } - }, - "fullWidth": { - "type": "boolean", - "description": "Whether to render the block as a full width one" } - }, - "required": ["view", "records", "definition"] - }, - "fragments": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentFragment" } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid", "fragments"] + } }, - "DocumentTableRecord": { - "type": "object", - "properties": { - "orderIndex": { - "type": "string" + "put": { + "operationId": "updateCommentReplyInSpace", + "summary": "Update a comment reply in a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "values": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "type": "number" - }, - { - "type": "string" - }, - { - "type": "boolean" - }, - { - "type": "array", - "items": { - "type": "string" - } - }, - { - "$ref": "#/components/schemas/ContentRef" - } - ] + { + "$ref": "#/components/parameters/commentId" + }, + { + "$ref": "#/components/parameters/commentReplyId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateCommentReplySchema" + } } } }, - "required": ["orderIndex", "values"] - }, - "DocumentTableDefinitionBase": { - "type": "object", - "properties": { - "id": { - "type": "string" + "responses": { + "200": { + "description": "The reply was updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentReply" + } + } + } }, - "title": { - "type": "string", - "description": "Title for the column" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["id", "title"] + } }, - "DocumentTableDefinition": { - "oneOf": [ + "delete": { + "operationId": "deleteCommentReplyInSpace", + "summary": "Delete a comment reply in a space.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionText" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentTableDefinitionNumber" + "$ref": "#/components/parameters/commentId" }, { - "$ref": "#/components/schemas/DocumentTableDefinitionCheckbox" + "$ref": "#/components/parameters/commentReplyId" + } + ], + "responses": { + "205": { + "description": "The comment has been deleted." + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/permissions/aggregate": { + "get": { + "operationId": "listPermissionsAggregateInSpace", + "summary": "List permissions for all users in a space.", + "tags": ["permissions", "spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, { - "$ref": "#/components/schemas/DocumentTableDefinitionFiles" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/DocumentTableDefinitionUsers" + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "role", + "in": "query", + "description": "If defined, only members with this role will be returned.", + "schema": { + "$ref": "#/components/schemas/MemberRole" + } + } + ], + "responses": { + "200": { + "description": "Listing of users who can access the space.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserContentPermission" + } + } + } + } + ] + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/publishing/customization": { + "get": { + "operationId": "getSpacePublishingCustomizationById", + "summary": "Get the publishing customization configuration for a space.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionRating" + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationSettings" + } + } + } }, - { - "$ref": "#/components/schemas/DocumentTableDefinitionSelect" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - { - "$ref": "#/components/schemas/DocumentTableDefinitionContentRef" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "DocumentTableDefinitionText": { - "allOf": [ + "put": { + "operationId": "updateSpacePublishingCustomizationById", + "summary": "Update the publishing customization configuration for a space.", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" - }, + "user": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["text"] - }, - "textAlignment": { - "type": "string", - "enum": ["center", "right", "left"] + "$ref": "#/components/parameters/spaceId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationSettings" } - }, - "required": ["type", "textAlignment"] + } } - ] - }, - "DocumentTableDefinitionNumber": { - "allOf": [ - { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationSettings" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/integrations": { + "get": { + "operationId": "listSpaceIntegrations", + "summary": "List integrations enabled in a space.", + "tags": ["integrations", "spaces"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["number"] - } - }, - "required": ["type"] + "user": [] } - ] - }, - "DocumentTableDefinitionCheckbox": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + "$ref": "#/components/parameters/spaceId" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["checkbox"] + "$ref": "#/components/parameters/integrationSearchQuery" + } + ], + "responses": { + "200": { + "description": "Listing of integrations enabled in the space.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + ] + } } - }, - "required": ["type"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "DocumentTableDefinitionFiles": { - "allOf": [ + } + } + }, + "/spaces/{spaceId}/integration-blocks": { + "get": { + "operationId": "listSpaceIntegrationsBlocks", + "summary": "List integrations blocks for a space", + "tags": ["integrations"], + "parameters": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "list of installed integration blocks", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SpaceIntegrationBlocks" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFoundError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/integration-scripts": { + "get": { + "operationId": "listSpaceIntegrationScripts", + "summary": "List the scripts to embed in published content for a space.", + "tags": ["spaces"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["files"] - } - }, - "required": ["type"] + "user": [] } - ] - }, - "DocumentTableDefinitionUsers": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SpaceIntegrationScript" + } + } + } + } }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/custom-fields": { + "get": { + "operationId": "getSpaceCustomFields", + "summary": "Get the values of the custom fields set on a space", + "tags": ["spaces"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["users"] - }, - "multiple": { - "type": "boolean" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomFieldValues" + } } - }, - "required": ["type", "multiple"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "DocumentTableDefinitionRating": { - "allOf": [ + "patch": { + "operationId": "updateSpaceCustomFields", + "summary": "Update the custom fields in a space", + "tags": ["spaces"], + "security": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" - }, + "user": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["rating"] - }, - "max": { - "type": "number" + "$ref": "#/components/parameters/spaceId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateCustomFieldValues" } - }, - "required": ["type", "max"] + } } - ] - }, - "DocumentTableDefinitionSelect": { - "allOf": [ - { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, + "responses": { + "204": { + "description": "Custom fields updated" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/pages/{pageId}/feedbacks/{visitorId}": { + "get": { + "operationId": "getPageFeedback", + "summary": "Get a page feedback by a visitor.", + "tags": ["spaces"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["select"] - }, - "multiple": { - "type": "boolean" - }, - "options": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocumentTableSelectOption" - } - } - }, - "required": ["type", "multiple", "options"] + "user": [] } - ] - }, - "DocumentTableDefinitionContentRef": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/DocumentTableDefinitionBase" + "$ref": "#/components/parameters/spaceId" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["content-ref"] - } - }, - "required": ["type"] - } - ] - }, - "DocumentTableSelectOption": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "label": { - "type": "string" + "$ref": "#/components/parameters/pageId" }, - "color": { - "type": "string" + { + "$ref": "#/components/parameters/visitorId" } - }, - "required": ["value", "label", "color"] - }, - "DocumentTableViewCards": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["cards"] - }, - "cardSize": { - "type": "string", - "description": "Size of the cards. It indicates how many columns will be used", - "enum": ["medium", "large"] - }, - "columns": { - "type": "array", - "description": "Ordered list of the definition IDs to display", - "items": { - "type": "string" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } + } } }, - "targetDefinition": { - "type": "string", - "description": "Definition ID to use as a target link for the card" - }, - "coverDefinition": { - "type": "string", - "description": "Definition ID to use as a cover image" - }, - "hideColumnTitle": { - "type": "boolean", - "description": "Should we display the column title or not" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "columns", "cardSize"] + } }, - "DocumentTableViewGrid": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["grid"] - }, - "columns": { - "type": "array", - "description": "Ordered list of the definition IDs to display", - "items": { - "type": "string" - } - }, - "columnWidths": { - "type": "object", - "description": "Percent width of each column", - "additionalProperties": { - "type": "number" - } - }, - "hideHeader": { - "type": "boolean", - "description": "Should we display the header with column titles" - }, - "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" + "put": { + "operationId": "createPageFeedback", + "summary": "Create a page feedback by a visitor.", + "tags": ["spaces"], + "security": [ + { + "user": [] } - }, - "required": ["type", "columns", "hideHeader"] - }, - "DocumentBlockTabsItem": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["tabs-item"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/pageId" }, - "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/parameters/visitorId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "rating": { + "$ref": "#/components/schemas/PageFeedbackRating" + } }, - { - "$ref": "#/components/schemas/DocumentBlockIntegration" - } - ] + "required": ["rating"] + } } - }, - "data": { - "type": "object", - "properties": { - "title": { - "type": "string" + } + }, + "responses": { + "200": { + "description": "Feedback updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } } } }, - "meta": { - "type": "object", - "properties": { - "id": { - "description": "Unique ID to be used in an URL for the block.", - "type": "string" + "201": { + "description": "Feedback created", + "headers": { + "Location": { + "description": "URL for the feedback", + "schema": { + "type": "string" + } } }, - "required": ["id"] + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } + } + } }, - "isVoid": { - "type": "boolean", - "enum": [false] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "nodes", "data"] - }, - "DocumentBlockContentRef": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["content-ref"] + } + } + }, + "/spaces/{spaceId}/pdf": { + "get": { + "operationId": "getSpacePDF", + "summary": "Generate a URL to export the content of the space as a PDF.", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "key": { - "type": "string" + { + "in": "query", + "name": "only", + "description": "Generate a PDF only for the provided page.", + "schema": { + "type": "boolean" + } }, - "data": { - "type": "object", - "properties": { - "ref": { - "$ref": "#/components/schemas/ContentRef" + { + "in": "query", + "name": "page", + "description": "ID of a specific page to generate a PDF for.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "URL of the PDF", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "description": "Temporary URL to print the content. The URL will work for 1h.", + "$ref": "#/components/schemas/URL" + } + }, + "required": ["url"] + } } - }, - "required": ["ref"] + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/share-links": { + "post": { + "operationId": "createSpaceShareLink", + "summary": "Creates a new space share link", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + }, + "required": ["name"] + } + } } }, - "required": ["object", "type", "data", "isVoid"] - }, - "DocumentBlockIntegration": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["integration"] + "responses": { + "201": { + "description": "The space share link has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" + } + } + } }, - "key": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/spaces/{spaceId}/share-links/{shareLinkId}": { + "patch": { + "operationId": "updateSpaceShareLinkById", + "summary": "Update the details of a space share link", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "data": { - "type": "object", - "properties": { - "integration": { - "type": "string", - "description": "Name of the integration" - }, - "block": { - "type": "string", - "description": "ID of the block in the integration" - }, - "props": { + { + "$ref": "#/components/parameters/shareLinkId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "type": "object", - "description": "Properties passed to the block during rendering", - "additionalProperties": { - "description": "Any value" + "minProperties": 1, + "properties": { + "active": { + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The space share link has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" } - }, - "action": { - "$ref": "#/components/schemas/ContentKitAction" - }, - "url": { - "type": "string", - "description": "URL associated with the content represented by the block.\nThis property is set when creating a block from a URL (unfurl) to ensure\nwe can convert the block back to an embed.\n" - }, - "fullWidth": { - "type": "boolean" } - }, - "required": ["integration", "block", "props"] + } }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] + } }, - "DocumentBlockDivider": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] - }, - "type": { - "type": "string", - "enum": ["divider"] - }, - "key": { - "type": "string" + "delete": { + "operationId": "deleteSpaceShareLinkById", + "summary": "Deletes a space share link", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "isVoid": { - "type": "boolean", - "enum": [true] + { + "$ref": "#/components/parameters/shareLinkId" + } + ], + "responses": { + "205": { + "description": "Space share link has been deleted" }, - "data": { - "type": "object", - "properties": {}, - "additionalProperties": false + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "isVoid", "data"] - }, - "DocumentBlockSyncedBlock": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["block"] + } + } + }, + "/spaces/{spaceId}/links": { + "get": { + "operationId": "listSpaceLinks", + "summary": "Get all links in the context of a space including their status and location where they appear.", + "tags": ["spaces", "links"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/spaceId" }, - "type": { - "type": "string", - "enum": ["synced-block"] + { + "$ref": "#/components/parameters/listPage" }, - "key": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" }, - "data": { - "type": "object", - "properties": { - "ref": { - "$ref": "#/components/schemas/ContentRefSyncedBlock" + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ContentReferenceStatus" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "properties": { + "stats": { + "$ref": "#/components/schemas/ContentReferencesStats" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentReferenceUsage" + } + } + }, + "required": ["items", "stats"] + } + ] + } } - }, - "required": ["ref"] + } }, - "meta": { - "type": "object", - "properties": { - "apiToken": { - "description": "API Token to use to fetch the synced block from the API.", - "type": "string" - } - }, - "required": ["apiToken"] + "404": { + "description": "The space could not be found.", + "$ref": "#/components/responses/NotFoundError" }, - "isVoid": { - "type": "boolean", - "enum": [true] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["object", "type", "data", "isVoid"] - }, - "ContentRef": { - "oneOf": [ + } + } + }, + "/collections/{collectionId}": { + "get": { + "operationId": "getCollectionById", + "summary": "Get the details about a collection using its ID", + "tags": ["collections"], + "security": [ { - "$ref": "#/components/schemas/ContentRefFile" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentRefURL" + "$ref": "#/components/parameters/collectionId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collection" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateCollectionById", + "summary": "Update the details of a collection", + "tags": ["collections"], + "security": [ { - "$ref": "#/components/schemas/ContentRefPage" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentRefAnchor" + "$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": "The collection has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collection" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "deleteCollectionById", + "summary": "Deletes a collection", + "tags": ["collections"], + "security": [ { - "$ref": "#/components/schemas/ContentRefUser" + "user": [] + } + ], + "parameters": [ + { + "$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/schemas/ContentRefCollection" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentRefSpace" + "$ref": "#/components/parameters/collectionId" }, { - "$ref": "#/components/schemas/ContentRefSnippet" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/ContentRefSyncedBlock" + "$ref": "#/components/parameters/listLimit" } - ] - }, - "ContentRefURL": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["url"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Space" + } + } + } + } + ] + } + } + } }, - "url": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["kind", "url"] - }, - "ContentRefFile": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["file"] - }, - "file": { - "type": "string" + } + } + }, + "/collections/{collectionId}/move": { + "post": { + "operationId": "moveCollection", + "summary": "Move a collection to a new position.", + "tags": ["collections"], + "security": [ + { + "user": [] } - }, - "required": ["kind", "file"] - }, - "ContentRefPage": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["page"] - }, - "page": { - "type": "string" - }, - "space": { - "description": "ID of the space the page is in. The page is considered as in the current space if none is provided.", - "type": "string" + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "minProperties": 1, + "properties": { + "parent": { + "description": "The unique id of the parent collection", + "type": "string", + "nullable": true + }, + "position": { + "description": "Where to move the collection. By default, it will be moved at the end.", + "$ref": "#/components/schemas/ContentPosition" + } + } + } + } } }, - "required": ["kind", "page"] - }, - "ContentRefAnchor": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["anchor"] - }, - "anchor": { - "type": "string" + "responses": { + "200": { + "description": "Collection moved", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collection" + } + } + } }, - "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" + "400": { + "description": "Invalid position space or collection provided", + "$ref": "#/components/responses/BadRequestError" }, - "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"] + "404": { + "description": "No matching Collection found for given ID", + "$ref": "#/components/responses/NotFoundError" }, - "user": { - "type": "string" - } - }, - "required": ["kind", "user"] - }, - "ContentRefCollection": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["collection"] + "409": { + "description": "Operation would not result in any update", + "$ref": "#/components/responses/ConflictError" }, - "collection": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["kind", "collection"] - }, - "ContentRefSpace": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["space"] - }, - "space": { - "type": "string" + } + } + }, + "/collections/{collectionId}/transfer": { + "post": { + "operationId": "transferCollection", + "summary": "Transfer a collection to another organization.", + "tags": ["collections"], + "security": [ + { + "user": [] } - }, - "required": ["kind", "space"] - }, - "ContentRefSnippet": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["snippet"] - }, - "snippet": { - "type": "string" - }, - "organization": { - "type": "string" + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" } - }, - "required": ["kind", "snippet", "organization"] - }, - "ContentRefSyncedBlock": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": ["synced-block"] - }, - "syncedBlock": { - "type": "string" - }, - "organization": { - "type": "string" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "organization": { + "type": "string", + "description": "The unique id of the target organization" + } + }, + "required": ["organization"] + } + } } }, - "required": ["kind", "syncedBlock", "organization"] - }, - "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" + "responses": { + "200": { + "description": "Collection transferred", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collection" + } + } + } }, - "title": { - "$ref": "#/components/schemas/SpaceTitle" + "404": { + "description": "No matching Collection found for given ID", + "$ref": "#/components/responses/NotFoundError" }, - "emoji": { - "description": "An emoji for this space. It'll match the emoji shown in the GitBook app.", - "$ref": "#/components/schemas/Emoji" + "409": { + "description": "Transfer would not result in any update", + "$ref": "#/components/responses/ConflictError" }, - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" + "412": { + "description": "The collection cannot be moved.", + "$ref": "#/components/responses/PreconditionFailedError" }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/collections/{collectionId}/permissions/aggregate": { + "get": { + "operationId": "listPermissionsAggregateInCollection", + "summary": "List permissions for all users in a collection.", + "tags": ["permissions", "spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" }, - "updatedAt": { - "$ref": "#/components/schemas/Timestamp" + { + "$ref": "#/components/parameters/listPage" }, - "deletedAt": { - "$ref": "#/components/schemas/Timestamp" + { + "$ref": "#/components/parameters/listLimit" }, - "editMode": { - "$ref": "#/components/schemas/SpaceEditMode" + { + "name": "role", + "in": "query", + "description": "If defined, only members with this role will be returned.", + "schema": { + "$ref": "#/components/schemas/MemberRole" + } + } + ], + "responses": { + "200": { + "description": "Listing of users who can access the collections.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserContentPermission" + } + } + } + } + ] + } + } + } }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the space in the API", - "format": "uri" - }, - "app": { - "type": "string", - "description": "URL of the space in the application", - "format": "uri" - }, - "published": { - "type": "string", - "description": "URL of the published version of the space. Only defined when visibility is not \"private.\"", - "format": "uri" - }, - "public": { - "type": "string", - "description": "URL of the public version of the space. Only defined when visibility is \"public\".", - "format": "uri" - }, - "icon": { - "description": "URL of the icon of this space, if defined.", - "$ref": "#/components/schemas/URL" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/collections/{collectionId}/publishing/customization": { + "get": { + "operationId": "getCollectionPublishingCustomizationById", + "summary": "Get the publishing customization configuration for a collection.", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationCollectionSettings" + } } - }, - "required": ["app", "location"] + } }, - "organization": { - "type": "string", - "description": "ID of the organization owning this space" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "parent": { - "type": "string", - "description": "ID of the parent collection." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateCollectionPublishingCustomizationById", + "summary": "Update the publishing customization configuration for a collection.", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationCollectionSettings" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomizationCollectionSettings" + } + } + } }, - "gitSync": { - "$ref": "#/components/schemas/GitSyncState" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "visitorAuth": { - "$ref": "#/components/schemas/SpaceVisitorAuth" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/collections/{collectionId}/share-links": { + "post": { + "operationId": "createCollectionShareLink", + "summary": "Creates a new collection share link", + "tags": ["collections"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + }, + "required": ["name"] + } + } + } + }, + "responses": { + "201": { + "description": "The collection share link has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" + } + } + } }, - "revision": { - "type": "string", - "description": "ID of the active revision in the space." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/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/collectionId" }, - "defaultLevel": { - "$ref": "#/components/schemas/DefaultLevel" + { + "$ref": "#/components/parameters/shareLinkId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "minProperties": 1, + "properties": { + "active": { + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + } + } + } } }, - "required": [ - "object", - "id", - "type", - "title", - "emoji", - "organization", - "visibility", - "revision", - "createdAt", - "updatedAt", - "urls", - "defaultLevel" - ] - }, - "SpaceEditMode": { - "type": "string", - "description": "Determines how a Space can be edited.\n* `live`: Users can directly edit the space\n* `locked`: All edits are locked for this space.\n", - "enum": ["live", "locked"] - }, - "SpaceTitle": { - "type": "string", - "description": "Title of the space", - "minLength": 1, - "maxLength": 50 + "responses": { + "200": { + "description": "The collection share link has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } }, - "SpaceVisitorAuth": { - "oneOf": [ + "delete": { + "operationId": "deleteCollectionShareLinkById", + "summary": "Deletes a collection share link", + "tags": ["collections"], + "security": [ { - "type": "object", - "title": "Custom", - "properties": { - "backend": { - "type": "string", - "description": "Custom backend for Visitor Authentication", - "enum": ["custom"] - } - }, - "required": ["backend"] + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/collectionId" }, { - "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"] + "$ref": "#/components/parameters/shareLinkId" } - ] - }, - "RevisionBase": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"revision\"", - "enum": ["revision"] + ], + "responses": { + "205": { + "description": "Collection share link has been deleted" }, - "id": { - "description": "Unique identifier for the revision", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations": { + "get": { + "operationId": "listIntegrations", + "summary": "List all public integrations", + "tags": ["integrations"], + "parameters": [ + { + "$ref": "#/components/parameters/listPage" }, - "parents": { - "description": "IDs of the parent revisions", - "type": "array", - "items": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/integrationSearchQuery" + }, + { + "name": "category", + "in": "query", + "description": "Filter the integrations by category", + "schema": { + "$ref": "#/components/schemas/IntegrationCategory" } }, - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RevisionPage" + { + "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": "Paginated list of integrations", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + ] + } + } } }, - "files": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RevisionFile" + "default": { + "$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"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Integration" + } + } } }, - "createdAt": { - "description": "When the revision was created.", - "$ref": "#/components/schemas/Timestamp" - }, - "git": { - "description": "Metadata about a potential associated git commit.", - "$ref": "#/components/schemas/GitSyncCommit" + "404": { + "description": "Organization could not be found for the given hostname", + "$ref": "#/components/responses/NotFoundError" }, - "urls": { - "type": "object", - "properties": { - "app": { - "type": "string", - "format": "uri", - "description": "URL in the application for the revision" - }, - "published": { - "type": "string", - "description": "URL of the published version of the revision. Only defined when the space visibility is not \"private.\"", - "format": "uri" - }, - "public": { - "type": "string", - "description": "URL of the public version of the revision. Only defined when the space visibility is \"public\".", - "format": "uri" - } - }, - "required": ["app"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["object", "id", "parents", "pages", "files", "urls", "createdAt"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublishIntegration" + } + } + } + } }, - "RevisionTypeMerge": { - "allOf": [ + "delete": { + "operationId": "unpublishIntegration", + "summary": "Unpublish an integration", + "tags": ["integrations"], + "security": [ { - "$ref": "#/components/schemas/RevisionBase" + "user": [] + } + ], + "parameters": [ + { + "$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": [ { - "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"] + "integration": [] } - ] - }, - "RevisionTypeRollback": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/RevisionBase" + "$ref": "#/components/parameters/integrationName" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Revision created as a rollback of a previous revision.", - "enum": ["rollback"] + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "externalId", + "in": "query", + "description": "External Id to filter by", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationInstallation" + } + } + } + } + ] + } } - }, - "required": ["type"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "RevisionTypeUpdate": { - "allOf": [ + "post": { + "operationId": "installIntegration", + "summary": "Install integration on a target organization", + "tags": ["integrations"], + "security": [ { - "$ref": "#/components/schemas/RevisionBase" - }, + "user": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Revision created when updating a change request with changes from primary.", - "enum": ["update"] + "$ref": "#/components/parameters/integrationName" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationTarget" + } + } + } + }, + "responses": { + "201": { + "headers": { + "Location": { + "description": "URL for the installed integration", + "schema": { + "type": "string" + } } }, - "required": ["type"] + "description": "Integration installed successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationInstallation" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "RevisionTypeEdits": { - "allOf": [ + } + } + }, + "/integrations/{integrationName}/events": { + "get": { + "operationId": "listIntegrationEvents", + "summary": "List all integration events", + "tags": ["integrations"], + "parameters": [ { - "$ref": "#/components/schemas/RevisionBase" + "$ref": "#/components/parameters/integrationName" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "Revision created by editing the content.", - "enum": ["edits"] + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "Paginated list of integration events", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationEvent" + } + } + } + } + ] + } } - }, - "required": ["type"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "Revision": { - "oneOf": [ + } + } + }, + "/integrations/{integrationName}/events/{eventId}": { + "get": { + "operationId": "getIntegrationEvent", + "summary": "Get a specific integration event by its id", + "tags": ["integrations"], + "parameters": [ { - "$ref": "#/components/schemas/RevisionTypeEdits" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/schemas/RevisionTypeMerge" + "$ref": "#/components/parameters/integrationEventId" + } + ], + "responses": { + "200": { + "description": "Integration event", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["event"], + "properties": { + "event": { + "$ref": "#/components/schemas/IntegrationEvent" + }, + "trace": { + "$ref": "#/components/schemas/IntegrationEventTrace" + } + } + } + } + } }, - { - "$ref": "#/components/schemas/RevisionTypeRollback" + "404": { + "$ref": "#/components/responses/NotFoundError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations/{integrationName}/spaces": { + "get": { + "operationId": "listIntegrationSpaceInstallations", + "summary": "Fetch a list of space installations of an integration", + "tags": ["integrations"], + "security": [ { - "$ref": "#/components/schemas/RevisionTypeUpdate" + "integration": [] } ], - "discriminator": { - "propertyName": "type" - } - }, - "RevisionPage": { - "oneOf": [ + "parameters": [ { - "$ref": "#/components/schemas/RevisionPageDocument" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/schemas/RevisionPageGroup" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/RevisionPageLink" + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "externalId", + "in": "query", + "description": "External Id to filter by", + "schema": { + "type": "string" + } } ], - "discriminator": { - "propertyName": "type" - } - }, - "RevisionPageBase": { - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for the page in the revision", - "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" + "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" + } + } + } + } + ] + } + } + } }, - "updatedAt": { - "description": "When the page was last edited. Only present if page has been edited at least once.", - "$ref": "#/components/schemas/Timestamp" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["id", "title"] - }, - "RevisionPageDocument": { - "allOf": [ + } + } + }, + "/integrations/{integrationName}/spaces/{spaceId}/dev": { + "put": { + "operationId": "updateIntegrationDevSpace", + "summary": "Update the development space for an integration", + "tags": ["integrations"], + "security": [ { - "$ref": "#/components/schemas/RevisionPageBase" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/Document" + "$ref": "#/components/parameters/integrationName" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "deprecated": true, - "enum": ["sheet"] - }, - "type": { - "type": "string", - "enum": ["document"] - }, - "urls": { - "required": ["app"], + "$ref": "#/components/parameters/spaceId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", "properties": { - "app": { - "description": "Location of the page in the app", - "$ref": "#/components/schemas/URL" + "tunnelUrl": { + "type": "string", + "description": "URL of the tunnel to dispatch integration events to", + "minLength": 1, + "maxLength": 256 } - } - }, - "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": ["tunnelUrl"] } - }, - "required": ["kind", "type", "urls", "slug", "path", "pages", "layout"] + } } - ] - }, - "RevisionPageDocumentCover": { - "type": "object", - "properties": { - "ref": { - "description": "Content reference pointing to the source image.", - "$ref": "#/components/schemas/ContentRefFile" + }, + "responses": { + "204": { + "description": "Updated development space successfully" }, - "yPos": { - "description": "Vertical position of the cover image.", - "type": "number" + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["yPos"] + } }, - "RevisionPageGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/RevisionPageBase" - }, + "delete": { + "operationId": "removeIntegrationDevSpace", + "summary": "Remove the development space for an integration", + "tags": ["integrations"], + "security": [ { - "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"] + "user": [] } - ] - }, - "RevisionPageLayout": { - "oneOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/RevisionPageLayoutPreset" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/schemas/RevisionPageLayoutOptions" + "$ref": "#/components/parameters/spaceId" } - ] - }, - "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?" + ], + "responses": { + "204": { + "description": "Removed development space successfully" }, - "outline": { - "type": "boolean", - "description": "Should the outline be visible?" + "404": { + "description": "No matching integration dev space found", + "$ref": "#/components/responses/NotFoundError" }, - "pagination": { - "type": "boolean", - "description": "Should the pagination be visible?" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "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": [ + } + }, + "/integrations/{integrationName}/render": { + "get": { + "operationId": "renderIntegrationUIWithGet", + "summary": "Render an integration UI in the context of an installation.", + "parameters": [ { - "$ref": "#/components/schemas/RevisionPageBase" + "$ref": "#/components/parameters/integrationName" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "deprecated": true, - "enum": ["link"] - }, - "type": { - "type": "string", - "enum": ["link"] - }, - "target": { - "$ref": "#/components/schemas/ContentRef" - }, - "href": { - "type": "string" + "name": "request", + "in": "query", + "required": true, + "description": "LZ-string compressed JSON request", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ContentKit element to render", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentKitRenderOutput" + } } }, - "required": ["kind", "type", "target"] + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "RevisionPageType": { - "type": "string", - "enum": ["document", "group", "link"] + } }, - "RevisionFile": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" + "post": { + "operationId": "renderIntegrationUIWithPost", + "summary": "Render an integration UI in the context of an installation.", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" + } + ], + "responses": { + "200": { + "description": "ContentKit element to render", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentKitRenderOutput" + } + } + }, + "headers": { + "Cache-Control": { + "schema": { + "type": "string" + } + } + } }, - "contentType": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RenderIntegrationUI" + } + } + } + } + } + }, + "/integrations/{integrationName}/tasks": { + "post": { + "operationId": "queueIntegrationTask", + "summary": "Queue a task for an integration to be executed later", + "tags": ["integrations"], + "security": [ + { + "integration": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "task": { + "type": "object", + "description": "Payload for the integration task" + }, + "schedule": { + "type": "number", + "description": "Number of seconds to wait before executing the task, defaults to 0", + "minimum": 0, + "maximum": 86400 + } + }, + "required": ["task"] + } + } + } + }, + "responses": { + "204": { + "description": "Integration task created successfully" }, - "downloadURL": { - "type": "string" + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "size": { - "type": "number" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations/{integrationName}/installations/{installationId}": { + "get": { + "operationId": "getIntegrationInstallationById", + "summary": "Get a specific integration's installation by its ID", + "tags": ["integrations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "dimensions": { - "type": "object", - "description": "For images, it contains the dimensions of it.", - "properties": { - "width": { - "type": "number" - }, - "height": { - "type": "number" + { + "$ref": "#/components/parameters/installationId" + } + ], + "responses": { + "200": { + "description": "Integration installation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationInstallation" + } } - }, - "required": ["width", "height"] + } }, - "git": { - "$ref": "#/components/schemas/GitSyncBlob" - } - }, - "required": ["id", "name", "contentType", "downloadURL", "size"] - }, - "RevisionFileImageDimensions": { - "type": "object", - "properties": { - "height": { - "type": "number" + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "width": { - "type": "number" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["height", "width"] - }, - "ImportContentSource": { - "type": "string", - "enum": [ - "website", - "docx", - "markdown", - "html", - "zip", - "confluence", - "github-wiki", - "dropbox-paper", - "notion", - "quip", - "google-docs", - "open-api" - ] + } }, - "ChangeAttributeContentReference": { - "type": "object", - "properties": { - "before": { - "$ref": "#/components/schemas/ContentRef" + "patch": { + "operationId": "updateIntegrationInstallation", + "summary": "Update external IDs and configurations of an integration's installation", + "tags": ["integrations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "after": { - "$ref": "#/components/schemas/ContentRef" + { + "$ref": "#/components/parameters/installationId" } - } - }, - "ChangeAttributeCustomFields": { - "type": "object", - "properties": { - "before": { - "type": "object", - "additionalProperties": { - "type": "object", - "properties": { - "value": { - "$ref": "#/components/schemas/CustomFieldValue" + ], + "responses": { + "200": { + "description": "The installation has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationInstallation" } - }, - "required": ["value"] + } } }, - "after": { - "type": "object", - "additionalProperties": { - "type": "object", - "properties": { - "value": { - "$ref": "#/components/schemas/CustomFieldValue" - } - }, - "required": ["value"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationInstallation" + } } } } }, - "ChangeAttributeNumber": { - "type": "object", - "properties": { - "before": { - "type": "number" - }, - "after": { - "type": "number" + "delete": { + "operationId": "uninstallIntegration", + "summary": "Uninstall the integration from a target organization", + "tags": ["integrations"], + "security": [ + { + "user": [] } - } - }, - "ChangeAttributeRevisionFileImageDimensions": { - "type": "object", - "properties": { - "before": { - "$ref": "#/components/schemas/RevisionFileImageDimensions" + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "after": { - "$ref": "#/components/schemas/RevisionFileImageDimensions" + { + "$ref": "#/components/parameters/installationId" } - } - }, - "ChangeAttributeRevisionPageDocumentCover": { - "type": "object", - "properties": { - "before": { - "$ref": "#/components/schemas/RevisionPageDocumentCover" + ], + "responses": { + "204": { + "description": "Integration uninstalled successfully" }, - "after": { - "$ref": "#/components/schemas/RevisionPageDocumentCover" + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "ChangeAttributeRevisionPageLayout": { - "type": "object", - "properties": { - "before": { - "$ref": "#/components/schemas/RevisionPageLayout" + } + }, + "/integrations/{integrationName}/installations/{installationId}/tokens": { + "post": { + "operationId": "createIntegrationInstallationToken", + "summary": "Create an integration installation API token", + "description": "Creates a temporary API token of an integration's installation that has access to the installation and it's scopes. You must be authenticated as the integration to obtain this token.\n", + "tags": ["integrations"], + "security": [ + { + "integration": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "after": { - "$ref": "#/components/schemas/RevisionPageLayout" + { + "$ref": "#/components/parameters/installationId" } - } - }, - "ChangeAttributeString": { - "type": "object", - "properties": { - "before": { - "type": "string" + ], + "responses": { + "200": { + "description": "The API token for the installation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/APITemporaryToken" + } + } + } + }, + "404": { + "description": "Installation could not be found", + "$ref": "#/components/responses/NotFoundError" }, - "after": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "ChangedRevisionFile": { - "type": "object", - "properties": { - "id": { - "type": "string" + } + }, + "/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" }, - "name": { - "type": "string" + { + "$ref": "#/components/parameters/installationId" }, - "contentType": { - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "downloadURL": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["id", "name", "contentType", "downloadURL"] - }, - "ChangedRevisionPage": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "type": { - "$ref": "#/components/schemas/RevisionPageType" - }, - "title": { - "type": "string" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } + } + ] + } + } + } }, - "path": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["id", "type", "title"] + } }, - "RevisionFileChangeAttributes": { - "type": "object", - "minProperties": 1, - "properties": { - "name": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "downloadURL": { - "$ref": "#/components/schemas/ChangeAttributeString" + "post": { + "operationId": "installIntegrationOnSpace", + "summary": "Install integration on a space using an existing installation", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "size": { - "$ref": "#/components/schemas/ChangeAttributeNumber" + { + "$ref": "#/components/parameters/installationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["space"], + "properties": { + "space": { + "type": "string", + "description": "ID of the space to install the integration on" + } + } + } + } + } + }, + "responses": { + "201": { + "headers": { + "Location": { + "description": "URL for the installed integration", + "schema": { + "type": "string" + } + } + }, + "description": "Integration installed successfully on space", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } }, - "contentType": { - "$ref": "#/components/schemas/ChangeAttributeString" + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "dimensions": { - "$ref": "#/components/schemas/ChangeAttributeRevisionFileImageDimensions" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "RevisionPageDocumentChangeAttributes": { - "type": "object", - "minProperties": 1, - "properties": { - "title": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "description": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "slug": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "document": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "cover": { - "$ref": "#/components/schemas/ChangeAttributeRevisionPageDocumentCover" - }, - "emoji": { - "$ref": "#/components/schemas/ChangeAttributeString" + } + }, + "/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}": { + "get": { + "operationId": "getIntegrationSpaceInstallation", + "summary": "Get a specific integration's space installation", + "tags": ["integrations"], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "layout": { - "$ref": "#/components/schemas/ChangeAttributeRevisionPageLayout" + { + "$ref": "#/components/parameters/installationId" }, - "customFields": { - "$ref": "#/components/schemas/ChangeAttributeCustomFields" + { + "$ref": "#/components/parameters/spaceId" } - } - }, - "RevisionPageGroupChangeAttributes": { - "type": "object", - "minProperties": 1, - "properties": { - "title": { - "$ref": "#/components/schemas/ChangeAttributeString" - }, - "emoji": { - "$ref": "#/components/schemas/ChangeAttributeString" + ], + "responses": { + "200": { + "description": "Integration space installation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } }, - "slug": { - "$ref": "#/components/schemas/ChangeAttributeString" + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "customFields": { - "$ref": "#/components/schemas/ChangeAttributeCustomFields" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "RevisionPageLinkChangeAttributes": { - "type": "object", - "minProperties": 1, - "properties": { - "title": { - "$ref": "#/components/schemas/ChangeAttributeString" + "patch": { + "operationId": "updateIntegrationSpaceInstallation", + "summary": "Update external IDs and configurations of an integration's installation for a space", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "emoji": { - "$ref": "#/components/schemas/ChangeAttributeString" + { + "$ref": "#/components/parameters/installationId" }, - "target": { - "$ref": "#/components/schemas/ChangeAttributeContentReference" + { + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "200": { + "description": "The space installation has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + } + } + } }, - "customFields": { - "$ref": "#/components/schemas/ChangeAttributeCustomFields" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationSpaceInstallation" + } + } } } }, - "RevisionSemanticChange": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionSemanticChangePageCreated" - }, + "delete": { + "operationId": "uninstallIntegrationFromSpace", + "summary": "Uninstall the integration from a space", + "parameters": [ { - "$ref": "#/components/schemas/RevisionSemanticChangePageEdited" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/schemas/RevisionSemanticChangePageDeleted" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/schemas/RevisionSemanticChangePageMoved" + "$ref": "#/components/parameters/spaceId" + } + ], + "responses": { + "204": { + "description": "The space installation has been deleted." }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/integrations/{integrationName}/installations/{installationId}/sites": { + "get": { + "operationId": "listIntegrationInstallationSites", + "summary": "List installations on sites for an integration in an organization", + "tags": ["integrations"], + "parameters": [ { - "$ref": "#/components/schemas/RevisionSemanticChangeFileCreated" + "$ref": "#/components/parameters/integrationName" }, { - "$ref": "#/components/schemas/RevisionSemanticChangeFileEdited" + "$ref": "#/components/parameters/installationId" }, { - "$ref": "#/components/schemas/RevisionSemanticChangeFileDeleted" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/RevisionSemanticChangeCustomFieldsEdited" - } - ] - }, - "RevisionSemanticChangeCustomFieldsEdited": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["custom_fields_edited"] - }, - "customFields": { - "$ref": "#/components/schemas/ChangeAttributeCustomFields" + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["type", "customFields"] - }, - "RevisionSemanticChangeFileCreated": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file_created"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationSiteInstallation" + } + } + } + } + ] + } + } + } }, - "file": { - "$ref": "#/components/schemas/ChangedRevisionFile" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "file"] + } }, - "RevisionSemanticChangeFileDeleted": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file_deleted"] + "post": { + "operationId": "installIntegrationOnSite", + "summary": "Install integration on a site using an existing installation", + "tags": ["integrations"], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "file": { - "$ref": "#/components/schemas/ChangedRevisionFile" + { + "$ref": "#/components/parameters/installationId" } - }, - "required": ["type", "file"] - }, - "RevisionSemanticChangeFileEdited": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file_edited"] - }, - "file": { - "$ref": "#/components/schemas/ChangedRevisionFile" - }, - "attributes": { - "$ref": "#/components/schemas/RevisionFileChangeAttributes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["siteId"], + "properties": { + "siteId": { + "type": "string", + "description": "ID of the site to install the integration on" + } + } + } + } } }, - "required": ["type", "file", "attributes"] - }, - "RevisionSemanticChangePageCreated": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page_created"] + "responses": { + "201": { + "headers": { + "Location": { + "description": "URL for the installed integration on the site", + "schema": { + "type": "string" + } + } + }, + "description": "Integration installed successfully on site", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSiteInstallation" + } + } + } }, - "page": { - "$ref": "#/components/schemas/ChangedRevisionPage" - } - }, - "required": ["type", "page"] - }, - "RevisionSemanticChangePageDeleted": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page_deleted"] + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "page": { - "$ref": "#/components/schemas/ChangedRevisionPage" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "page"] - }, - "RevisionSemanticChangePageEdited": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page_edited"] + } + } + }, + "/integrations/{integrationName}/installations/{installationId}/sites/{siteId}": { + "get": { + "operationId": "getIntegrationSiteInstallation", + "summary": "Get a specific integration's site installation", + "tags": ["integrations"], + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "page": { - "$ref": "#/components/schemas/ChangedRevisionPage" + { + "$ref": "#/components/parameters/installationId" }, - "attributes": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocumentChangeAttributes" - }, - { - "$ref": "#/components/schemas/RevisionPageGroupChangeAttributes" - }, - { - "$ref": "#/components/schemas/RevisionPageLinkChangeAttributes" - } - ] + { + "$ref": "#/components/parameters/siteId" } - }, - "required": ["type", "page", "attributes"] - }, - "RevisionSemanticChangePageMoved": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page_moved"] - }, - "page": { - "$ref": "#/components/schemas/ChangedRevisionPage" - }, - "parent": { - "type": "object", - "properties": { - "before": { - "$ref": "#/components/schemas/ChangedRevisionPage" - }, - "after": { - "$ref": "#/components/schemas/ChangedRevisionPage" + ], + "responses": { + "200": { + "description": "Integration site installation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSiteInstallation" + } } } - } - }, - "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" - ] - }, - "GitSyncState": { - "type": "object", - "properties": { - "installationProvider": { - "type": "string", - "description": "The provider of the Git Sync installation." - }, - "operation": { - "$ref": "#/components/schemas/GitSyncOperation" }, - "url": { - "type": "string", - "description": "The URL to the repository tree, used when rendering public content." + "404": { + "$ref": "#/components/responses/NotFoundError" }, - "updatedAt": { - "description": "When the Git provider details were last updated", - "$ref": "#/components/schemas/Timestamp" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "GitSyncOperation": { - "type": "object", - "properties": { - "state": { - "$ref": "#/components/schemas/GitSyncOperationState" + "patch": { + "operationId": "updateIntegrationSiteInstallation", + "summary": "Update external IDs and configurations of an integration's installation for a site", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "startedAt": { - "$ref": "#/components/schemas/Timestamp" + { + "$ref": "#/components/parameters/installationId" }, - "completedAt": { - "description": "Date when the operation was successful (when state is `success`)", - "$ref": "#/components/schemas/Timestamp" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "The site installation has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationSiteInstallation" + } + } + } }, - "error": { - "type": "string", - "description": "Error details, defined if state is `failure`." + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["state"] - }, - "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"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateIntegrationSiteInstallation" + } + } + } + } }, - "GitSyncCommit": { - "type": "object", - "properties": { - "oid": { - "type": "string", - "description": "SHA for the commit" + "delete": { + "operationId": "uninstallIntegrationFromSite", + "summary": "Uninstall the integration from a site", + "parameters": [ + { + "$ref": "#/components/parameters/integrationName" }, - "message": { - "type": "string", - "description": "Message describing the purpose of the commit" + { + "$ref": "#/components/parameters/installationId" }, - "createdByGitBook": { - "type": "boolean", - "description": "If true, the Git commit was generated by an export from GitBook" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "204": { + "description": "The site installation has been deleted." }, - "url": { - "type": "string", - "description": "URL of the commit in the GitSync provider" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs": { + "get": { + "operationId": "listOrganizationsForAuthenticatedUser", + "summary": "Get the list of organizations for the currently authenticated user", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/listPage" }, - "ref": { - "type": "string", - "description": "Original name of the ref where the commit originated from" + { + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["oid", "message", "createdByGitBook"] - }, - "GitSyncBlob": { - "type": "object", - "properties": { - "oid": { - "type": "string", - "description": "SHA for the blob" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Organization" + } + } + }, + "required": ["items"] + } + ] + } + } + } }, - "path": { - "type": "string", - "description": "Path of the blob in the Git tree" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["oid", "path"] + } }, - "Organization": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"organization\"", - "enum": ["organization"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the organization" - }, - "title": { - "$ref": "#/components/schemas/OrganizationTitle" - }, - "emailDomains": { - "$ref": "#/components/schemas/OrganizationEmailDomains" - }, - "type": { - "$ref": "#/components/schemas/OrganizationType" - }, - "useCase": { - "$ref": "#/components/schemas/OrganizationUseCase" - }, - "communityType": { - "$ref": "#/components/schemas/OrganizationCommunityType" - }, - "defaultRole": { - "$ref": "#/components/schemas/MemberRoleOrGuest" - }, - "defaultContent": { - "$ref": "#/components/schemas/OrganizationDefaultContent" - }, - "sso": { - "description": "Whether SSO is enforced organization wide", - "type": "boolean" - }, - "ai": { - "description": "If true, the organization is configured to use all our AI features.", - "type": "boolean" - }, - "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" + "post": { + "operationId": "createOrganization", + "summary": "Create an organization", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateOrganization" } - }, - "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"] - }, - "OrganizationExperimentalFeature": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "title": { - "type": "string" + "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" + } + } + } }, - "description": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}": { + "get": { + "operationId": "getOrganizationById", + "summary": "Get an organization by its ID", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } }, - "enabled": { - "type": "boolean" + "404": { + "description": "No matching organization found for given id", + "$ref": "#/components/responses/NotFoundError" }, - "stage": { - "type": "string", - "enum": ["alpha", "beta"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["id", "title", "description", "enabled", "stage"] - }, - "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": [ + "delete": { + "operationId": "deleteOrganizationById", + "summary": "Delete an organization by its ID", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/MemberRole" - }, + "user-internal": [] + } + ], + "parameters": [ { - "type": "string", - "nullable": true, - "enum": [null] + "$ref": "#/components/parameters/organizationId" } - ] - }, - "OrganizationTransferResponse": { - "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." + ], + "responses": { + "205": { + "description": "The organization has been successfully deleted" }, - "newSourceHostname": { - "type": "string", - "description": "The new hostname if the source organization needed to change hostname." + "404": { + "description": "No matching organization found for given id", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "OrganizationTarget": { - "type": "object", - "required": ["organization"], - "properties": { - "organization": { - "type": "string" + "patch": { + "operationId": "updateOrganizationById", + "summary": "Update an organization by its ID", + "tags": ["organizations"], + "security": [ + { + "user": [] } - } - }, - "OrganizationMember": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"member\"", - "enum": ["member"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the user." - }, - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest" - }, - "user": { - "$ref": "#/components/schemas/User" - }, - "disabled": { - "type": "boolean", - "description": "Whatever the membership of this user is disabled and prevent them from accessing content." - }, - "joinedAt": { - "description": "Date at which the user joined the organization.", - "$ref": "#/components/schemas/Timestamp" - }, - "lastSeenAt": { - "description": "Date at which the user was last seen active in the organization.", - "$ref": "#/components/schemas/Timestamp" - }, - "sso": { - "type": "boolean", - "description": "Whether the user can login with SSO." + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTitle" + }, + "emailDomains": { + "$ref": "#/components/schemas/OrganizationEmailDomains" + }, + "hostname": { + "$ref": "#/components/schemas/OrganizationHostname" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "defaultContent": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationDefaultContent" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "logo": { + "oneOf": [ + { + "$ref": "#/components/schemas/URL" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "sso": { + "type": "boolean" + }, + "ai": { + "type": "boolean" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The organization has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } }, - "spaces": { - "type": "number" + "400": { + "description": "Invalid default content space or collection provided", + "$ref": "#/components/responses/BadRequestError" }, - "teams": { - "type": "number" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": [ - "object", - "id", - "role", - "user", - "disabled", - "joinedAt", - "sso", - "spaces", - "teams" - ] - }, - "OrganizationTeam": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"team\"", - "enum": ["team"] + } + } + }, + "/orgs/{organizationId}/members": { + "get": { + "operationId": "listMembersInOrganizationById", + "summary": "List organization members", + "description": "Lists members for the specified organization.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "id": { - "type": "string", - "description": "Unique identifier for the team." + { + "$ref": "#/components/parameters/listPage" }, - "title": { - "$ref": "#/components/schemas/OrganizationTeamTitle" + { + "$ref": "#/components/parameters/listLimit" }, - "members": { - "type": "integer", - "description": "Count of members in this team." + { + "$ref": "#/components/parameters/listOrder" }, - "spaces": { - "type": "number", - "description": "Count of spaces this team has access to." + { + "name": "role", + "description": "The Role to filter the member list by", + "in": "query", + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/MemberRole" + }, + { + "type": "string", + "enum": ["guest"] + } + ] + } }, - "createdAt": { - "description": "Date at which the team was created.", - "$ref": "#/components/schemas/Timestamp" - } - }, - "required": ["object", "id", "title", "members", "spaces", "createdAt"] - }, - "OrganizationTeamTitle": { - "type": "string", - "description": "Title of the team", - "minLength": 1, - "maxLength": 64 - }, - "TeamMember": { - "type": "object", - "properties": { - "role": { - "$ref": "#/components/schemas/TeamMemberRole" + { + "name": "search", + "in": "query", + "description": "A query to filter the member list (displayName and email)", + "schema": { + "type": "string" + } + }, + { + "name": "sort", + "in": "query", + "description": "The property to sort the results by. When sorting by lastSeenAt, only active members will be listed.", + "schema": { + "type": "string", + "default": "joinedAt", + "enum": ["joinedAt", "lastSeenAt"] + } } - }, - "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"] - }, - "OrganizationTeamMember": { - "type": "object", - "description": "A member of a team in an organization, including its relationship to it", - "properties": { - "organization": { - "$ref": "#/components/schemas/OrganizationMember" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationMember" + } + } + } + } + ] + } + } + } }, - "team": { - "$ref": "#/components/schemas/TeamMember" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["organization", "team"] - }, - "OrganizationDefaultContent": { - "description": "The default content for the organization", - "oneOf": [ + } + } + }, + "/orgs/{organizationId}/members/{userId}": { + "get": { + "operationId": "getMemberInOrganizationById", + "summary": "Get specified organization member", + "description": "Gets a specific member in an organization.\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/SpacePointer" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/CollectionPointer" + "$ref": "#/components/parameters/userId" } - ] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationMember" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } }, - "OrganizationInvite": { - "allOf": [ + "patch": { + "operationId": "updateMemberInOrganizationById", + "summary": "Update specified organization member", + "description": "Updates a specific member in an organization.\n", + "tags": ["organizations"], + "security": [ { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"invite\"", - "enum": ["invite"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the organization invite" - } - }, - "required": ["object", "id"] + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "oneOf": [ - { + "$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": { "type": "object", "properties": { "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest", - "description": "The role of the member in the organization" - } - }, - "required": ["role"] - }, - { - "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"] - }, - { - "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" + "$ref": "#/components/schemas/MemberRoleOrGuest" } - }, - "required": ["level", "collection"] + } } - ] + } } - ] + } }, - "OrganizationPointer": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["organization"] - }, - "organization": { - "type": "string", - "description": "Unique identifier for the organization" + "delete": { + "operationId": "removeMemberFromOrganizationById", + "summary": "Delete a member from an organization", + "description": "Deletes a specific member from an organization\n", + "tags": ["organizations"], + "security": [ + { + "user": [] } - }, - "required": ["type", "organization"] - }, - "Capture": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the capture" - }, - "title": { - "$ref": "#/components/schemas/CaptureTitle" + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "context": { - "$ref": "#/components/schemas/CaptureContext" + { + "$ref": "#/components/parameters/userId" + } + ], + "responses": { + "204": { + "description": "The member was deleted from the organization." }, - "externalId": { - "type": "string", - "description": "ID in the original source of the capture." + "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", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "204": { + "description": "Organization member has been updated." }, - "externalURL": { - "type": "string", - "format": "uri", - "description": "URL of the source from which the capture originated" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/members/{userId}/sso": { + "post": { + "operationId": "setUserAsSSOMemberForOrganization", + "summary": "Set a user as an SSO member of an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "createdAt": { - "type": "string", - "format": "date-time" + { + "$ref": "#/components/parameters/userId" + } + ], + "responses": { + "200": { + "description": "The user has been added as an SSO member of the organization.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationMember" + } + } + } }, - "stoppedAt": { - "type": "string", - "format": "date-time" + "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"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "editedAt": { - "type": "string", - "format": "date-time" + { + "$ref": "#/components/parameters/userId" }, - "events": { - "description": "Count of events recorded.", - "properties": { - "terminal.command": { - "type": "integer" - }, - "speech": { - "type": "integer" - }, - "thread.message": { - "type": "integer" - } - } + { + "$ref": "#/components/parameters/listPage" }, - "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", - "minItems": 1, - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/Integration" - }, - { - "$ref": "#/components/schemas/User" + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "Listing of spaces that can be accessed by the user in the organization.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MemberContentPermission" + } + } + } + } + ] } - ] + } } }, - "output": { - "description": "Output document for the capture. Is not set when capture is not finished.", - "$ref": "#/components/schemas/Document" - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the capture in the API", - "format": "uri" - }, - "app": { - "type": "string", - "description": "URL of the capture in the app", - "format": "uri" - } - }, - "required": ["location", "app"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/members/{userId}/teams": { + "get": { + "operationId": "listTeamsForOrganizationMember", + "summary": "List all teams an organization member is part of", + "tags": ["teams"], + "security": [ + { + "user": [] } - }, - "required": [ - "object", - "id", - "title", - "context", - "events", - "createdAt", - "contributors", - "urls" - ] - }, - "CaptureTitle": { - "type": "string", - "description": "Optional title describing the capture", - "maxLength": 100 - }, - "CaptureEvent": { - "oneOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/CaptureTerminalCommandEvent" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/CaptureSpeechEvent" + "$ref": "#/components/parameters/userId" }, { - "$ref": "#/components/schemas/CaptureThreadMessageEvent" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/CaptureFileAddedEvent" + "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/schemas/CaptureFileChangedEvent" + "in": "query", + "name": "title", + "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "required": ["team", "member"], + "properties": { + "team": { + "$ref": "#/components/schemas/OrganizationTeam" + }, + "member": { + "$ref": "#/components/schemas/TeamMember" + } + } + } + } + } + } + ] + } + } + } }, - { - "$ref": "#/components/schemas/CaptureFileRemovedEvent" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "CaptureContext": { - "oneOf": [ + } + } + }, + "/orgs/{organizationId}/teams": { + "get": { + "operationId": "listTeamsInOrganizationById", + "summary": "List organization teams", + "description": "Lists teams for the specified organization.\n", + "tags": ["organizations"], + "security": [ { - "type": "string", - "enum": ["thread", "walkthrough", "document"] + "user": [] } - ] - }, - "BaseCaptureEvent": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of event" + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "timestamp": { - "type": "string", - "format": "date-time", - "description": "When the event happened" + { + "$ref": "#/components/parameters/listPage" }, - "source": { - "type": "string", - "description": "Optionally, provide the source of the event. GitBook may use this to improve the generated content.", - "maxLength": 50 + { + "$ref": "#/components/parameters/listLimit" }, - "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" + { + "in": "query", + "name": "owner", + "description": "The unique identifier of a member of the organization. Only teams they can manage will be returned.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "title", + "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationTeam" + } + } + } + } + ] + } } - }, - "required": ["name"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "timestamp"] + } }, - "CaptureSpeechEvent": { - "allOf": [ + "put": { + "operationId": "createOrganizationTeam", + "summary": "Create organization team", + "description": "Creates a team in the specified organization.\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/BaseCaptureEvent" - }, + "user": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["speech"] + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "201": { + "description": "Team has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationTeam" + } } - }, - "required": ["type"] + } }, - { - "oneOf": [ - { - "type": "object", - "properties": { - "audio": { - "description": "WAV audio file, encoded as base64", - "type": "string" - } - }, - "required": ["audio"] - }, - { + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "transcript": { - "description": "Transcript of the speech", - "type": "string" + "title": { + "$ref": "#/components/schemas/OrganizationTeamTitle" + }, + "members": { + "description": "A list of organization member identifiers", + "type": "array", + "items": { + "type": "string" + } } }, - "required": ["transcript"] + "required": ["title"] } - ] + } + } + } + } + }, + "/orgs/{organizationId}/teams/{teamId}": { + "get": { + "operationId": "getTeamInOrganizationById", + "summary": "Get specified organization team", + "description": "Gets a specific team in an organization.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] } - ] - }, - "CaptureTerminalCommandEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/BaseCaptureEvent" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["terminal.command"] - }, - "command": { - "type": "string" - }, - "stdout": { - "type": "string" + "$ref": "#/components/parameters/teamId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationTeam" + } } - }, - "required": ["type", "command", "stdout"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "CaptureThreadMessageEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" - }, + "patch": { + "operationId": "updateTeamInOrganizationById", + "summary": "Update specified organization team", + "description": "Updates a specific team in an organization.\n", + "tags": ["organizations"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["thread.message"] - }, - "isFirst": { - "type": "boolean" - }, - "text": { - "type": "string" - } - }, - "required": ["type", "text"] + "user": [] } - ] - }, - "CaptureFileAddedEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/BaseCaptureEvent" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file.added"] - }, - "filename": { - "type": "string" - }, - "fileSnapshot": { - "type": "string" - } - }, - "required": ["type", "filename", "fileSnapshot"] + "$ref": "#/components/parameters/teamId" } - ] - }, - "CaptureFileChangedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseCaptureEvent" + ], + "responses": { + "200": { + "description": "The team has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationTeam" + } + } + } }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file.changed"] - }, - "filename": { - "type": "string" - }, - "fileDiff": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTeamTitle" + } + }, + "required": ["title"] } - }, - "required": ["type", "filename", "fileDiff"] + } } - ] + } }, - "CaptureFileRemovedEvent": { - "allOf": [ + "delete": { + "operationId": "removeTeamFromOrganizationById", + "summary": "Delete a team in an organization", + "description": "Deletes a specific team in an organization\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/BaseCaptureEvent" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["file.removed"] - }, - "filename": { - "type": "string" - }, - "fileSnapshot": { - "type": "string" - } - }, - "required": ["type", "filename", "fileSnapshot"] + "$ref": "#/components/parameters/teamId" } - ] - }, - "Snippet": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the snippet" - }, - "organization": { - "type": "string", - "description": "ID of the organization owning this snippet" - }, - "createdAt": { - "type": "string", - "format": "date-time" - }, - "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." - }, - "name": { - "type": "string", - "description": "A display name for the source." - }, - "externalId": { - "type": "string", - "description": "An ID identifying the snippet in the source system, if available." - }, - "externalUrl": { - "description": "URL of the snippet in the source system, if available.", - "$ref": "#/components/schemas/URL" - } - }, - "required": ["sourceId", "name"] + ], + "responses": { + "204": { + "description": "The team was deleted from the organization." }, - "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" - } - ] - } + "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", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "description": "URL of the snippet in the API", - "$ref": "#/components/schemas/URL" - }, - "app": { - "description": "URL of the snippet in the app", - "$ref": "#/components/schemas/URL" + { + "$ref": "#/components/parameters/teamId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateMembersInOrganizationTeam" } - }, - "required": ["location", "app"] + } } }, - "required": [ - "id", - "organization", - "source", - "createdAt", - "archived", - "contributors", - "urls" - ] - }, - "UpdateSnippetSchema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "A new title for the snippet." + "responses": { + "204": { + "description": "Members have been updated" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "SyncedBlock": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the synced block" + "get": { + "operationId": "listTeamMembersInOrganizationById", + "summary": "List team members", + "description": "Lists members, and their roles, for the specified organization team.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "organization": { - "type": "string", - "description": "ID of the organization owning this synced block" + { + "$ref": "#/components/parameters/teamId" }, - "createdAt": { - "type": "string", - "format": "date-time" + { + "$ref": "#/components/parameters/listPage" }, - "title": { - "type": "string", - "description": "Title describing the synced block.", - "maxLength": 100 + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationTeamMember" + } + } + } + } + ] + } + } + } }, - "document": { - "$ref": "#/components/schemas/JSONDocument" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/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", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "description": "URL of the synced block in the API", - "$ref": "#/components/schemas/URL" + { + "$ref": "#/components/parameters/teamId" + }, + { + "$ref": "#/components/parameters/userId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/TeamMemberRole" + } + } } - }, - "required": ["location"] + } } }, - "required": ["id", "organization", "source", "createdAt", "urls", "document"] + "responses": { + "204": { + "description": "Member has been added to the team" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } }, - "ContentAuditRelation": { - "type": "object", - "description": "Content audit relation", - "properties": { - "id": { - "type": "string" + "delete": { + "operationId": "deleteMemberFromOrganizationTeamById", + "summary": "Delete members from a team", + "description": "Deletes member from the specified organization team.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "sources": { - "description": "The sources that are related", - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentAuditSource" - } + { + "$ref": "#/components/parameters/teamId" }, - "type": { - "description": "The type of the relation between the sources", - "$ref": "#/components/schemas/ContentAuditRelationType" + { + "$ref": "#/components/parameters/userId" + } + ], + "responses": { + "204": { + "description": "Member has been deleted from the team" }, - "reason": { - "type": "string", - "description": "A human readable description of the reason for the relation" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/invites": { + "post": { + "operationId": "inviteUsersToOrganization", + "summary": "Invite users to a given organization based on a list of emails", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "type": "string", + "description": "The unique identifiers of the users who were added to the organization" + } + }, + "invited": { + "type": "number", + "description": "The number of users who were added to the organization" + }, + "failedSSOEmails": { + "type": "array", + "items": { + "type": "string", + "description": "A list of emails who were invited to the organization, but who were not added as SSO users as they are members of another org" + } + } + }, + "required": ["users", "invited"] + } + } + } }, - "status": { - "description": "The status of the relation", - "$ref": "#/components/schemas/ContentAuditRelationStatus" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "createdAt": { - "description": "The date at which the relation was created", - "$ref": "#/components/schemas/Timestamp" + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": ["id", "sources", "type", "status", "createdAt"] - }, - "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", - "properties": { - "status": { - "$ref": "#/components/schemas/ContentAuditRelationStatus" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InviteUsersToOrganization" + } + } } - }, - "required": ["status"] - }, - "ContentAuditSource": { - "oneOf": [ + } + } + }, + "/orgs/{organizationId}/invites/{inviteId}": { + "post": { + "operationId": "joinOrganizationWithInvite", + "summary": "Use an invite to join an organization.", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/ContentAuditSourceSection" + "user": [] } - ] - }, - "ContentAuditSourceSection": { - "type": "object", - "description": "A GitBook section source", - "properties": { - "id": { - "type": "string" - }, - "type": { - "type": "string", - "enum": ["section"] - }, - "space": { - "$ref": "#/components/schemas/Space" + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "page": { - "$ref": "#/components/schemas/RevisionPageDocument" + { + "$ref": "#/components/parameters/inviteId" } - }, - "required": ["id", "type", "space", "page"] - }, - "ContentReferenceUsage": { - "type": "object", - "properties": { - "status": { - "$ref": "#/components/schemas/ContentReferenceStatus" - }, - "targetReference": { - "description": "The reference target where a list of pages are pointing at", - "$ref": "#/components/schemas/ContentReferenceResolved" - }, - "locationReferences": { - "description": "All pages where the target is being referenced.", - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentReferenceResolved" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": {} + } + } } - } - }, - "required": ["status", "targetReference", "locationReferences"] - }, - "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": [ - "space", - "page", - "file", - "anchor", - "collection", - "user", - "snippet", - "url", - "synced-block" - ] }, - "url": { - "description": "Target in-app url for the reference", - "type": "string" - }, - "extra": { - "type": "object", - "properties": { - "collection": { - "$ref": "#/components/schemas/Collection" - }, - "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" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/link-invites": { + "post": { + "operationId": "createOrganizationInvite", + "summary": "Create a new organization invite", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateOrganizationInvite" } } } }, - "required": ["text", "type", "url", "extra"] - }, - "ContentReferenceStatus": { - "type": "string", - "enum": ["ok", "broken", "in-app"], - "description": "Text to display to represent the reference. Possible values include:\n- `ok` - No problems detected for this content reference.\n- `broken` - The target does not exist in the revision.\n- `in-app` - The target is a URL link pointing to an internal location in the app.\n" - }, - "ContentReferencesStats": { - "type": "object", - "properties": { - "total": { - "description": "Total count of links", - "type": "number" - }, - "broken": { - "type": "object", - "properties": { - "total": { - "description": "Count of broken links", - "type": "number" - }, - "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" + "responses": { + "201": { + "description": "The organization invite has been created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationInvite" + } } - }, - "required": ["total", "space", "changeRequest"] - } - }, - "required": ["total", "broken"] - }, - "ChangeRequest": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"change-request\"", - "enum": ["change-request"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the change request" - }, - "number": { - "type": "number", - "description": "Incremental identifier of the change request" - }, - "status": { - "$ref": "#/components/schemas/ChangeRequestStatus" - }, - "subject": { - "$ref": "#/components/schemas/ChangeRequestSubject" - }, - "createdBy": { - "$ref": "#/components/schemas/User" - }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" - }, - "updatedAt": { - "$ref": "#/components/schemas/Timestamp" + } }, - "revision": { - "type": "string", - "description": "ID of the active revision in the change request." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/link-invites/{inviteId}": { + "patch": { + "operationId": "updateOrganizationInviteById", + "summary": "Update an organization invite.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "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" + { + "$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"] + } + ] } - }, - "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"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the review." - }, - "revision": { - "type": "string", - "description": "The revision this review was made against." - }, - "reviewer": { - "description": "The user who performed the review.", - "$ref": "#/components/schemas/User" - }, - "requestedBy": { - "description": "The user who requested the review. If undefined, the review was left without a request.", - "$ref": "#/components/schemas/User" + "responses": { + "200": { + "description": "The organization invite has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationInvite" + } + } + } }, - "status": { - "description": "The status of the review.", - "$ref": "#/components/schemas/ChangeRequestReviewStatus" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "delete": { + "operationId": "deleteOrganizationInviteById", + "summary": "Deletes an organization invite.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "comment": { - "$ref": "#/components/schemas/Comment" + { + "$ref": "#/components/parameters/inviteId" + } + ], + "responses": { + "205": { + "description": "The organization invite has been deleted" }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + "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": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingUpgrade" + } + } + } }, - "updatedAt": { - "$ref": "#/components/schemas/Timestamp" + "default": { + "$ref": "#/components/responses/UnexpectedError" } }, - "required": [ - "object", - "id", - "revision", - "reviewer", - "status", - "createdAt", - "updatedAt" - ] - }, - "ChangeRequestReviewStatus": { - "type": "string", - "description": "Status of a change request review.", - "enum": ["changes-requested", "approved"] + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpgradeOrganizationBilling" + } + } + } + } }, - "ChangeRequestRequestedReviewer": { - "type": "object", - "allOf": [ + "get": { + "operationId": "getOrganizationBillingPortal", + "summary": "Get the billing portal for an organization", + "tags": ["organizations"], + "security": [ { - "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"] - }, + "user-internal": [] + } + ], + "parameters": [ { - "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"] + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingPortal" + } } - ] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "ChangeRequestSubject": { - "type": "string", - "description": "Subject of the change request", - "minLength": 0, - "maxLength": 100 - }, - "UpdateCommentSchema": { - "type": "object", - "properties": { - "resolved": { - "type": "boolean", - "description": "Whether the comment is resolved or not." + } + } + }, + "/orgs/{organizationId}/billing/preview": { + "get": { + "operationId": "previewBillingInvoice", + "summary": "Generates a billing invoice preview for organizations without an active subscription", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "body": { - "description": "Content of the comment.", - "$ref": "#/components/schemas/Document" + { + "name": "interval", + "in": "query", + "required": true, + "description": "The desired billing interval plan", + "schema": { + "$ref": "#/components/schemas/BillingInterval" + } }, - "addedReactions": { - "type": "array", - "description": "Reactions to add to the comment.", - "items": { - "type": "string" + { + "name": "product", + "in": "query", + "required": true, + "description": "The desired core plan", + "schema": { + "$ref": "#/components/schemas/BillingProduct" } }, - "removedReactions": { - "type": "array", - "description": "Reactions to remove from the comment.", - "items": { - "type": "string" + { + "name": "members", + "in": "query", + "description": "The desired amount of members in the organization", + "schema": { + "type": "number" } + }, + { + "name": "premiumSites", + "in": "query", + "description": "The desired amount of published premium sites", + "schema": { + "type": "number" + } + }, + { + "name": "audienceSites", + "in": "query", + "description": "The desired amount of published audience sites", + "schema": { + "type": "number" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingInvoicePreview" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "UpdateCommentReplySchema": { - "type": "object", - "properties": { - "body": { - "description": "Content of the comment.", - "$ref": "#/components/schemas/Document" + } + }, + "/orgs/{organizationId}/request_upgrade": { + "post": { + "operationId": "requestOrganizationUpgrade", + "summary": "Send a request to ask the organization's admin to upgrade it.", + "tags": ["organizations"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": {} + } + } + } }, - "addedReactions": { - "type": "array", - "description": "Reactions to add to the comment.", - "items": { + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/search": { + "get": { + "operationId": "searchOrganizationContent", + "summary": "Search content in an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "name": "query", + "in": "query", + "required": true, + "schema": { "type": "string" } }, - "removedReactions": { - "type": "array", - "description": "Reactions to remove from the comment.", - "items": { - "type": "string" + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchSpaceResult" + } + } + } + } + ] + } + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "PostCommentSchema": { - "type": "object", - "properties": { - "node": { - "description": "The node to which the comment is posted, if any.", - "type": "string" + } + }, + "/orgs/{organizationId}/spaces": { + "get": { + "operationId": "listSpacesInOrganizationById", + "summary": "List organization spaces", + "description": "Lists spaces for the specified organization.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "page": { - "description": "The page to which the comment is posted, if any.", - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "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/parameters/listLimit" }, - "user": { - "$ref": "#/components/schemas/User" + { + "name": "visibility", + "in": "query", + "description": "If defined, only content with this visibility will be returned.", + "schema": { + "$ref": "#/components/schemas/ContentVisibility" + } } - }, - "required": ["permission", "user"] - }, - "MemberContentPermission": { - "type": "object", - "description": "Permission of a member in a content.", - "properties": { - "permission": { - "$ref": "#/components/schemas/MemberRole" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Space" + } + } + } + } + ] + } + } + } }, - "space": { - "$ref": "#/components/schemas/Space" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["permission", "space"] + } }, - "SearchSpaceResult": { - "type": "object", - "description": "Search result representing a space.", - "properties": { - "id": { - "type": "string" - }, - "title": { - "type": "string" - }, - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchPageResult" + "post": { + "operationId": "createSpace", + "summary": "Create an organization space", + "tags": ["spaces"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSpace" + } } } }, - "required": ["id", "title", "pages"] - }, - "SearchPageResult": { - "type": "object", - "description": "Search result representing a page in a space.", - "properties": { - "id": { - "type": "string" - }, - "title": { - "type": "string" - }, - "path": { - "type": "string" - }, - "sections": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SearchSectionResult" - } - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "app": { - "type": "string", - "description": "URL of the page in the application", - "format": "uri" + "responses": { + "201": { + "description": "Space created", + "headers": { + "Location": { + "description": "API URL for the newly created space", + "schema": { + "type": "string" + } } }, - "required": ["app"] - } - }, - "required": ["id", "title", "path", "urls"] - }, - "SearchSectionResult": { - "type": "object", - "description": "Search result representing a section in a page.", - "properties": { - "id": { - "type": "string" - }, - "title": { - "type": "string" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Space" + } + } + } }, - "path": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/spaces/gitsync": { + "get": { + "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": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "body": { - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "app": { - "type": "string", - "description": "URL of the section in the application", - "format": "uri" - } - }, - "required": ["app"] - } - }, - "required": ["id", "title", "path", "body", "urls"] - }, - "SearchAIQuery": { - "type": "object", - "properties": { - "query": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" }, - "previousQueries": { - "type": "array", - "deprecated": true, - "maxItems": 10, - "items": { - "type": "string" + { + "name": "status", + "in": "query", + "description": "If defined, only spaces with matching Git sync status are returned", + "schema": { + "$ref": "#/components/schemas/GitSyncOperationState" } } - }, - "required": ["query"] - }, - "SearchAIAnswer": { - "type": "object", - "description": "Answer from AI for a question asked on a content.", - "properties": { - "text": { - "deprecated": true, - "type": "string" - }, - "answer": { - "$ref": "#/components/schemas/Document" - }, - "followupQuestions": { - "type": "array", - "items": { - "type": "string" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SpaceWithGitSync" + } + } + } + } + ] + } + } } }, - "sources": { - "type": "array", - "description": "The sources used to generate the answer.", - "items": { - "$ref": "#/components/schemas/SearchAIAnswerSource" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/collections": { + "get": { + "operationId": "listCollectionsInOrganizationById", + "summary": "List organization collections", + "description": "Lists collections for the specified organization.\n", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "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"] + { + "$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 } } - }, - "required": ["text", "answer", "pages", "sources", "followupQuestions"] - }, - "SearchAIAnswerStream": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["answer"] + ], + "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" + } + } + } + } + ] + } + } + } }, - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type"] + } }, - "SearchAIAnswerSource": { - "allOf": [ + "post": { + "operationId": "createCollection", + "summary": "Create an organization collection", + "tags": ["collections"], + "security": [ { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["page", "entity", "capture"] - } - }, - "required": ["type"] - }, + "user": [] + } + ], + "parameters": [ { - "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"] - }, - { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", - "title": "Snippet", "properties": { - "type": { - "type": "string", - "enum": ["capture"] - }, - "captureId": { + "title": { "type": "string", - "description": "ID of the capture" + "maxLength": 50 }, - "source": { + "parent": { "type": "string", - "description": "Source of the capture" + "description": "ID of a parent collection" } - }, - "required": ["type", "captureId", "source"] + } } - ] - } - ] - }, - "SearchAIRecommendedQuestions": { - "type": "object", - "description": "Questions recommended by the AI for the given content.", - "properties": { - "questions": { - "type": "array", - "items": { - "type": "string" } } }, - "required": ["questions"] - }, - "SearchAIRecommendedQuestionStream": { - "type": "object", - "properties": { - "question": { - "type": "string" - } - }, - "required": ["question"] - }, - "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" - }, - "sectionHits": { - "description": "Number of sections matching this search.", - "type": "number" - } - } - }, - "AnalyticsTopSearches": { - "type": "object", - "description": "Top search queries for a content.", - "required": ["searches", "queries"], - "properties": { - "searches": { - "description": "Number of searches done by users.", - "type": "number" - }, - "queries": { - "description": "Top queries searched for this content.", - "type": "array", - "items": { - "$ref": "#/components/schemas/AnalyticsSearchQuery" - } - } - } - }, - "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" - }, - "views": { - "description": "Page views per interval (day, week, month).", - "type": "array", - "items": { - "type": "object", - "properties": { - "timestamp": { + "responses": { + "201": { + "description": "Collection created", + "headers": { + "Location": { + "description": "API URL for the newly created collection", + "schema": { "type": "string" - }, - "count": { - "type": "number" } - }, - "required": ["timestamp", "count"] - } - } - } - }, - "AnalyticsContentPages": { - "type": "object", - "required": ["pages"], - "properties": { - "pages": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AnalyticsContentPage" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collection" + } + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "AnalyticsContentPage": { - "type": "object", - "description": "Page entry in the content analytics.", - "required": ["page", "pageViews"], - "properties": { - "page": { - "$ref": "#/components/schemas/RevisionPageDocument" + } + }, + "/orgs/{organizationId}/custom-fields": { + "get": { + "operationId": "listOrganizationCustomFields", + "summary": "Get the custom fields for spaces in an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "pageViews": { - "type": "number" + { + "$ref": "#/components/parameters/listPage" }, - "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." + { + "$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/CustomField" + } + } + } + } + ] + } } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "Collection": { - "type": "object", - "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"collection\"", - "enum": ["collection"] - }, - "id": { - "type": "string", - "description": "Unique identifier for the collection" - }, - "title": { - "$ref": "#/components/schemas/CollectionTitle" - }, - "description": { - "$ref": "#/components/schemas/CollectionDescription" - }, - "path": { - "type": "string", - "description": "Path in the published URL" - }, - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" - }, - "publishingType": { - "type": "string", - "enum": ["variants"] - }, - "organization": { - "type": "string", - "description": "ID of the organization owning this collection" - }, - "parent": { - "type": "string", - "description": "ID of the parent collection, if any" - }, - "collection": { - "type": "string", - "deprecated": true, - "description": "ID of the parent collection, if any" - }, - "defaultLevel": { - "$ref": "#/components/schemas/DefaultLevel" - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the collection in the API", - "format": "uri" - }, - "app": { - "type": "string", - "description": "URL of the collection in the application", - "format": "uri" + "post": { + "operationId": "createOrganizationCustomField", + "summary": "Create a new custom field in an orgamization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$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"] } - }, - "required": ["app", "location"] + } } }, - "required": [ - "object", - "id", - "title", - "organization", - "visibility", - "urls", - "defaultLevel" - ] - }, - "CollectionTitle": { - "type": "string", - "description": "Title of the collection", - "minLength": 0, - "maxLength": 50 - }, - "CollectionDescription": { - "type": "string", - "description": "Description of the collection", - "minLength": 0, - "maxLength": 100 - }, - "Integration": { - "type": "object", - "properties": { - "object": { - "type": "string", - "enum": ["integration"] - }, - "name": { - "type": "string", - "description": "Unique named identifier for the integration" - }, - "version": { - "type": "number", - "description": "Version of the integration" - }, - "title": { - "$ref": "#/components/schemas/IntegrationTitle" - }, - "description": { - "$ref": "#/components/schemas/IntegrationDescription" + "responses": { + "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" + } + } + } }, - "summary": { - "$ref": "#/components/schemas/IntegrationSummary" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/custom-fields/{fieldName}": { + "get": { + "operationId": "getOrganizationCustomFieldByName", + "summary": "Get a custom field by its name", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "previewImages": { - "type": "array", - "description": "URLs of images to showcase the integration", - "maxItems": 3, - "items": { + { + "name": "fieldName", + "in": "path", + "required": true, + "description": "The name of the custom field", + "schema": { "type": "string" } - }, - "target": { - "$ref": "#/components/schemas/IntegrationTarget" - }, - "verified": { - "type": "boolean", - "description": "If true, the integration has been verified by the GitBook team" - }, - "visibility": { - "$ref": "#/components/schemas/IntegrationVisibility" - }, - "scopes": { - "$ref": "#/components/schemas/IntegrationScopes" - }, - "categories": { - "$ref": "#/components/schemas/IntegrationCategories" - }, - "blocks": { - "$ref": "#/components/schemas/IntegrationBlocks" - }, - "configurations": { - "$ref": "#/components/schemas/IntegrationConfigurations" - }, - "externalLinks": { - "$ref": "#/components/schemas/IntegrationExternalLinks" - }, - "owner": { - "$ref": "#/components/schemas/Organization" - }, - "urls": { - "type": "object", - "description": "URLs associated with the object", - "properties": { - "location": { - "type": "string", - "description": "URL of the integration in the API", - "format": "uri" - }, - "icon": { - "type": "string", - "description": "URL of the icon associated to the integration", - "format": "uri" - }, - "app": { - "type": "string", - "description": "URL of the integration in the application", - "format": "uri" - }, - "assets": { - "type": "string", - "description": "URL of the integration's assets.", - "format": "uri" - }, - "publicEndpoint": { - "type": "string", - "description": "Public HTTP endpoint for the integration", - "format": "uri" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomField" + } } - }, - "required": ["location", "app", "assets", "publicEndpoint"] + } }, - "permissions": { - "type": "object", - "description": "The set of permissions for the integration", - "properties": { - "admin": { - "type": "boolean" - } - }, - "required": ["admin"] + "404": { + "description": "No matching custom field found", + "$ref": "#/components/responses/NotFoundError" }, - "contentSecurityPolicy": { - "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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", - "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" - ] - }, - "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": [ + "patch": { + "operationId": "updateOrganizationCustomField", + "summary": "Update a custom field in an organization", + "tags": ["organizations"], + "security": [ { - "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" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "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" + } + } } - }, - "required": ["codeblock", "body"] + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomField" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "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." + "delete": { + "operationId": "deleteOrganizationCustomField", + "summary": "Delete a custom field in an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "title": { - "type": "string", - "description": "Short descriptive title for the block.", - "minLength": 2, - "maxLength": 40 + { + "name": "fieldName", + "in": "path", + "required": true, + "description": "The name of the custom field", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Custom field has been deleted" }, - "description": { - "type": "string", - "description": "Long descriptive text for the block.", - "minLength": 0, - "maxLength": 150 + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/integrations": { + "get": { + "operationId": "listOrganizationIntegrations", + "summary": "List integrations owned by an organization", + "tags": ["spaces"], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "icon": { - "type": "string", - "description": "URL of the icon to represent this block." + { + "$ref": "#/components/parameters/listPage" }, - "urlUnfurl": { - "type": "array", - "description": "URLs patterns to convert as this block.", - "items": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/integrationSearchQuery" + } + ], + "responses": { + "200": { + "description": "List of integrations.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + ] + } + } } }, - "markdown": { - "$ref": "#/components/schemas/IntegrationBlockMarkdown" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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" + } + } + }, + "/orgs/{organizationId}/integrations/{integrationName}/installation_status": { + "get": { + "operationId": "getOrganizationIntegrationStatus", + "summary": "Get the status of an integration installation in an organization", + "tags": ["integrations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/integrationName" + } + ], + "responses": { + "200": { + "description": "Integration installation status", + "content": { + "application/json": { + "schema": { + "properties": { + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + } + }, + "required": ["status"] + } + } } }, - "required": ["url", "label"] + "404": { + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "IntegrationEvent": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique ID of the event." + } + }, + "/orgs/{organizationId}/installations": { + "get": { + "operationId": "listOrganizationInstallations", + "summary": "List installations of integrations in an organization.", + "tags": ["spaces"], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "integrationId": { - "type": "string", - "description": "Unique ID of the integration." + { + "$ref": "#/components/parameters/listPage" }, - "installationId": { - "type": "string", - "description": "Unique ID of the integration installation." + { + "$ref": "#/components/parameters/listLimit" + }, + { + "$ref": "#/components/parameters/integrationSearchQuery" + } + ], + "responses": { + "200": { + "description": "List of integrations with the associated installations.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "installation": { + "$ref": "#/components/schemas/IntegrationInstallation" + }, + "integration": { + "$ref": "#/components/schemas/Integration" + } + }, + "required": ["integration", "installation"] + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/integrations/installations-status": { + "get": { + "operationId": "listOrganizationIntegrationsStatus", + "summary": "List the statuses of all integrations installed in an organization", + "tags": ["integrations"], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + { + "$ref": "#/components/parameters/listPage" }, - "payload": { - "$ref": "#/components/schemas/Event" + { + "$ref": "#/components/parameters/listLimit" }, - "status": { - "type": "string", - "description": "Status of the event.", - "enum": ["success", "failed"] + { + "$ref": "#/components/parameters/integrationSearchQuery" } - }, - "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" + ], + "responses": { + "200": { + "description": "List of integrations.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "required": ["status", "integration"], + "properties": { + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + }, + "integration": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + } + } + ] + } + } + } }, - "level": { - "description": "The level of the log entry.", - "type": "string", - "enum": ["debug", "info", "warn", "error"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "IntegrationEventTrace": { - "type": "object", - "required": ["logs"], - "properties": { - "logs": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationEventLog" + } + }, + "/orgs/{organizationId}/experiments": { + "get": { + "operationId": "listOrgExperimentalFeatures", + "summary": "List experiemental features for the given organization.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationExperimentalFeature" + } + } + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } }, - "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" + "post": { + "operationId": "updateOrgExperimentalFeatures", + "summary": "Toggle on or off experimental features.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "boolean" + } + } + } + } + }, + "responses": { + "204": { + "description": "OK" }, - "space": { - "$ref": "#/components/schemas/IntegrationConfiguration" + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "IntegrationConfiguration": { - "oneOf": [ + } + }, + "/orgs/{organizationId}/saml": { + "get": { + "operationId": "listSAMLProvidersInOrganizationById", + "summary": "List organization SAML providers", + "description": "Lists SAML providers configured for the specified organization.\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/IntegrationConfigurationSchema" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/IntegrationConfigurationComponent" + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" } - ] - }, - "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"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" }, { "type": "object", + "required": ["items"], "properties": { - "type": { - "type": "string", - "enum": ["button"] - }, - "callback_url": { - "type": "string" - }, - "button_text": { - "type": "string" + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationSAMLProvider" + } } - }, - "required": ["type", "callback_url", "button_text"] + } } ] } - ] + } } }, - "required": { - "type": "array", - "uniqueItems": true, - "items": { - "type": "string" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["properties"] + } }, - "IntegrationConfigurationComponent": { - "type": "object", - "description": "ContentKit component for configuration", - "properties": { - "componentId": { - "type": "string", - "description": "ID of the ContentKit component defined in the integration" + "post": { + "operationId": "createOrganizationSAMLProvider", + "summary": "Create a new SAML provider in an orgamization", + "tags": ["organizations"], + "security": [ + { + "user": [] } - }, - "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" + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "label": { + "$ref": "#/components/schemas/SAMLProviderLabel" + }, + "entityID": { + "$ref": "#/components/schemas/SAMLProviderEntityID" + }, + "certificate": { + "$ref": "#/components/schemas/SAMLProviderCertificate" + }, + "ssoURL": { + "$ref": "#/components/schemas/URL" + }, + "defaultTeam": { + "type": "string" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + } + }, + "required": ["label"] } - }, - "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" + "responses": { + "201": { + "description": "SAML Provider created", + "headers": { + "Location": { + "description": "API URL for the newly created SAML Provider", + "schema": { + "type": "string" + } } }, - "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" + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSAMLProvider" + } + } + } }, - "site": { - "description": "ID of the site the integration is installed on.", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/saml/{samlProviderId}": { + "get": { + "operationId": "getOrganizationSAMLProviderById", + "summary": "Get a SAML provider in an organization by its ID", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" + { + "$ref": "#/components/parameters/samlProviderId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSAMLProvider" + } + } + } }, - "configuration": { - "description": "Configuration of the integration for this site", - "type": "object" + "404": { + "description": "No matching provider found", + "$ref": "#/components/responses/NotFoundError" }, - "externalIds": { - "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "updateOrganizationSAMLProvider", + "summary": "Update a SAML provider in an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "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" + { + "$ref": "#/components/parameters/samlProviderId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "label": { + "$ref": "#/components/schemas/SAMLProviderLabel" + }, + "entityID": { + "$ref": "#/components/schemas/SAMLProviderEntityID" + }, + "certificate": { + "$ref": "#/components/schemas/SAMLProviderCertificate" + }, + "ssoURL": { + "$ref": "#/components/schemas/URL" + }, + "defaultTeam": { + "type": "string" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + } + } } - }, - "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" + "responses": { + "200": { + "description": "SAML provider has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationSAMLProvider" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } }, - "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" + "delete": { + "operationId": "deleteOrganizationSAMLProvider", + "summary": "Delete a SAML provider in an organization", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "signingSecret": { - "type": "string", - "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the integration.", - "deprecated": true + { + "$ref": "#/components/parameters/samlProviderId" + } + ], + "responses": { + "204": { + "description": "SAML provider has been deleted" }, - "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." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/usage": { + "get": { + "operationId": "getUsageForOrganizationById", + "summary": "Get all usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationUsage" + } } - }, - "required": ["integration"] + } }, - "apiEndpoint": { - "type": "string", - "description": "URL of the HTTP API" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/usage/collections": { + "get": { + "operationId": "getCollectionsUsageForOrganizationById", + "summary": "Get collections usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "collections": { + "$ref": "#/components/schemas/OrganizationUsageCollections" + } + }, + "required": ["collections"] + } + } + } }, - "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." + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/usage/spaces": { + "get": { + "operationId": "getSpacesUsageForOrganizationById", + "summary": "Get spaces usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "spaces": { + "$ref": "#/components/schemas/OrganizationUsageSpaces" + } + }, + "required": ["spaces"] + } } - }, - "required": ["integration"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["apiEndpoint", "apiTokens", "integration", "signingSecrets", "secrets"] - }, - "IntegrationTarget": { - "type": "string", - "enum": ["organization", "all"] - }, - "IntegrationInstallationTarget": { - "oneOf": [ + } + } + }, + "/orgs/{organizationId}/usage/sites": { + "get": { + "operationId": "getSitesUsageForOrganizationById", + "summary": "Get sites usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ { - "$ref": "#/components/schemas/OrganizationTarget" + "user-internal": [] } - ] - }, - "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": [ + ], + "parameters": [ { - "type": "string" + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "sites": { + "$ref": "#/components/schemas/OrganizationUsageSites" + } + }, + "required": ["sites"] + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/usage/teams": { + "get": { + "operationId": "getTeamsUsageForOrganizationById", + "summary": "Get teams usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ { - "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" + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "teams": { + "$ref": "#/components/schemas/OrganizationUsageTeams" + } + }, + "required": ["teams"] + } } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "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" + } + } + }, + "/orgs/{organizationId}/usage/members": { + "get": { + "operationId": "getMembersUsageForOrganizationById", + "summary": "Get members usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "members": { + "$ref": "#/components/schemas/OrganizationUsageMembers" + } + }, + "required": ["members"] + } } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "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." + } + }, + "/orgs/{organizationId}/usage/team-members": { + "get": { + "operationId": "getTeamMembersUsageForOrganizationById", + "summary": "Get team members usage metrics for an organization", + "tags": ["organizations", "usage"], + "security": [ + { + "user-internal": [] } - }, - "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" - }, - { + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "entityId": { - "type": "string" + "teamMembers": { + "$ref": "#/components/schemas/OrganizationUsageTeamMembers" } }, - "required": ["entityId"] + "required": ["teamMembers"] } - ] + } } - } - }, - "required": ["entityId", "properties"] - }, - "Entity": { - "allOf": [ - { - "$ref": "#/components/schemas/UpsertEntity" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/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": [ { - "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"] + "user": [] } - ] - }, - "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"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "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" + "$ref": "#/components/parameters/documentFormat" }, { - "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": [ + "$ref": "#/components/parameters/listPage" + }, { - "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"] + "$ref": "#/components/parameters/listLimit" }, { - "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": { + "name": "context", + "in": "query", + "description": "The context in which the item was captured", + "schema": { + "type": "string", + "enum": ["walkthrough", "thread"] + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { "type": "object", + "required": ["items"], "properties": { - "label": { - "type": "string" - }, - "value": { - "type": "string" + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Capture" + } } - }, - "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"] - }, - { + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "post": { + "operationId": "startCapture", + "summary": "Start a capture", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", - "description": "reference to another entity, creating a relation", "properties": { - "type": { + "title": { + "$ref": "#/components/schemas/CaptureTitle" + }, + "context": { + "$ref": "#/components/schemas/CaptureContext" + }, + "externalId": { "type": "string", - "enum": ["relation"] + "description": "ID in the original source of the capture." }, - "entity": { - "type": "object", - "properties": { - "type": { - "$ref": "#/components/schemas/EntityType" - } - }, - "required": ["type"] + "externalURL": { + "type": "string", + "format": "uri", + "description": "URL of the original source of the capture." } }, - "required": ["type", "entity"] + "required": ["context"] } - ] + } } - ] - }, - "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" + }, + "responses": { + "201": { + "description": "Capture started", + "headers": { + "Location": { + "description": "API URL for the newly created capture", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Capture" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/captures/{captureId}": { + "get": { + "operationId": "getCapture", + "deprecated": true, + "summary": "Get a capture by its ID. Deprecated, use getSnippet instead.", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/FetchEvent" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/FetchPublishedScriptEvent" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/FetchVisitorAuthenticationEvent" + "$ref": "#/components/parameters/captureId" }, { - "$ref": "#/components/schemas/UIRenderEvent" + "$ref": "#/components/parameters/documentFormat" } ], - "discriminator": { - "propertyName": "type" - } - }, - "BaseEvent": { - "description": "Common properties for all events.", - "type": "object", - "properties": { - "eventId": { - "description": "Unique identifier for the event.", - "type": "string" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Capture" + } + } + } }, - "type": { - "description": "Type of the event.", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["eventId", "type"] - }, - "InstallationEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseEvent" - }, + } + } + }, + "/orgs/{organizationId}/captures/{captureId}/events": { + "post": { + "operationId": "addEventsToCapture", + "summary": "Add events to a running capture", + "tags": ["organizations"], + "security": [ { - "type": "object", - "description": "Common properties for all events related to an installation", - "properties": { - "installationId": { - "type": "string", - "description": "ID of the integration installation" - } - }, - "required": ["installationId"] + "user": [] } - ] - }, - "SpaceEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/InstallationEvent" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "description": "Common properties for all events related to a specific space.", - "properties": { - "spaceId": { - "type": "string", - "description": "ID of the space" - } - }, - "required": ["spaceId"] + "$ref": "#/components/parameters/captureId" } - ] - }, - "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": { + ], + "requestBody": { + "content": { + "application/json": { + "schema": { "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." + "events": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CaptureEvent" + } } }, - "required": ["status"] + "required": ["events"] } - }, - "required": ["type", "status"] + } } - ] - }, - "SpaceInstallationSetupEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + }, + "responses": { + "204": { + "description": "Events added" }, - { - "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"] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/captures/{captureId}/stop": { + "post": { + "operationId": "stopCapture", + "summary": "Stop a capture", + "tags": ["organizations"], + "security": [ + { + "user": [] } - ] - }, - "SpaceInstallationDeletedEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "description": "Event received when integration has been uninstalled from a space.", - "properties": { - "type": { - "type": "string", - "enum": ["space_installation_deleted"] - }, - "previous": { + "$ref": "#/components/parameters/captureId" + }, + { + "$ref": "#/components/parameters/documentFormat" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { "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." - } + "properties": {} + } + } + } + }, + "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"] } } - }, - "required": ["type", "previous"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "SpaceViewEvent": { - "allOf": [ + } + } + }, + "/orgs/{organizationId}/snippets": { + "get": { + "operationId": "listSnippets", + "summary": "Lists snippets.", + "description": "List snippets in an organization, newest first.\n", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/SpaceEvent" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "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" + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "source", + "in": "query", + "description": "If specified, only snippets from the specified source will be returned.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Snippet" + } + } + } } - }, - "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"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "SpaceContentUpdatedEvent": { - "allOf": [ + "post": { + "operationId": "createSnippet", + "summary": "Create a new snippet", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/SpaceEvent" - }, + "user": [] + } + ], + "parameters": [ { - "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" + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" } - }, - "required": ["type", "revisionId"] + } } - ] - }, - "SpaceVisibilityUpdatedEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + }, + "responses": { + "201": { + "description": "Snippet created", + "headers": { + "Location": { + "description": "API URL for the newly created snippet", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Snippet" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/snippets/{snippetId}": { + "get": { + "operationId": "getSnippet", + "summary": "Get a snippet by its ID", + "tags": ["organizations"], + "security": [ { - "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"] + "user": [] } - ] - }, - "SpaceGitSyncCompletedEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/parameters/organizationId" }, { - "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)" + "$ref": "#/components/parameters/snippetId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Snippet" + } } - }, - "required": ["type", "state", "revisionId", "commitId"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "SpaceGitSyncStartedEvent": { - "allOf": [ + "delete": { + "operationId": "deleteSnippet", + "summary": "Delete a snippet by its ID.", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/SpaceEvent" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "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"] + "$ref": "#/components/parameters/snippetId" } - ] - }, - "FetchRequest": { - "type": "object", - "properties": { - "method": { - "type": "string", - "enum": ["post", "get", "put", "delete"] - }, - "url": { - "type": "string" + ], + "responses": { + "200": { + "description": "OK" }, - "headers": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["method", "url", "headers"] + } }, - "FetchEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/BaseEvent" - }, + "put": { + "operationId": "updateSnippet", + "summary": "Update an existing snippet.", + "tags": ["organizations"], + "security": [ { - "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"] + "user": [] } - ] - }, - "FetchPublishedScriptEvent": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/SpaceEvent" + "$ref": "#/components/parameters/organizationId" }, { - "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"] + "$ref": "#/components/parameters/snippetId" + }, + { + "$ref": "#/components/parameters/ifUnmodifiedSince" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSnippetSchema" } - }, - "required": ["type"] + } } - ] - }, - "FetchVisitorAuthenticationEvent": { - "allOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Snippet" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/snippets/{snippetId}/move": { + "post": { + "operationId": "moveSnippet", + "summary": "Move a snippet into a destination. The snippet will be archived in the process.", + "tags": ["organizations"], + "security": [ { - "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"] + "user": [] } - ] - }, - "UIRenderEvent": { - "allOf": [ + ], + "parameters": [ { - "oneOf": [ - { - "$ref": "#/components/schemas/SpaceEvent" - }, - { - "$ref": "#/components/schemas/InstallationEvent" - } - ] + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "description": "Event generated when rendering a UI", - "properties": { - "auth": { + "$ref": "#/components/parameters/snippetId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "type": "object", + "required": ["target"], "properties": { - "userId": { - "type": "string", - "description": "The user's ID." + "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"] } - }, - "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" + "responses": { + "200": { + "description": "The snippet was successfully moved.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["page"], + "properties": { + "page": { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + "changeRequest": { + "$ref": "#/components/schemas/ChangeRequest" + } + } + } } - }, - "required": ["result", "sessionId"] + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "get": { + "operationId": "getSnippetSuggestedLocations", + "summary": "Return possible snippet locations in an organization based on the current user.", + "tags": ["organizations"], + "security": [ { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": ["preview"] - }, - "invoice": { - "$ref": "#/components/schemas/BillingInvoicePreview" - } - }, - "required": ["result", "invoice"] + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": ["upgraded"] - } - }, - "required": ["result"] + "$ref": "#/components/parameters/snippetId" }, { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": ["downgraded"] - } - }, - "required": ["result"] - } - ] - }, - "BillingInvoicePreview": { - "type": "object", - "properties": { - "amount": { - "description": "Amount of the invoice", - "type": "number" + "$ref": "#/components/parameters/listPage" }, - "amountDueToday": { - "description": "Amount that will be immediately charged.", - "type": "number" + { + "$ref": "#/components/parameters/listLimit" }, - "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" + { + "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" + } }, - "remainingCustomerBalance": { - "description": "Current balance after potential upgrade.", - "type": "number" + { + "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" + } }, - "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" + { + "name": "search", + "in": "query", + "description": "If specified, only locations matching the search query will be returned.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A paginated list of suggested snippet locations.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "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" + } + ] + } + } + } + } + } + } + ] } - }, - "required": ["amount", "description", "periodStart", "periodEnd"] + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": [ - "amount", - "amountDueToday", - "customerBalance", - "remainingCustomerBalance", - "lines" - ] - }, - "APIIntegrationScope": { - "type": "string", - "enum": [ - "integration:read", - "integration:update", - "integration:installation:read", - "integration:installation:update" - ] - }, - "APIScope": { - "anyOf": [ + } + } + }, + "/orgs/{organizationId}/synced-blocks": { + "get": { + "operationId": "listSyncedBlocks", + "summary": "List all the synced blocks created in an organization", + "tags": ["organizations"], + "security": [ { - "$ref": "#/components/schemas/IntegrationScope" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$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" + "$ref": "#/components/parameters/listPage" }, - "expiresOn": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" }, - "issuedOn": { - "type": "string" + { + "name": "ids", + "in": "query", + "description": "A list of IDs to filter the synced blocks.", + "required": false, + "schema": { + "type": "array", + "items": { + "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" + ], + "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/SyncedBlock" + } + } + } + } + ] + } + } } }, - "validationErrors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CloudflareHostnameTLSValidationError" - } + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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" + "post": { + "operationId": "createSyncedBlock", + "summary": "Create a new synced block", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["content"], + "properties": { + "title": { + "type": "string", + "description": "Title of synced block" + }, + "content": { + "description": "The content of the synced block. For now, only JSON documents are supported.", + "$ref": "#/components/schemas/Document" + } + } + } + } } }, - "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" + "responses": { + "201": { + "description": "Synced block created", + "headers": { + "Location": { + "description": "API URL for the newly created synced block", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SyncedBlock" + } + } + } }, - "status": { - "$ref": "#/components/schemas/CloudflareHostnameStatus" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/synced-blocks/{syncedBlockId}": { + "get": { + "operationId": "getSyncedBlock", + "summary": "Get a synced block by its ID", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "createdAt": { - "type": "string" + { + "$ref": "#/components/parameters/syncedBlockId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SyncedBlock" + } + } + } }, - "ssl": { - "$ref": "#/components/schemas/CloudflareHostnameTLSInfo" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "put": { + "operationId": "updateSyncedBlock", + "summary": "Update an existing synced block.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "verificationErrors": { - "type": "array", - "items": { - "type": "string" + { + "$ref": "#/components/parameters/syncedBlockId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "A new title for the Synced Block." + } + } + } } } }, - "required": ["hostname", "status", "createdAt", "verificationErrors"] - }, - "FirebaseUserInfo": { - "type": "object", - "description": "The User Firebase Auth Info.", - "properties": { - "uid": { - "type": "string" + "responses": { + "200": { + "description": "OK" }, - "displayName": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/synced-blocks/{syncedBlockId}/content": { + "get": { + "operationId": "getSyncedBlockContent", + "summary": "Get a synced block content", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "email": { - "type": "string" + { + "$ref": "#/components/parameters/syncedBlockId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/JSONDocument" + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionFile" + } + } + }, + "required": ["document", "files"] + } + } + } }, - "phoneNumber": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/synced-blocks/{syncedBlockId}/backlinks": { + "get": { + "operationId": "listSyncedBlockBacklinks", + "summary": "Get a list of pages that reference this synced block.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "photoUrl": { - "type": "string" + { + "$ref": "#/components/parameters/syncedBlockId" }, - "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" + { + "$ref": "#/components/parameters/listPage" }, - "searchKey": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" } - }, - "required": ["id", "searchKey"] - }, - "UserBackOfficeInfo": { - "type": "object", - "description": "The GitBook User info shown in the BackOffice.", - "properties": { - "id": { - "type": "string" + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocationPage" + } + } + } + } + ] + } + } + } }, - "riskEvaluation": { - "$ref": "#/components/schemas/UserRiskEvaluation" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/synced-blocks/{syncedBlockId}/usage/spaces": { + "get": { + "operationId": "listSyncedBlockSpaces", + "summary": "Get a list of spaces that reference this synced block.", + "tags": ["organizations"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "authProviders": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FirebaseUserInfo" - } + { + "$ref": "#/components/parameters/syncedBlockId" }, - "createdAt": { - "type": "string" + { + "$ref": "#/components/parameters/listPage" }, - "lastSignInAt": { - "type": "string" + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Space" + } + } + } + } + ] + } + } + } }, - "disabled": { - "type": "boolean" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": [ - "id", - "riskEvaluation", - "authProviders", - "createdAt", - "lastSignInAt", - "disabled" - ] - }, - "UserImpersonation": { - "type": "object", - "description": "The info returned when impersonating a GitBook User.", - "allOf": [ + } + } + }, + "/orgs/{organizationId}/ask": { + "post": { + "operationId": "askInOrganization", + "summary": "Ask a question.", + "security": [ + { + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/UserBackOfficeInfo" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "impersonation": { - "$ref": "#/components/schemas/UserImpersonationInfo" - } - }, - "required": ["impersonation"] - } - ] - }, - "UserImpersonationInfo": { - "type": "object", - "description": "The GitBook User impersonation info.", - "properties": { - "authURL": { - "type": "string" + "$ref": "#/components/parameters/documentFormat" }, - "impersonatorId": { - "type": "string" + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIQuery" + } + } } }, - "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": { + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { "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" + "properties": { + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" + } + } } - }, - "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" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/ask/questions": { + "get": { + "operationId": "getRecommendedQuestionsInOrganization", + "summary": "Get a list of questions recommended to be asked in an organization.", + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + } + ], + "security": [ + { + "user": [] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestions" } - }, - "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" + "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/organizationId" + } + ], + "security": [ + { + "user": [] + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" } - }, - "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" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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" - } + } + } + }, + "/orgs/{organizationId}/ask/stream": { + "get": { + "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": [] } - }, - "required": ["contents"] - }, - "UnsplashImage": { - "type": "object", - "required": ["kind", "id", "description", "downloadLocation", "urls", "author"], - "properties": { - "kind": { - "type": "string", - "enum": ["unsplash_image"] - }, - "id": { - "type": "string" + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "description": { - "type": "string" + { + "name": "query", + "in": "query", + "required": true, + "schema": { + "type": "string" + } }, - "downloadLocation": { - "type": "string" + { + "$ref": "#/components/parameters/documentFormat" }, - "urls": { - "type": "object", - "properties": { - "full": { - "type": "string" - }, - "small": { - "type": "string" + { + "name": "details", + "in": "query", + "description": "Return query details in the result", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/SearchAIAnswerStream" + } } - }, - "required": ["full", "small"] + } }, - "author": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "required": ["name", "url"] + "default": { + "$ref": "#/components/responses/UnexpectedError" } } - }, - "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"] + } + }, + "/orgs/{organizationId}/sites": { + "get": { + "operationId": "listSites", + "summary": "List all the sites created in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] } - }, - "required": ["theme"] - }, - "ContentKitContext": { - "description": "Object representing the context in which a ContentKit component is rendered.", - "oneOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentKitContextConfigurationAccount" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitContextConfigurationSpace" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/ContentKitContextDocument" + "$ref": "#/components/parameters/listLimit" + }, + { + "name": "space", + "in": "query", + "description": "Identifier of the space to filter the sites by", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "title", + "in": "query", + "description": "Filter sites by their title", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "published", + "in": "query", + "description": "Filter sites by their published status", + "required": false, + "schema": { + "type": "boolean" + } } - ] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Site" + } + } + } + } + ] + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } }, - "ContentKitContextConfigurationAccount": { - "allOf": [ + "post": { + "operationId": "createSite", + "summary": "Create a site in an organization", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitContextBase" - }, + "user": [] + } + ], + "parameters": [ { - "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." + "$ref": "#/components/parameters/organizationId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of the site, defaults to Basic", + "$ref": "#/components/schemas/SiteType" + }, + "title": { + "$ref": "#/components/schemas/SiteTitle" + }, + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "spaces": { + "oneOf": [ + { + "type": "array", + "description": "ID of spaces to be added to the site", + "items": { + "type": "string" + } + }, + { + "type": "string", + "description": "Create a new space associated to the site", + "enum": ["sample", "empty"] + } + ] + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Site created", + "headers": { + "Location": { + "description": "API URL for the newly created site", + "schema": { + "type": "string" + } } }, - "required": ["type", "organizationId"] + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Site" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] - }, - "ContentKitContextConfigurationSpace": { - "allOf": [ + } + } + }, + "/orgs/{organizationId}/sites/publishing/checkout": { + "get": { + "operationId": "previewSitePublishCheckout", + "summary": "Preview checkout information upon publishing a site in the organization.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitContextBase" + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "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." + "in": "query", + "name": "plan", + "description": "The plan of the site to preview the checkout information for.", + "required": true, + "schema": { + "$ref": "#/components/schemas/SiteType" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingOperationPreviewResponse" + } } - }, - "required": ["type", "spaceId"] + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}": { + "get": { + "operationId": "getSiteById", + "summary": "Get an organization site by its ID", + "tags": ["sites"], + "security": [ + { + "user": [] } - ] - }, - "ContentKitContextDocument": { - "allOf": [ + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentKitContextBase" + "$ref": "#/components/parameters/organizationId" }, { - "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" + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Site" + } } - }, - "required": ["type", "spaceId", "editable"] + } + }, + "404": { + "description": "No matching site found", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "ContentKitDynamicBinding": { - "type": "object", - "description": "Binding between a property and a state value.", - "properties": { - "$state": { - "type": "string", - "description": "Key in the state" + "patch": { + "operationId": "updateSiteById", + "summary": "Update a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] } - }, - "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" - } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "controls": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitBlockControl" - }, - { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitBlockControl" + { + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/SiteTitle" + }, + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "basename": { + "$ref": "#/components/schemas/SiteBasename" + }, + "defaultSiteSpace": { + "type": "string", + "description": "ID of the site-space to be used as the default" } } - ] + } } } }, - "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" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Site" + } + } + } }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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" + "delete": { + "operationId": "deleteSiteById", + "summary": "Delete a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] } - }, - "required": ["type", "onPress"] - }, - "ContentKitTextInput": { - "type": "object", - "description": "Text input to prompt the user.", - "properties": { - "type": { - "type": "string", - "enum": ["textinput"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "disabled": { - "type": "boolean" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "205": { + "description": "Site has been deleted" }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/publish": { + "post": { + "operationId": "publishSite", + "summary": "Publishes the site to the audience defined in the site's visibility setting.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "initialValue": { - "description": "Text value to initialize the input with.", - "type": "string" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "Site published successfully", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/Site" + }, + { + "type": "object", + "description": "User needs to checkout in order to publish the site.", + "properties": { + "type": { + "type": "string", + "enum": ["checkout"] + }, + "sessionId": { + "type": "string", + "description": "Stripe payment session ID" + } + }, + "required": ["type", "sessionId"] + } + ] + } + } + } }, - "placeholder": { - "description": "Text that appears in the form control when it has no value set", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/unpublish": { + "post": { + "operationId": "unpublishSite", + "summary": "Unpublishes the site.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "multiline": { - "type": "boolean" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "Site unpublished successfully", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Site" + } + } + } }, - "inputType": { - "type": "string", - "enum": ["text", "password"], - "default": "text" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "state"] - }, - "ContentKitText": { - "type": "object", - "description": "Low level text element.", - "properties": { - "type": { - "type": "string", - "enum": ["text"] + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/share-links": { + "get": { + "operationId": "listSiteShareLinks", + "summary": "List all the share links created in a site", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "style": { - "type": "string", - "enum": ["bold", "italic", "code", "strikethrough"] + { + "$ref": "#/components/parameters/siteId" }, - "children": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "oneOf": [ - { - "type": "string" - }, + { + "$ref": "#/components/parameters/listPage" + }, + { + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ { - "$ref": "#/components/schemas/ContentKitText" + "$ref": "#/components/schemas/List" }, { - "$ref": "#/components/schemas/ContentKitLink" + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ShareLink" + } + } + } } ] } } - ] - } - }, - "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" } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "children"] + } }, - "ContentKitHint": { - "type": "object", - "description": "Element used to contextualize other elements or info.", - "properties": { - "type": { - "type": "string", - "enum": ["hint"] + "post": { + "operationId": "createSiteShareLink", + "summary": "Create a share link in a site", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" + { + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + }, + "required": ["name"] + } } } }, - "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" + "responses": { + "201": { + "description": "The share link has been created", + "headers": { + "Location": { + "description": "API URL for the newly created share link", + "schema": { + "type": "string" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" + } + } } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "children"] - }, - "ContentKitVStack": { - "type": "object", - "description": "Vertical stack of boxes.", - "properties": { - "type": { - "type": "string", - "enum": ["vstack"] + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}": { + "patch": { + "operationId": "updateSiteShareLinkById", + "summary": "Update the details of a site share link", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "align": { - "type": "string", - "default": "start", - "enum": ["start", "center", "end"] + { + "$ref": "#/components/parameters/siteId" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" + { + "$ref": "#/components/parameters/shareLinkId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "minProperties": 1, + "properties": { + "active": { + "type": "boolean" + }, + "name": { + "$ref": "#/components/schemas/ShareLinkName" + } + } + } } } }, - "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" + "responses": { + "200": { + "description": "The site share link has been updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShareLink" + } } - }, - "additionalProperties": true, - "required": ["action"] + } }, - { - "$ref": "#/components/schemas/ContentKitDefaultAction" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ] + } }, - "ContentKitDefaultAction": { - "oneOf": [ + "delete": { + "operationId": "deleteSiteShareLinkById", + "summary": "Deletes a site share link", + "tags": ["sites"], + "security": [ { - "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"] - }, + "user": [] + } + ], + "parameters": [ { - "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"] + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "description": "Action to open an url.", - "properties": { - "action": { - "type": "string", - "enum": ["@ui.url.open"] - }, - "url": { - "type": "string" - } - }, - "required": ["action", "url"] + "$ref": "#/components/parameters/siteId" }, { - "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"] + "$ref": "#/components/parameters/shareLinkId" + } + ], + "responses": { + "205": { + "description": "Site share link has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/plan": { + "post": { + "operationId": "updateSitePlan", + "summary": "Update the site plan.", + "tags": ["sites"], + "security": [ { - "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"] + "user-internal": [] } - ] - }, - "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"] + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "title": { - "type": "string" + { + "$ref": "#/components/parameters/siteId" }, - "subtitle": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" + { + "in": "query", + "name": "successReturnURL", + "description": "The app screen URL to bring the user back to after a succesfull checkout.", + "schema": { + "type": "string" } }, - "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" + { + "in": "query", + "name": "cancelReturnURL", + "description": "The app screen URL to bring the user back to after a canceled checkout.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "plan": { + "$ref": "#/components/schemas/SiteType" + }, + "interval": { + "description": "Desired interval for new subscriptions. Defaults to the existing billing interval.", + "$ref": "#/components/schemas/BillingInterval" + } + }, + "required": ["plan"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "type": "object", + "required": ["type", "sessionId"], + "properties": { + "type": { + "description": "User must checkout to complete the update.", + "type": "string", + "enum": ["checkout"] + }, + "sessionId": { + "type": "string", + "description": "Stripe payment session ID" + } + } + }, + { + "type": "object", + "required": ["type", "sessionId"], + "properties": { + "type": { + "description": "User needs to go through the legacy update flow.", + "type": "string", + "enum": ["legacy-checkout"] + }, + "sessionId": { + "type": "string", + "description": "Stripe payment session ID" + } + } + }, + { + "type": "object", + "required": ["type"], + "properties": { + "type": { + "description": "The site plan was successfully updated.", + "type": "string", + "enum": ["success"] + } + } + } + ] + } + } } }, - "submit": { - "$ref": "#/components/schemas/ContentKitButton" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "children"] + } }, - "ContentKitWebFrame": { - "type": "object", - "description": "Frame for a webpage", - "properties": { - "type": { - "type": "string", - "enum": ["webframe"] + "get": { + "operationId": "previewSitePlanUpdate", + "summary": "Preview an upgrade to a site plan, returning checkout information.", + "tags": ["sites"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "aspectRatio": { - "type": "number", - "description": "Ratio between width and height. Used to size the webframe." + { + "$ref": "#/components/parameters/siteId" }, - "source": { - "type": "object", - "description": "Content to load in the frame.", - "properties": { - "url": { - "type": "string" + { + "name": "plan", + "in": "query", + "required": true, + "description": "The desired site plan", + "schema": { + "$ref": "#/components/schemas/SiteType" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingOperationPreviewResponse" + } } - }, - "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" + "404": { + "description": "No matching site found", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/publishing/auth": { + "get": { + "operationId": "getSitePublishingAuthById", + "summary": "Get the publishing authentication settings for a site.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SitePublishingAuth" } - ] + } } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "source"] + } }, - "ContentKitCodeBlock": { - "type": "object", - "description": "Code block with syntax highlighting", - "properties": { - "type": { - "type": "string", - "enum": ["codeblock"] + "patch": { + "operationId": "updateSitePublishingAuthById", + "summary": "Update the publishing authentication settings for a site.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, + { + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": true, "content": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitDynamicBinding" - }, - { - "type": "string", - "description": "Code content to display" + "application/json": { + "schema": { + "$ref": "#/components/schemas/SitePublishingAuthUpdate" } - ] + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SitePublishingAuth" + } + } + } }, - "syntax": { - "description": "Syntax to use for highlighting (ex: javascript, python)", - "type": "string" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "lineNumbers": { - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "number", - "description": "Line number to start at." - } - ] + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate": { + "post": { + "operationId": "regenerateSitePublishingAuthById", + "summary": "Regenerate the publishing authentication settings for a site. This will re-generate the private key.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "buttons": { - "type": "array", - "description": "Controls button shown as an overlay in a corner of the code block.", - "items": { - "$ref": "#/components/schemas/ContentKitButton" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SitePublishingAuth" + } + } } }, - "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" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "onContentChange": { - "$ref": "#/components/schemas/ContentKitAction" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/publishing/preview": { + "get": { + "operationId": "getSitePublishingPreviewById", + "summary": "Get a URL to preview the published content of a site. The URL will be valid for 1 hour.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "header": { - "type": "array", - "description": "Header displayed before the code lines", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" + { + "$ref": "#/components/parameters/siteId" + }, + { + "name": "siteSpace", + "in": "query", + "description": "ID of the site-space to preview. If not provided, the default site-space will be used.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" + } + }, + "required": ["url"] + } + } } }, - "footer": { - "type": "array", - "description": "Footer displayed after the code lines", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" - } + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "content"] - }, - "ContentKitRenderOutput": { - "type": "object", - "description": "Output of the integration when rendering an UI.", - "properties": { - "element": { - "$ref": "#/components/schemas/ContentKitRootElement" + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/customization": { + "get": { + "operationId": "getSiteCustomizationById", + "summary": "Get the customization configuration for a site.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "state": { - "type": "object" + { + "$ref": "#/components/parameters/siteId" }, - "props": { - "type": "object" + { + "$ref": "#/components/parameters/siteCustomizationUnmasked" } - }, - "required": ["element", "state", "props"] + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } }, - "ContentKitMarkdown": { - "type": "object", - "description": "Block with rich text formatting of a markdown content.", - "properties": { - "type": { - "type": "string", - "enum": ["markdown"] + "put": { + "operationId": "updateSiteCustomizationById", + "summary": "Update the customization configuration for a site.", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, + { + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": true, "content": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitDynamicBinding" - }, - { - "type": "string", - "description": "Markdown content to display" + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" } - ] + } } }, - "required": ["type", "content"] - }, - "ContentKitCard": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["card"] + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" + } + } + } }, - "title": { - "type": "string" + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "hint": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitInlineElement" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/customization/raw": { + "get": { + "operationId": "getSiteRawCustomizationById", + "summary": "Get the raw customization settings of a site.", + "tags": ["sites"], + "security": [ + { + "user-internal": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" + }, + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" } } - ] + } }, - "icon": { - "oneOf": [ - { - "$ref": "#/components/schemas/ContentKitIcon" - }, - { - "$ref": "#/components/schemas/ContentKitImage" - } - ] + "400": { + "$ref": "#/components/responses/BadRequestError" }, - "onPress": { - "$ref": "#/components/schemas/ContentKitAction" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/integration-scripts": { + "get": { + "operationId": "listSiteIntegrationScripts", + "summary": "List the scripts to embed in published content for a site.", + "tags": ["integrations", "sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentKitDescendantElement" + { + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SiteIntegrationScript" + } + } + } } }, - "buttons": { - "type": "array", - "description": "Buttons displayed in the top right corner of the card.", - "items": { - "$ref": "#/components/schemas/ContentKitButton" - } + "400": { + "$ref": "#/components/responses/BadRequestError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type"] - }, - "ContentKitImage": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["image"] + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/integrations": { + "get": { + "operationId": "listSiteIntegrations", + "summary": "List integrations enabled in a site.", + "tags": ["integrations", "sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "source": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" + { + "$ref": "#/components/parameters/siteId" + }, + { + "$ref": "#/components/parameters/integrationSearchQuery" + } + ], + "responses": { + "200": { + "description": "Listing of integrations enabled in the site.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Integration" + } + } + } + } + ] + } } - }, - "required": ["url"] + } }, - "aspectRatio": { - "type": "number" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "source", "aspectRatio"] - }, - "ContentKitLink": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["link"] + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces": { + "post": { + "operationId": "addSpaceToSite", + "summary": "Add a space to a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "target": { - "type": "object", - "properties": { - "url": { - "oneOf": [ - { - "type": "string" - }, - { - "$ref": "#/components/schemas/ContentKitURL" + { + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "spaceId": { + "type": "string", + "description": "ID of the space" } - ] + }, + "required": ["spaceId"] } - }, - "required": ["url"] - }, - "children": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { + } + } + }, + "responses": { + "201": { + "description": "Space added to the site", + "headers": { + "Location": { + "description": "API URL for the newly created site-space relationship", + "schema": { "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" + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteSpace" + } } - ] + } }, - "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" - } - ] + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "label", "element"] + } }, - "ContentKitSelectOption": { - "type": "object", - "description": "An individual option in a select element", - "properties": { - "id": { - "type": "string" + "get": { + "operationId": "listSiteSpaces", + "summary": "List all the site spaces under a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "label": { - "type": "string" + { + "$ref": "#/components/parameters/siteId" }, - "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"] + { + "$ref": "#/components/parameters/siteShareKey" }, - "disabled": { - "type": "boolean" + { + "$ref": "#/components/parameters/listPage" }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", - "type": "string" + { + "$ref": "#/components/parameters/listLimit" }, - "initialValue": { - "description": "Value to initialize the select with.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" + { + "name": "default", + "in": "query", + "description": "If true, only the default site space will be returned. If false, only the non-default site spaces are returned. If undefined, all site spaces are returned.", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SiteSpace" + } + } + } + } + ] } } - ] - }, - "onValueChange": { - "$ref": "#/components/schemas/ContentKitAction" + } }, - "placeholder": { - "description": "Text that appears in the form control when it has no value set", - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/search": { + "post": { + "operationId": "searchSiteContent", + "summary": "Search content in a site", + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "multiple": { - "description": "Should the select accept the selection of multiple options. If true, the state will be an array.", - "type": "boolean" + { + "$ref": "#/components/parameters/siteId" }, - "acceptInput": { - "description": "Should the filter input be allowed to be selected as an option.", - "type": "boolean" + { + "$ref": "#/components/parameters/listPage" }, - "options": { - "description": "Array of options to display in the select.", - "oneOf": [ - { - "type": "array", - "description": "Static list of options", - "items": { - "$ref": "#/components/schemas/ContentKitSelectOption" - } - }, - { + { + "$ref": "#/components/parameters/listLimit" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { "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" - } - ] + "query": { + "type": "string" + }, + "siteSpaceIds": { + "type": "array", + "minLength": 1, + "items": { + "type": "string" + } } }, - "required": ["url"] + "required": ["query"] } - ] + } } }, - "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" + "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" + } + } + } + } + ] + } + } + } }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "required": ["type", "state"] - }, - "ContentKitCheckbox": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": ["checkbox"] + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}": { + "patch": { + "operationId": "updateSiteSpaceById", + "summary": "Update a space on a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "state": { - "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", - "type": "string" + { + "$ref": "#/components/parameters/siteId" }, - "value": { - "description": "Value to store in a state array when the checkbox is selected.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" + { + "$ref": "#/components/parameters/siteSpaceId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "path": { + "$ref": "#/components/schemas/SiteSpacePath" + } + } } - ] - }, - "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" + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteSpace" + } } - ] + } }, - "confirm": { - "$ref": "#/components/schemas/ContentKitConfirm" + "default": { + "$ref": "#/components/responses/UnexpectedError" } - }, - "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 + "delete": { + "operationId": "deleteSiteSpaceById", + "summary": "Delete a space on a site in an organization", + "tags": ["sites"], + "security": [ + { + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, - "confirm": { - "type": "string", - "description": "A text value to define the text of the button that confirms the action.", - "maxLength": 30 + { + "$ref": "#/components/parameters/siteId" }, - "style": { - "type": "string", - "enum": ["primary", "danger"] - } - }, - "required": ["title", "text", "confirm"] - }, - "ContentKitRootElement": { - "description": "Element used as root", - "oneOf": [ { - "$ref": "#/components/schemas/ContentKitBlock" + "$ref": "#/components/parameters/siteSpaceId" + } + ], + "responses": { + "205": { + "description": "Site space has been deleted" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization": { + "get": { + "operationId": "getSiteSpaceCustomizationById", + "summary": "Get the customization configuration for a site space.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitModal" + "user": [] } ], - "discriminator": { - "propertyName": "type" - } - }, - "ContentKitDescendantElement": { - "description": "Any element that can be used as children.", - "oneOf": [ + "parameters": [ { - "$ref": "#/components/schemas/ContentKitButton" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitTextInput" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/ContentKitHStack" + "$ref": "#/components/parameters/siteSpaceId" }, { - "$ref": "#/components/schemas/ContentKitVStack" + "$ref": "#/components/parameters/siteCustomizationUnmasked" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" + } + } + } }, - { - "$ref": "#/components/schemas/ContentKitBox" + "400": { + "$ref": "#/components/responses/BadRequestError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "overrideSiteSpaceCustomizationById", + "summary": "Override the customization configuration for a site space.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitDivider" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentKitWebFrame" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitCodeBlock" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/ContentKitMarkdown" + "$ref": "#/components/parameters/siteSpaceId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "description": "The settings that overrides the site customization settings.", + "$ref": "#/components/schemas/SiteSpaceCustomizationOverrides" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCustomizationSettings" + } + } + } }, - { - "$ref": "#/components/schemas/ContentKitCard" + "400": { + "$ref": "#/components/responses/BadRequestError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization/raw": { + "get": { + "operationId": "getSiteSpaceRawCustomizationById", + "summary": "Get the raw customization settings of a site space.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitImage" - }, + "user-internal": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentKitInput" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitSelect" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/ContentKitSwitch" + "$ref": "#/components/parameters/siteSpaceId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SiteCustomizationSettings" + }, + { + "type": "object", + "properties": { + "hasOverrides": { + "type": "boolean", + "description": "Indicates whether the site customization settings have been overridden." + } + }, + "required": ["hasOverrides"] + } + ] + } + } + } }, - { - "$ref": "#/components/schemas/ContentKitCheckbox" + "400": { + "$ref": "#/components/responses/BadRequestError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/insights/content": { + "get": { + "operationId": "getContentAnalyticsForSiteSpaceById", + "summary": "Get page traffic and ratings for a given site space.", + "tags": ["analytics", "sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitRadio" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/ContentKitText" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitHint" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/ContentKitLink" + "$ref": "#/components/parameters/siteSpaceId" } ], - "discriminator": { - "propertyName": "type" + "responses": { + "200": { + "description": "Content analytics per page.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsContentPages" + } + } + } + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } } - }, - "ContentKitInlineElement": { - "description": "Any element that is inline.", - "oneOf": [ + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/insights/pages/{pageId}/feedbacks/{visitorId}": { + "put": { + "operationId": "createSitesPageFeedback", + "summary": "Create a page feedback by a visitor on a site.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/ContentKitText" + "user": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ContentKitImage" + "$ref": "#/components/parameters/siteId" }, { - "$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" + "$ref": "#/components/parameters/siteSpaceId" }, - "pathname": { - "type": "string", - "description": "Path of the URL prefixed with a `/`.", - "example": "/v1/options" + { + "$ref": "#/components/parameters/pageId" }, - "query": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "type": "string" + { + "$ref": "#/components/parameters/visitorId" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "rating": { + "$ref": "#/components/schemas/PageFeedbackRating" + } }, - { - "$ref": "#/components/schemas/ContentKitDynamicBinding" + "required": ["rating"] + } + } + } + }, + "responses": { + "200": { + "description": "Feedback updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } + } + } + }, + "201": { + "description": "Feedback created", + "headers": { + "Location": { + "description": "URL for the feedback", + "schema": { + "type": "string" } - ] + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PageFeedback" + } + } } - } - }, - "required": ["host", "pathname"] - }, - "SubscriptionChannel": { - "description": "Channel to subscribe to for API updates.", - "oneOf": [ - { - "$ref": "#/components/schemas/SpaceInfoChannel" - }, - { - "$ref": "#/components/schemas/SpaceGitInfoChannel" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move": { + "post": { + "operationId": "moveSiteSpace", + "summary": "Move a site space to a new position in the site.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/SpacePublishingAuthChannel" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/SpacePublishingCustomizationChannel" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/SpaceEntitiesChannel" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/SpaceCustomFieldsChannel" + "$ref": "#/components/parameters/siteSpaceId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "position": { + "description": "The position where to move the site space. When not provided the site space is moved at the end of the site.", + "$ref": "#/components/schemas/SiteSpaceMovePosition" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Site space moved", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteSpace" + } + } + } }, - { - "$ref": "#/components/schemas/BackofficeUserInfoChannel" + "400": { + "description": "Invalid move site space position provided", + "$ref": "#/components/responses/BadRequestError" }, - { - "$ref": "#/components/schemas/SpaceIntegrationsChannel" + "404": { + "description": "No matching Site space found", + "$ref": "#/components/responses/NotFoundError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/permissions/aggregate": { + "get": { + "operationId": "listPermissionsAggregateInSite", + "summary": "List permissions for all users of a site.", + "tags": ["permissions", "sites"], + "security": [ { - "$ref": "#/components/schemas/OrganizationCustomFieldsChannel" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/UserAPITokensChannel" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/UserOrganizationsChannel" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/UserProfileChannel" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/ChangeRequestChannel" + "$ref": "#/components/parameters/listLimit" + } + ], + "responses": { + "200": { + "description": "Listing of users who can access the site.", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/List" + }, + { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserSitePermission" + } + } + } + } + ] + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/insights/track_view": { + "post": { + "operationId": "trackViewInSiteById", + "summary": "Track a page view in a site", + "description": "Track a page view in a site.", + "tags": ["analytics", "sites"], + "parameters": [ { - "$ref": "#/components/schemas/ChangeRequestsChannel" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/ChangeRequestReviewsChannel" + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "204": { + "description": "Page view has been tracked." }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-change-request-broken-links"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteTrackPageView" } - }, - "required": ["channel", "space", "changeRequest"] - }, + } + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/insights/search": { + "post": { + "operationId": "getSearchAnalyticsForSiteById", + "summary": "Get an overview of the top search queries in a site.", + "tags": ["analytics", "sites"], + "security": [ { - "$ref": "#/components/schemas/CollectionChannel" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/CollectionPublishingCustomizationChannel" + "$ref": "#/components/parameters/organizationId" }, { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization"] - }, - "organization": { - "type": "string" + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "siteSpaceIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "period": { + "$ref": "#/components/schemas/AnalyticsSearchPeriod" + } + } } - }, - "required": ["channel", "organization"] + } + } + }, + "responses": { + "200": { + "description": "Top queries searched on this site.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsTopSearches" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/ads": { + "post": { + "operationId": "updateSiteAdsById", + "summary": "Enable, disable, or submit for review Ads on a site.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/OrganizationMembersChannel" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/OrganizationMemberChannel" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/OrganizationTeamsChannel" + "$ref": "#/components/parameters/siteId" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": ["in-review", "disabled"] + }, + "topic": { + "$ref": "#/components/schemas/SiteAdsTopic" + } + } + } + } + } + }, + "responses": { + "204": { + "description": "OK" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/orgs/{organizationId}/sites/{siteId}/ads/stats": { + "post": { + "operationId": "getSiteAdsStatsById", + "summary": "Get the stats about Ads on a site.", + "tags": ["sites"], + "security": [ { - "$ref": "#/components/schemas/OrganizationTeamChannel" - }, + "user": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/OrganizationTeamMembersChannel" + "$ref": "#/components/parameters/organizationId" }, { - "$ref": "#/components/schemas/OrganizationTeamMemberChannel" + "$ref": "#/components/parameters/siteId" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteAdsStats" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/custom-hostnames/{hostname}": { + "get": { + "operationId": "getCustomHostname", + "summary": "Get the details about a custom hostname.", + "tags": ["custom-hostnames"], + "security": [ { - "$ref": "#/components/schemas/OrganizationSpacesChannel" - }, + "user-internal": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/OrganizationCollectionsChannel" + "$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/schemas/OrganizationEntitiesChannel" - }, + "user-internal": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/OrganizationSchemasChannel" + "$ref": "#/components/parameters/hostname" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "target": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationPointer" + }, + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + }, + { + "$ref": "#/components/schemas/SitePointer" + } + ] + } + }, + "required": ["target"] + } + } + } + }, + "responses": { + "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" + } + } + } }, - { - "$ref": "#/components/schemas/OrganizationCapturesChannel" + "400": { + "description": "Selected custom hostname target does not exist", + "$ref": "#/components/responses/ConflictError" }, - { - "$ref": "#/components/schemas/OrganizationContentAuditsChannel" + "409": { + "description": "Custom hostname is already in use on the target", + "$ref": "#/components/responses/ConflictError" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + }, + "patch": { + "operationId": "dnsRevalidateCustomHostname", + "summary": "Revalidate a custom hostname's DNS records and status.", + "tags": ["custom-hostnames"], + "security": [ { - "$ref": "#/components/schemas/OrganizationIntegrationsChannel" - }, + "user-internal": [] + } + ], + "parameters": [ { - "$ref": "#/components/schemas/OrganizationInstallationsChannel" + "$ref": "#/components/parameters/hostname" + } + ], + "responses": { + "204": { + "description": "DNS validation has been retriggered" }, - { - "$ref": "#/components/schemas/OrganizationSitesChannel" + "400": { + "description": "The current custom hostname is inactive and cannot be revalidated", + "$ref": "#/components/responses/ConflictError" }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization-experimental-features"] - }, - "organization": { - "type": "string" - } - }, - "required": ["channel", "organization"] + "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/schemas/OrganizationSyncedBlockChannel" - }, + "user-internal": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comments"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - } - }, - "required": ["channel", "space"] + "$ref": "#/components/parameters/hostname" + } + ], + "responses": { + "205": { + "description": "Custom hostname has been removed" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/custom-hostnames/{hostname}/test": { + "post": { + "operationId": "testCustomHostname", + "summary": "Test if a custom hostname can be used for a content or organization.", + "tags": ["custom-hostnames"], + "security": [ { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comment"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" - } - }, - "required": ["channel", "space", "comment"] - }, + "user-internal": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comment-reply"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" - }, - "commentReply": { - "type": "string" + "$ref": "#/components/parameters/hostname" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "target": { + "oneOf": [ + { + "$ref": "#/components/schemas/OrganizationPointer" + }, + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + }, + { + "$ref": "#/components/schemas/SitePointer" + } + ] + } + }, + "required": ["target"] } - }, - "required": ["channel", "space", "comment", "commentReply"] + } + } + }, + "responses": { + "204": { + "description": "The custom hostname is available and valid." }, - { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-comment-replies"] - }, - "space": { - "type": "string" - }, - "changeRequest": { - "type": "string" - }, - "comment": { - "type": "string" - } - }, - "required": ["channel", "space", "comment"] + "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" + } + } + } + }, + "/ads/sites": { + "get": { + "operationId": "adsListSites", + "summary": "List all the sites with ads configured", + "tags": ["ads"], + "parameters": [ { - "$ref": "#/components/schemas/IntegrationChannel" + "$ref": "#/components/parameters/listPage" }, { - "$ref": "#/components/schemas/IntegrationInstallationChannel" + "$ref": "#/components/parameters/listLimit" }, { - "$ref": "#/components/schemas/IntegrationSpaceInstallationChannel" + "$ref": "#/components/parameters/xGitBookPartnerKey" + } + ], + "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": ["id", "url", "email", "topic"], + "properties": { + "id": { + "type": "string" + }, + "url": { + "type": "string" + }, + "email": { + "type": "string" + }, + "topic": { + "$ref": "#/components/schemas/SiteAdsTopic" + } + } + } + } + } + } + ] + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/ads/sites/{siteId}": { + "patch": { + "operationId": "adsUpdateSite", + "summary": "Update the Ads configuration for a site", + "tags": ["ads"], + "parameters": [ { - "$ref": "#/components/schemas/IntegrationSpaceInstallationsChannel" + "$ref": "#/components/parameters/siteId" }, { - "$ref": "#/components/schemas/IntegrationSiteInstallationChannel" + "$ref": "#/components/parameters/xGitBookPartnerKey" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "type": "object", + "required": ["status", "zoneId", "reportingId"], + "properties": { + "status": { + "type": "string", + "enum": ["live"] + }, + "zoneId": { + "type": "string", + "description": "ID of the zone" + }, + "reportingId": { + "type": "string", + "description": "ID to fetch reporting data" + } + } + }, + { + "type": "object", + "required": ["status"], + "properties": { + "status": { + "type": "string", + "enum": ["rejected"] + } + } + }, + { + "type": "object", + "required": ["status"], + "properties": { + "status": { + "type": "string", + "enum": ["pending"] + } + } + } + ] + } + } + } + }, + "responses": { + "204": { + "description": "OK" }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/internal/hive/token": { + "post": { + "operationId": "generateHiveAccessToken", + "summary": "Returns a token to authenticate with Hive.", + "tags": ["hive"], + "security": [ { - "$ref": "#/components/schemas/IntegrationSiteInstallationsChannel" + "user-internal": [] + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "spaces": { + "deprecated": true, + "type": "array", + "items": { + "description": "Deprecated. Use contentIds.", + "type": "string" + } + }, + "contentIds": { + "type": "array", + "items": { + "description": "Content IDs to retrieve permissions for.", + "type": "string" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The JWT to access user's specific content in Hive.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HiveAccessToken" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/urls/content": { + "get": { + "operationId": "getContentByUrl", + "summary": "Resolve a URL to a content (space, collection, page)", + "tags": ["urls"], + "security": [ { - "$ref": "#/components/schemas/SiteChannel" + "user": [] + } + ], + "parameters": [ + { + "name": "url", + "in": "query", + "required": true, + "description": "URL to resolve", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "type": "object", + "description": "URL resolved to a collection", + "properties": { + "collection": { + "$ref": "#/components/schemas/Collection" + } + }, + "required": ["collection"] + }, + { + "type": "object", + "description": "URL resolved to the content of a space", + "properties": { + "space": { + "$ref": "#/components/schemas/Space" + }, + "changeRequest": { + "$ref": "#/components/schemas/ChangeRequest" + }, + "page": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocument" + }, + { + "$ref": "#/components/schemas/RevisionPageGroup" + } + ] + } + }, + "required": ["space"] + } + ] + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/urls/embed": { + "get": { + "operationId": "getEmbedByUrl", + "summary": "Resolve a URL to an embed", + "tags": ["urls"], + "parameters": [ { - "$ref": "#/components/schemas/SiteSpaceChannel" + "name": "url", + "in": "query", + "required": true, + "description": "URL to resolve", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Embed" + } + } + } }, + "default": { + "$ref": "#/components/responses/UnexpectedError" + } + } + } + }, + "/urls/published": { + "get": { + "operationId": "getPublishedContentByUrl", + "summary": "Resolve a URL of a published content.", + "tags": ["urls"], + "parameters": [ { - "$ref": "#/components/schemas/SiteSpacesChannel" + "name": "url", + "in": "query", + "required": true, + "description": "URL to resolve", + "schema": { + "$ref": "#/components/schemas/URL" + } }, { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["site-publishing-auth"] - }, - "site": { - "type": "string" + "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/PublishedSiteContentLookup" + } } - }, - "required": ["channel", "site"] + } }, - { - "$ref": "#/components/schemas/CustomHostnameChannel" + "404": { + "description": "No content found for the URL.", + "$ref": "#/components/responses/NotFoundError" + }, + "default": { + "$ref": "#/components/responses/UnexpectedError" } - ], - "discriminator": { - "propertyName": "channel" + } + } + } + }, + "components": { + "securitySchemes": { + "user": { + "type": "http", + "scheme": "bearer" + }, + "user-internal": { + "type": "http", + "scheme": "bearer" + }, + "user-staff": { + "type": "http", + "scheme": "bearer" + }, + "integration": { + "type": "http", + "scheme": "bearer" + }, + "integration-installation": { + "type": "http", + "scheme": "bearer" + } + }, + "parameters": { + "listPage": { + "name": "page", + "in": "query", + "description": "Identifier of the page results to fetch.", + "schema": { + "type": "string" + } + }, + "listLimit": { + "name": "limit", + "in": "query", + "description": "The number of results per page", + "schema": { + "type": "number", + "minimum": 0, + "maximum": 1000 + } + }, + "documentFormat": { + "name": "format", + "in": "query", + "description": "Output format for the content.", + "schema": { + "type": "string", + "enum": ["document", "markdown"] + } + }, + "tokenId": { + "name": "tokenId", + "in": "path", + "required": true, + "description": "The id of the API token", + "schema": { + "type": "string" + } + }, + "userId": { + "name": "userId", + "in": "path", + "required": true, + "description": "The unique ID of the User", + "schema": { + "type": "string" + } + }, + "spaceId": { + "name": "spaceId", + "in": "path", + "required": true, + "description": "The unique id of the space", + "schema": { + "type": "string" + } + }, + "siteShareKey": { + "name": "shareKey", + "in": "query", + "description": "For sites published via share-links, the share key is useful to resolve published URLs.", + "schema": { + "type": "string" + } + }, + "teamId": { + "name": "teamId", + "in": "path", + "required": true, + "description": "The unique ID of the Team", + "schema": { + "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 + } + }, + "fileId": { + "name": "fileId", + "in": "path", + "required": true, + "description": "The unique id of the file", + "schema": { + "type": "string" + } + }, + "pageId": { + "name": "pageId", + "in": "path", + "required": true, + "description": "The unique id of the page", + "schema": { + "type": "string" + } + }, + "pagePath": { + "name": "pagePath", + "in": "path", + "required": true, + "description": "The path of the page in the revision.", + "schema": { + "type": "string" + } + }, + "documentSchema": { + "name": "schema", + "in": "query", + "description": "Version of the schema used for the document.", + "schema": { + "type": "string", + "enum": ["current", "next"] + } + }, + "changeRequestId": { + "name": "changeRequestId", + "in": "path", + "required": true, + "description": "The unique ID of the change request or its number identifier in the space", + "schema": { + "type": "string" + } + }, + "listOrder": { + "name": "order", + "in": "query", + "description": "An order for the items in the list", + "schema": { + "type": "string", + "default": "desc", + "enum": ["asc", "desc"] + } + }, + "status": { + "name": "status", + "in": "query", + "description": "When provided, only comments with the given status are returned. Defaults to \"all\".", + "schema": { + "type": "string", + "default": "all", + "enum": ["all", "open", "resolved"] + } + }, + "targetPage": { + "name": "targetPage", + "in": "query", + "description": "The target page of the comment", + "schema": { + "type": "string" } }, - "SpaceInfoChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space"] - }, - "space": { - "type": "string" - } - }, - "required": ["channel", "space"] + "commentId": { + "name": "commentId", + "in": "path", + "required": true, + "description": "The unique id of the comment", + "schema": { + "type": "string" + } }, - "SpaceGitInfoChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-git-info"] - }, - "space": { - "type": "string" - } - }, - "required": ["channel", "space"] + "commentReplyId": { + "name": "commentReplyId", + "in": "path", + "required": true, + "description": "The unique id of the comment reply", + "schema": { + "type": "string" + } }, - "SpacePublishingAuthChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-publishing-auth"] - }, - "space": { - "type": "string" - } - }, - "required": ["channel", "space"] + "revisionId": { + "name": "revisionId", + "in": "path", + "required": true, + "description": "The unique id of the revision", + "schema": { + "type": "string" + } }, - "SpacePublishingCustomizationChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["space-publishing-customization"] - }, - "space": { - "type": "string" - } + "integrationSearchQuery": { + "name": "search", + "in": "query", + "description": "A search string to filter integrations by name\n", + "schema": { + "type": "string" + } + }, + "visitorId": { + "name": "visitorId", + "in": "path", + "required": true, + "description": "The id of the visitor", + "schema": { + "type": "string" + } + }, + "shareLinkId": { + "name": "shareLinkId", + "in": "path", + "required": true, + "description": "The unique id of the share link", + "schema": { + "type": "string" + } + }, + "collectionId": { + "name": "collectionId", + "in": "path", + "required": true, + "description": "The unique id of the collection", + "schema": { + "type": "string" + } + }, + "integrationName": { + "name": "integrationName", + "in": "path", + "required": true, + "description": "Name of the integration.", + "schema": { + "type": "string", + "pattern": "^[a-zA-Z0-9-_.]+$", + "maxLength": 100 + } + }, + "integrationEventId": { + "name": "eventId", + "in": "path", + "required": true, + "description": "ID of the integration event", + "schema": { + "type": "string" + } + }, + "installationId": { + "name": "installationId", + "in": "path", + "required": true, + "description": "Identifier of the installation", + "schema": { + "type": "string" + } + }, + "siteId": { + "name": "siteId", + "in": "path", + "required": true, + "description": "The unique id of the site", + "schema": { + "type": "string" + } + }, + "organizationId": { + "name": "organizationId", + "in": "path", + "required": true, + "description": "The unique id of the organization", + "schema": { + "type": "string" + } + }, + "inviteId": { + "name": "inviteId", + "in": "path", + "required": true, + "description": "The unique id of the invite", + "schema": { + "type": "string" + } + }, + "samlProviderId": { + "name": "samlProviderId", + "in": "path", + "required": true, + "description": "The unique id of the SAML provider", + "schema": { + "type": "string" + } + }, + "captureId": { + "name": "captureId", + "in": "path", + "required": true, + "description": "The unique id of a capture", + "schema": { + "type": "string" + } + }, + "snippetId": { + "name": "snippetId", + "in": "path", + "required": true, + "description": "The unique id of a snippet", + "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" + } + }, + "syncedBlockId": { + "name": "syncedBlockId", + "in": "path", + "required": true, + "description": "The unique id of a synced block", + "schema": { + "type": "string" + } + }, + "siteCustomizationUnmasked": { + "name": "unmasked", + "in": "query", + "description": "(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.", + "deprecated": true, + "schema": { + "type": "boolean", + "default": false + } + }, + "siteSpaceId": { + "name": "siteSpaceId", + "in": "path", + "required": true, + "description": "The unique id of the site-space relationship", + "schema": { + "type": "string" + } + }, + "hostname": { + "name": "hostname", + "in": "path", + "required": true, + "description": "The custom hostname, for example \"docs.gitbook.com\"", + "schema": { + "type": "string" + } + }, + "xGitBookPartnerKey": { + "in": "header", + "name": "X-GitBook-Partner-Key", + "schema": { + "type": "string" }, - "required": ["channel", "space"] + "required": true + }, + "pageFormat": { + "$ref": "#/components/parameters/documentFormat" + }, + "commentStatus": { + "$ref": "#/components/parameters/status" }, - "SpaceEntitiesChannel": { + "commentTargetPage": { + "$ref": "#/components/parameters/targetPage" + } + }, + "schemas": { + "Error": { "type": "object", + "required": ["error"], "properties": { - "channel": { - "type": "string", - "enum": ["space-entities"] - }, - "space": { - "type": "string" + "error": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + } + }, + "required": ["code", "message"] } - }, - "required": ["channel", "space"] + } }, - "SpaceCustomFieldsChannel": { + "ApiInformation": { "type": "object", "properties": { - "channel": { + "version": { "type": "string", - "enum": ["space-customfields"] + "description": "Current release of GitBook" }, - "space": { - "type": "string" + "build": { + "type": "string", + "description": "Date of the latest release in ISO format" } }, - "required": ["channel", "space"] + "required": ["version", "build"] }, - "BackofficeUserInfoChannel": { + "List": { "type": "object", "properties": { - "channel": { - "type": "string", - "enum": ["backoffice-user-info"] + "next": { + "type": "object", + "properties": { + "page": { + "type": "string", + "description": "Unique identifier to query the next results page" + } + }, + "required": ["page"] }, - "user": { - "type": "string" + "count": { + "type": "number", + "description": "Total count of objects in the list" } - }, - "required": ["channel", "user"] + } }, - "SpaceIntegrationsChannel": { + "SearchSectionResult": { "type": "object", + "description": "Search result representing a section in a page.", "properties": { - "channel": { - "type": "string", - "enum": ["space-integrations"] + "id": { + "type": "string" }, - "space": { + "title": { "type": "string" + }, + "path": { + "type": "string" + }, + "body": { + "type": "string" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "app": { + "type": "string", + "description": "URL of the section in the application", + "format": "uri" + } + }, + "required": ["app"] } }, - "required": ["channel", "space"] + "required": ["id", "title", "path", "body", "urls"] }, - "UserAPITokensChannel": { + "SearchPageResult": { "type": "object", + "description": "Search result representing a page in a space.", "properties": { - "channel": { - "type": "string", - "enum": ["user-api-tokens"] + "id": { + "type": "string" }, - "user": { + "title": { + "type": "string" + }, + "path": { "type": "string" + }, + "sections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchSectionResult" + } + }, + "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": ["channel", "user"] + "required": ["id", "title", "path", "urls"] }, - "UserOrganizationsChannel": { + "SearchSpaceResult": { "type": "object", + "description": "Search result representing a space.", "properties": { - "channel": { - "type": "string", - "enum": ["user-organizations"] + "id": { + "type": "string" }, - "user": { + "title": { "type": "string" + }, + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchPageResult" + } } }, - "required": ["channel", "user"] + "required": ["id", "title", "pages"] }, - "UserProfileChannel": { + "MarkdownDocument": { "type": "object", "properties": { - "channel": { + "markdown": { "type": "string", - "enum": ["user-profile"] - }, - "user": { - "type": "string" + "description": "Content of the document formatted as markdown" } }, - "required": ["channel", "user"] + "required": ["markdown"] }, - "CollectionChannel": { + "DocumentMarkBold": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["collection"] + "enum": ["mark"] }, - "collection": { - "type": "string" + "type": { + "type": "string", + "enum": ["bold"] } }, - "required": ["channel", "collection"] + "required": ["object", "type"] }, - "CollectionPublishingCustomizationChannel": { + "DocumentMarkItalic": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["collection-publishing-customization"] + "enum": ["mark"] }, - "collection": { - "type": "string" + "type": { + "type": "string", + "enum": ["italic"] } }, - "required": ["channel", "collection"] + "required": ["object", "type"] }, - "ChangeRequestChannel": { + "DocumentMarkCode": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["space-change-request"] - }, - "space": { - "type": "string" + "enum": ["mark"] }, - "changeRequest": { - "type": "string" + "type": { + "type": "string", + "enum": ["code"] } }, - "required": ["channel", "space", "changeRequest"] + "required": ["object", "type"] }, - "ChangeRequestsChannel": { + "DocumentMarkStrikethrough": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["space-change-requests"] + "enum": ["mark"] }, - "space": { - "type": "string" + "type": { + "type": "string", + "enum": ["strikethrough"] } }, - "required": ["channel", "space"] + "required": ["object", "type"] }, - "ChangeRequestReviewsChannel": { + "DocumentMarkColor": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["space-change-request-reviews"] + "enum": ["mark"] }, - "space": { - "type": "string" + "type": { + "type": "string", + "enum": ["color"] }, - "changeRequest": { - "type": "string" + "data": { + "type": "object", + "properties": { + "text": { + "type": "string", + "enum": [ + "default", + "green", + "blue", + "red", + "orange", + "yellow", + "purple" + ] + }, + "background": { + "type": "string", + "enum": [ + "default", + "green", + "blue", + "red", + "orange", + "yellow", + "purple" + ] + } + }, + "required": ["text", "background"] } }, - "required": ["channel", "space", "changeRequest"] + "required": ["object", "type", "data"] }, - "OrganizationCustomFieldsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization-customfields"] + "DocumentTextMark": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentMarkBold" }, - "organization": { - "type": "string" + { + "$ref": "#/components/schemas/DocumentMarkItalic" + }, + { + "$ref": "#/components/schemas/DocumentMarkCode" + }, + { + "$ref": "#/components/schemas/DocumentMarkStrikethrough" + }, + { + "$ref": "#/components/schemas/DocumentMarkColor" } - }, - "required": ["channel", "organization"] + ] }, - "OrganizationMembersChannel": { + "DocumentTextLeaf": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-members"] + "enum": ["leaf"] }, - "organization": { + "text": { "type": "string" + }, + "marks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTextMark" + } } }, - "required": ["channel", "organization"] + "required": ["object", "text", "marks"] }, - "OrganizationMemberChannel": { + "DocumentText": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-member"] + "enum": ["text"] }, - "organization": { + "key": { "type": "string" }, - "user": { - "type": "string" + "leaves": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTextLeaf" + } } }, - "required": ["channel", "organization", "user"] + "required": ["object", "leaves"] }, - "OrganizationTeamsChannel": { + "ContentRefURL": { "type": "object", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-teams"] + "enum": ["url"] }, - "organization": { + "url": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["kind", "url"] }, - "OrganizationTeamChannel": { + "ContentRefFile": { "type": "object", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-team"] - }, - "organization": { - "type": "string" + "enum": ["file"] }, - "team": { + "file": { "type": "string" } }, - "required": ["channel", "organization", "team"] + "required": ["kind", "file"] }, - "OrganizationSyncedBlockChannel": { + "DocumentInlineImage": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-synced-block"] + "enum": ["inline"] }, - "organization": { - "type": "string" + "type": { + "type": "string", + "enum": ["inline-image"] }, - "syncedBlock": { + "key": { "type": "string" + }, + "data": { + "type": "object", + "properties": { + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefURL" + }, + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] + }, + "refDark": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefURL" + }, + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] + }, + "caption": { + "type": "string" + }, + "size": { + "type": "string", + "enum": ["original", "line"] + } + }, + "required": ["ref"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["channel", "organization", "syncedBlock"] + "required": ["object", "type", "data", "isVoid"] }, - "OrganizationTeamMembersChannel": { + "ContentRefPage": { "type": "object", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-team-members"] + "enum": ["page"] }, - "organization": { + "page": { "type": "string" }, - "team": { + "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": ["channel", "organization", "team"] + "required": ["kind", "page"] }, - "OrganizationTeamMemberChannel": { + "ContentRefAnchor": { "type": "object", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-team-member"] + "enum": ["anchor"] }, - "organization": { + "anchor": { "type": "string" }, - "team": { + "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" }, - "member": { + "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": ["channel", "organization", "member"] + "required": ["kind", "anchor"] }, - "OrganizationSpacesChannel": { + "ContentRefUser": { "type": "object", - "description": "Subscription channel for changes in spaces in an organization.", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-spaces"] + "enum": ["user"] }, - "organization": { + "user": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["kind", "user"] }, - "OrganizationCollectionsChannel": { + "ContentRefCollection": { "type": "object", - "description": "Subscription channel for changes in collections in an organization.", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-collections"] + "enum": ["collection"] }, - "organization": { + "collection": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["kind", "collection"] }, - "OrganizationEntitiesChannel": { + "ContentRefSpace": { "type": "object", - "description": "Subscription channel for entities in an organization.", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-entities"] - }, - "organization": { - "type": "string" + "enum": ["space"] }, - "entityType": { + "space": { "type": "string" } }, - "required": ["channel", "organization", "entityType"] + "required": ["kind", "space"] }, - "OrganizationSchemasChannel": { + "ContentRefSnippet": { "type": "object", - "description": "Subscription channel for all entity schemas in an organization.", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-schemas"] + "enum": ["snippet"] + }, + "snippet": { + "type": "string" }, "organization": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["kind", "snippet", "organization"] }, - "OrganizationCapturesChannel": { + "ContentRefSyncedBlock": { "type": "object", "properties": { - "channel": { + "kind": { "type": "string", - "enum": ["organization-captures"] + "enum": ["synced-block"] }, - "organization": { + "syncedBlock": { "type": "string" } }, - "required": ["channel", "organization"] + "required": ["kind", "syncedBlock"] }, - "OrganizationContentAuditsChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["organization-content-audits"] + "ContentRef": { + "description": "A relative reference to content in GitBook.", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" }, - "organization": { - "type": "string" + { + "$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" } - }, - "required": ["channel", "organization"] + ] }, - "OrganizationIntegrationsChannel": { + "DocumentInlineLink": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-integrations"] + "enum": ["inline"] }, - "organization": { + "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": ["channel", "organization"] + "required": ["object", "type", "nodes", "data"] }, - "OrganizationInstallationsChannel": { + "DocumentInlineEmoji": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-installations"] + "enum": ["inline"] }, - "organization": { + "type": { + "type": "string", + "enum": ["emoji"] + }, + "key": { "type": "string" + }, + "data": { + "type": "object", + "properties": { + "code": { + "type": "string" + } + }, + "required": ["code"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["channel", "organization"] + "required": ["object", "type", "data", "isVoid"] }, - "OrganizationSitesChannel": { + "DocumentInlineMath": { "type": "object", - "description": "Subscription channel for changes in sites in an organization.", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["organization-sites"] + "enum": ["inline"] }, - "organization": { + "type": { + "type": "string", + "enum": ["inline-math"] + }, + "key": { "type": "string" + }, + "data": { + "type": "object", + "properties": { + "formula": { + "type": "string" + } + }, + "required": ["formula"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["channel", "organization"] + "required": ["object", "type", "data", "isVoid"] }, - "IntegrationChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["integration"] + "DocumentBlocksEssentials": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockParagraph" }, - "integration": { - "type": "string" + { + "$ref": "#/components/schemas/DocumentBlockHeading" + }, + { + "$ref": "#/components/schemas/DocumentBlockListOrdered" + }, + { + "$ref": "#/components/schemas/DocumentBlockListUnordered" + }, + { + "$ref": "#/components/schemas/DocumentBlockListTasks" + }, + { + "$ref": "#/components/schemas/DocumentBlockDivider" } - }, - "required": ["channel", "integration"] + ] }, - "IntegrationInstallationChannel": { + "DocumentFragment": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["integration-installation"] + "enum": ["fragment"] }, - "integration": { + "key": { "type": "string" }, - "installation": { + "fragment": { + "type": "string" + }, + "type": { "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + } } }, - "required": ["channel", "integration", "installation"] + "required": ["object", "nodes"] }, - "IntegrationSpaceInstallationChannel": { + "DocumentInlineAnnotation": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["integration-space-installation"] + "enum": ["inline"] }, - "integration": { - "type": "string" + "type": { + "type": "string", + "enum": ["annotation"] }, - "installation": { + "key": { "type": "string" }, - "space": { - "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": ["channel", "integration", "installation", "space"] + "required": ["object", "type", "fragments", "isVoid", "nodes"] }, - "IntegrationSpaceInstallationsChannel": { + "DocumentBlockCodeLine": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["integration-space-installations"] + "enum": ["block"] }, - "integration": { - "type": "string" + "type": { + "type": "string", + "enum": ["code-line"] }, - "installation": { + "key": { "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentText" + }, + { + "$ref": "#/components/schemas/DocumentInlineAnnotation" + } + ] + } + }, + "data": { + "type": "object", + "properties": { + "highlighted": { + "type": "boolean" + } + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["channel", "integration", "installation"] + "required": ["object", "type", "nodes", "data"] }, - "IntegrationSiteInstallationChannel": { + "DocumentBlockCode": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["integration-site-installation"] + "enum": ["block"] }, - "integration": { - "type": "string" + "type": { + "type": "string", + "enum": ["code"] }, - "installation": { + "key": { "type": "string" }, - "site": { - "type": "string" + "data": { + "type": "object", + "properties": { + "syntax": { + "type": "string" + }, + "title": { + "type": "string" + }, + "overflow": { + "type": "string", + "default": "scroll", + "enum": ["scroll", "wrap"] + }, + "lineNumbers": { + "type": "boolean" + }, + "fullWidth": { + "type": "boolean" + } + } + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockCodeLine" + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["channel", "integration", "installation", "site"] + "required": ["object", "type", "data", "nodes"] }, - "IntegrationSiteInstallationsChannel": { + "DocumentInlineMention": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["integration-site-installations"] + "enum": ["inline"] }, - "integration": { - "type": "string" + "type": { + "type": "string", + "enum": ["mention"] }, - "installation": { + "key": { "type": "string" + }, + "data": { + "type": "object", + "properties": { + "ref": { + "$ref": "#/components/schemas/ContentRef" + } + }, + "required": ["ref"] + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["channel", "integration", "installation"] + "required": ["object", "type", "data", "isVoid"] }, - "SiteChannel": { - "type": "object", - "properties": { - "channel": { - "type": "string", - "enum": ["site"] + "DocumentInline": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentInlineLink" }, - "site": { - "type": "string" + { + "$ref": "#/components/schemas/DocumentInlineEmoji" + }, + { + "$ref": "#/components/schemas/DocumentInlineMath" + }, + { + "$ref": "#/components/schemas/DocumentInlineImage" + }, + { + "$ref": "#/components/schemas/DocumentInlineAnnotation" + }, + { + "$ref": "#/components/schemas/DocumentInlineMention" } - }, - "required": ["channel", "site"] + ] }, - "SiteSpaceChannel": { + "DocumentBlockParagraph": { "type": "object", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["site-space"] + "enum": ["block"] }, - "site": { - "type": "string" + "type": { + "type": "string", + "enum": ["paragraph"] }, - "siteSpace": { + "key": { "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentInline" + }, + { + "$ref": "#/components/schemas/DocumentText" + } + ] + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } }, - "required": ["channel", "site", "siteSpace"] + "required": ["object", "type", "nodes"] }, - "SiteSpacesChannel": { + "DocumentBlockHeading": { "type": "object", - "description": "Subscription channel for changes in site spaces in an organization.", "properties": { - "channel": { + "object": { "type": "string", - "enum": ["site-spaces"] + "enum": ["block"] }, - "site": { - "type": "string" - } - }, - "required": ["channel", "site"] - }, - "CustomHostnameChannel": { - "type": "object", - "properties": { - "channel": { + "type": { "type": "string", - "enum": ["custom-hostname"] + "enum": ["heading-1", "heading-2", "heading-3"] }, - "customHostname": { + "key": { "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentInline" + }, + { + "$ref": "#/components/schemas/DocumentText" + } + ] + } + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[-a-z0-9.+_]+$" + } + } + }, + "meta": { + "type": "object", + "properties": { + "id": { + "description": "Unique ID to be used in an URL for the block.", + "type": "string" + } + }, + "required": ["id"] + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["channel", "customHostname"] + "required": ["object", "type", "nodes", "data"] }, - "CustomField": { + "DocumentBlockHint": { "type": "object", - "description": "Custom field", "properties": { - "id": { - "type": "string" - }, - "name": { - "$ref": "#/components/schemas/CustomFieldName" - }, - "title": { - "$ref": "#/components/schemas/CustomFieldTitle" - }, - "description": { - "$ref": "#/components/schemas/CustomFieldDescription" + "object": { + "type": "string", + "enum": ["block"] }, "type": { - "$ref": "#/components/schemas/CustomFieldType" - }, - "placeholder": { - "$ref": "#/components/schemas/CustomFieldPlaceholder" - }, - "options": { - "$ref": "#/components/schemas/CustomFieldOptions" - }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + "type": "string", + "enum": ["hint"] }, - "updatedAt": { - "$ref": "#/components/schemas/Timestamp" + "key": { + "type": "string" }, - "urls": { + "data": { "type": "object", - "description": "URLs associated with the object", "properties": { - "location": { + "style": { "type": "string", - "description": "URL of the custom field in the API", - "format": "uri" + "enum": ["info", "warning", "danger", "success"] } }, - "required": ["location"] + "required": ["style"] + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "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"] + "required": ["object", "type", "data", "nodes"] }, - "CustomFieldValue": { - "oneOf": [ - { + "DocumentBlockQuote": { + "type": "object", + "properties": { + "object": { "type": "string", - "maxLength": 256 + "enum": ["block"] }, - { - "type": "number" + "type": { + "type": "string", + "enum": ["blockquote"] }, - { - "type": "boolean" + "key": { + "type": "string" }, - { + "nodes": { "type": "array", "items": { - "type": "string", - "maxLength": 256 + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + }, + { + "$ref": "#/components/schemas/DocumentBlockQuote" + } + ] } + }, + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } - ] + }, + "required": ["object", "type", "nodes"] }, - "CustomFieldValues": { - "type": "array", - "items": { - "type": "object", - "properties": { - "customField": { - "$ref": "#/components/schemas/CustomField" + "DocumentBlockMath": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["math"] + }, + "key": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "formula": { + "type": "string" + } }, - "value": { - "$ref": "#/components/schemas/CustomFieldValue" - } + "required": ["formula"] }, - "required": ["customField"] - } + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] }, - "UpdateCustomFieldValues": { + "DocumentTableViewGrid": { "type": "object", "properties": { - "values": { + "type": { + "type": "string", + "enum": ["grid"] + }, + "columns": { + "type": "array", + "description": "Ordered list of the definition IDs to display", + "items": { + "type": "string" + } + }, + "columnWidths": { "type": "object", + "description": "Percent width of each column", "additionalProperties": { - "type": "object", - "maxProperties": 100, - "minProperties": 1, - "properties": { - "value": { - "$ref": "#/components/schemas/CustomFieldValue" - } - }, - "required": ["value"] + "type": "number" } + }, + "hideHeader": { + "type": "boolean", + "description": "Should we display the header with column titles" + }, + "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": ["values"] - }, - "CustomFieldOptions": { - "type": "array", - "minItems": 1, - "maxItems": 50, - "items": { - "type": "string", - "minLength": 1, - "maxLength": 40 - } - }, - "CustomFieldPlaceholder": { - "type": "string", - "maxLength": 100 + "required": ["type", "columns", "hideHeader"] }, - "CustomizationSettings": { + "DocumentTableViewCards": { "type": "object", "properties": { - "inherit": { - "type": "boolean", - "description": "Inherit customization settings from the parent collection." + "type": { + "type": "string", + "enum": ["cards"] }, - "title": { + "cardSize": { "type": "string", - "description": "Title to use for the published content. If not defined, it'll fallback to the content title." + "description": "Size of the cards. It indicates how many columns will be used", + "enum": ["medium", "large"] }, - "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"] + "columns": { + "type": "array", + "description": "Ordered list of the definition IDs to display", + "items": { + "type": "string" + } }, - "internationalization": { - "type": "object", - "properties": { - "locale": { - "$ref": "#/components/schemas/CustomizationLocale" - }, - "inherit": { - "type": "boolean", - "description": "Inherit locale from the parent collection." - } - }, - "required": ["locale", "inherit"] + "targetDefinition": { + "type": "string", + "description": "Definition ID to use as a target link for the card" }, - "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 - } - ] + "coverDefinition": { + "type": "string", + "description": "Definition ID to use as a cover image" }, - "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"] + "hideColumnTitle": { + "type": "boolean", + "description": "Should we display the column title or not" + } + }, + "required": ["type", "columns", "cardSize"] + }, + "DocumentTableRecord": { + "type": "object", + "properties": { + "orderIndex": { + "type": "string" }, - "footer": { + "values": { "type": "object", - "properties": { - "logo": { - "$ref": "#/components/schemas/CustomizationThemedURL" - }, - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomizationFooterGroup" + "additionalProperties": { + "oneOf": [ + { + "type": "number" + }, + { + "type": "string" + }, + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "$ref": "#/components/schemas/ContentRef" } - }, - "copyright": { - "type": "string", - "maxLength": 300 - } - }, - "required": ["groups"] + ] + } + } + }, + "required": ["orderIndex", "values"] + }, + "DocumentTableDefinitionBase": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "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"] + "title": { + "type": "string", + "description": "Title for the column" + } + }, + "required": ["id", "title"] + }, + "DocumentTableDefinitionText": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "pdf": { + { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "If true, PDF export is enabled for the published content." + "type": { + "type": "string", + "enum": ["text"] + }, + "textAlignment": { + "type": "string", + "enum": ["center", "right", "left"] } }, - "required": ["enabled"] + "required": ["type", "textAlignment"] + } + ] + }, + "DocumentTableDefinitionNumber": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "feedback": { + { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "If true, feedback gathering is enabled" + "type": { + "type": "string", + "enum": ["number"] } }, - "required": ["enabled"] + "required": ["type"] + } + ] + }, + "DocumentTableDefinitionCheckbox": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "aiSearch": { + { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "If true, AI search is enabled" + "type": { + "type": "string", + "enum": ["checkbox"] } }, - "required": ["enabled"] + "required": ["type"] + } + ] + }, + "DocumentTableDefinitionFiles": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "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" + "type": { + "type": "string", + "enum": ["files"] } }, - "required": ["showEditLink"] + "required": ["type"] + } + ] + }, + "DocumentTableDefinitionUsers": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "pagination": { + { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Whether the pagination navigation should be displayed on pages." + "type": { + "type": "string", + "enum": ["users"] + }, + "multiple": { + "type": "boolean" } }, - "required": ["enabled"] + "required": ["type", "multiple"] + } + ] + }, + "DocumentTableDefinitionRating": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, - "trademark": { + { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible" + "type": { + "type": "string", + "enum": ["rating"] + }, + "max": { + "type": "number" } }, - "required": ["enabled"] + "required": ["type", "max"] + } + ] + }, + "DocumentTableSelectOption": { + "type": "object", + "properties": { + "value": { + "type": "string" }, - "privacyPolicy": { - "type": "object", - "properties": { - "url": { - "$ref": "#/components/schemas/URL" - } - } + "label": { + "type": "string" }, - "socialPreview": { - "type": "object", - "properties": { - "url": { - "$ref": "#/components/schemas/URL" - } - } + "color": { + "type": "string" } }, - "required": [ - "inherit", - "styling", - "internationalization", - "favicon", - "header", - "footer", - "themes", - "pdf", - "feedback", - "aiSearch", - "trademark", - "pagination", - "git", - "privacyPolicy", - "socialPreview" - ] + "required": ["value", "label", "color"] }, - "CustomizationCollectionSettings": { + "DocumentTableDefinitionSelect": { "allOf": [ { - "$ref": "#/components/schemas/CustomizationSettings" + "$ref": "#/components/schemas/DocumentTableDefinitionBase" }, { "type": "object", "properties": { - "collection": { - "type": "object", - "properties": { - "defaultSpace": { - "type": "string", - "description": "ID of the space used by default in the collection" - } + "type": { + "type": "string", + "enum": ["select"] + }, + "multiple": { + "type": "boolean" + }, + "options": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentTableSelectOption" } } }, - "required": ["collection"] + "required": ["type", "multiple", "options"] } ] }, - "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" + "DocumentTableDefinitionContentRef": { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentTableDefinitionBase" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["content-ref"] + } + }, + "required": ["type"] + } ] }, - "CustomizationHeaderPreset": { - "type": "string", - "enum": ["default", "bold", "contrast", "custom", "none"] - }, - "CustomizationThemeMode": { - "type": "string", - "enum": ["light", "dark"] - }, - "CustomizationHeaderLink": { - "allOf": [ + "DocumentTableDefinition": { + "oneOf": [ { - "$ref": "#/components/schemas/CustomizationContentLink" + "$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" + } + ] + }, + "DocumentBlockTable": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["table"] + }, + "key": { + "type": "string" + }, + "isVoid": { + "type": "boolean", + "enum": [true] + }, + "data": { "type": "object", "properties": { - "links": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomizationContentLink" + "view": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentTableViewGrid" + }, + { + "$ref": "#/components/schemas/DocumentTableViewCards" + } + ] + }, + "records": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/DocumentTableRecord" + } + }, + "definition": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/DocumentTableDefinition" } + }, + "fullWidth": { + "type": "boolean", + "description": "Whether to render the block as a full width one" } + }, + "required": ["view", "records", "definition"] + }, + "fragments": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentFragment" } } - ] + }, + "required": ["object", "type", "data", "isVoid", "fragments"] }, - "CustomizationContentLink": { + "DocumentBlockListItem": { "type": "object", "properties": { - "title": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["list-item"] + }, + "key": { "type": "string" }, - "to": { - "$ref": "#/components/schemas/ContentRef" + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + }, + { + "$ref": "#/components/schemas/DocumentBlockCode" + }, + { + "$ref": "#/components/schemas/DocumentBlockHint" + }, + { + "$ref": "#/components/schemas/DocumentBlockQuote" + }, + { + "$ref": "#/components/schemas/DocumentBlockMath" + }, + { + "$ref": "#/components/schemas/DocumentBlockTable" + } + ] + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { + "type": "object", + "properties": { + "checked": { + "type": "boolean" + } + } } }, - "required": ["title", "to"] + "required": ["object", "type", "nodes"] }, - "CustomizationFooterGroup": { + "DocumentBlockListOrdered": { "type": "object", "properties": { - "title": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["list-ordered"] + }, + "key": { "type": "string" }, - "links": { + "data": { + "type": "object", + "properties": { + "start": { + "type": "number", + "description": "An integer to start counting from for the list items." + } + } + }, + "nodes": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomizationContentLink" + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockListItem" + } + ] } + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["title", "links"] - }, - "CustomizationCorners": { - "type": "string", - "enum": ["straight", "rounded"] - }, - "CustomizationBackground": { - "type": "string", - "enum": ["plain", "match"] + "required": ["object", "type", "data", "nodes"] }, - "CustomizationThemedURL": { + "DocumentBlockListUnordered": { "type": "object", "properties": { - "light": { - "$ref": "#/components/schemas/URL" + "object": { + "type": "string", + "enum": ["block"] }, - "dark": { - "$ref": "#/components/schemas/URL" + "type": { + "type": "string", + "enum": ["list-unordered"] + }, + "key": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockListItem" + } + ] + } + }, + "data": { + "type": "object", + "additionalProperties": false + }, + "isVoid": { + "type": "boolean", + "enum": [false] } }, - "required": ["light", "dark"] + "required": ["object", "type", "nodes"] }, - "CustomizationThemedColor": { + "DocumentBlockListTasks": { "type": "object", "properties": { - "light": { - "$ref": "#/components/schemas/Color" + "object": { + "type": "string", + "enum": ["block"] }, - "dark": { - "$ref": "#/components/schemas/Color" + "type": { + "type": "string", + "enum": ["list-tasks"] + }, + "key": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlockListItem" + } + ] + } + }, + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } }, - "required": ["light", "dark"] + "required": ["object", "type", "nodes"] }, - "PageFeedback": { + "DocumentBlockDivider": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of Object, always equal to \"page-feedback\"", - "enum": ["page-feedback"] + "enum": ["block"] }, - "visitorId": { - "type": "string" + "type": { + "type": "string", + "enum": ["divider"] }, - "rating": { - "$ref": "#/components/schemas/PageFeedbackRating" + "key": { + "type": "string" }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + "isVoid": { + "type": "boolean", + "enum": [true] }, - "revision": { - "type": "string", - "description": "ID of the revision when the rating was created" + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false + } + }, + "required": ["object", "type", "isVoid", "data"] + }, + "DocumentBlockImageDimension": { + "oneOf": [ + { + "type": "number" }, - "urls": { + { "type": "object", - "description": "URLs associated with the object", "properties": { - "location": { - "type": "string", - "description": "URL of the page feedback in the API", - "format": "uri" + "unit": { + "type": "string" + }, + "value": { + "type": "number" } }, - "required": ["location"] + "required": ["unit", "value"] } - }, - "required": ["object", "visitorId", "rating", "createdAt", "revision", "urls"] - }, - "PageFeedbackRating": { - "type": "string", - "enum": ["bad", "ok", "good"] + ] }, - "ShareLink": { + "DocumentBlockImage": { "type": "object", "properties": { "object": { "type": "string", - "description": "Type of Object, always equals to \"share-link\"", - "enum": ["share-link"] + "enum": ["block"] }, - "id": { + "type": { "type": "string", - "description": "Unique identifier for the share-link" + "enum": ["image"] }, - "createdAt": { - "$ref": "#/components/schemas/Timestamp" + "key": { + "type": "string" }, - "name": { - "$ref": "#/components/schemas/ShareLinkName" + "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"] }, - "active": { - "type": "boolean" + "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", "id", "createdAt"] - }, - "ShareLinkName": { - "type": "string", - "description": "Name of the share link", - "minLength": 0, - "maxLength": 50 + "required": ["object", "type", "data", "fragments", "isVoid"] }, - "Site": { + "DocumentBlockImages": { "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" + "enum": ["block"] }, - "createdAt": { + "type": { "type": "string", - "format": "date-time" + "enum": ["images"] }, - "subscription": { - "$ref": "#/components/schemas/SiteSubscription" + "key": { + "type": "string" }, - "urls": { + "data": { "type": "object", - "description": "URLs associated with the object", "properties": { - "location": { - "type": "string", - "description": "URL of the site in the API", - "format": "uri" - }, - "app": { + "align": { "type": "string", - "description": "URL of the site in the application", - "format": "uri" + "enum": ["center", "left", "right"] }, - "published": { - "type": "string", - "description": "URL of the published version of the site. Only defined when visibility is not \"unpublished.\"", - "format": "uri" + "fullWidth": { + "type": "boolean" } - }, - "required": ["app", "location"] + } + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockImage" + } + }, + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": [ - "object", - "id", - "title", - "basename", - "visibility", - "createdAt", - "siteSpaces", - "defaultSpace", - "subscription", - "urls" - ] - }, - "SiteTitle": { - "type": "string", - "description": "Title of the site", - "minLength": 2, - "maxLength": 50 + "required": ["object", "type", "data", "nodes", "isVoid"] }, - "SiteCustomizationSettings": { + "DocumentBlockFile": { "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"] + "object": { + "type": "string", + "enum": ["block"] }, - "internationalization": { - "type": "object", - "properties": { - "locale": { - "$ref": "#/components/schemas/CustomizationLocale" - } - }, - "required": ["locale"] + "type": { + "type": "string", + "enum": ["file"] }, - "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 - } - ] + "key": { + "type": "string" }, - "header": { + "data": { "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" - } + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] } }, - "required": ["preset", "links"] + "required": ["ref"] }, - "footer": { + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlockDrawing": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["drawing"] + }, + "key": { + "type": "string" + }, + "data": { "type": "object", "properties": { - "logo": { - "$ref": "#/components/schemas/CustomizationThemedURL" - }, - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomizationFooterGroup" - } - }, - "copyright": { - "type": "string", - "maxLength": 300 + "ref": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentRefFile" + } + ] } - }, - "required": ["groups"] + } }, - "themes": { + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlockEmbed": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["embed"] + }, + "key": { + "type": "string" + }, + "data": { "type": "object", "properties": { - "default": { - "$ref": "#/components/schemas/CustomizationThemeMode" + "url": { + "type": "string" }, - "toggeable": { - "description": "Should the reader be able to switch between dark and light mode", + "fullWidth": { "type": "boolean" } }, - "required": ["default", "toggeable"] + "required": ["url"] }, - "pdf": { + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlockExpandable": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["expandable"] + }, + "key": { + "type": "string" + }, + "isVoid": { + "type": "boolean", + "enum": [true] + }, + "data": { "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "If true, PDF export is enabled for the published site." - } - }, - "required": ["enabled"] + "properties": {}, + "additionalProperties": false }, - "feedback": { + "fragments": { + "type": "array", + "items": { + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentFragment" + }, + { + "type": "object", + "properties": { + "fragment": { + "type": "string", + "enum": ["expandable-title"] + }, + "type": { + "type": "string", + "enum": ["expandable-title"] + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockParagraph" + }, + "minItems": 1, + "maxItems": 1 + } + }, + "required": ["nodes", "fragment", "type"] + } + ] + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/DocumentFragment" + }, + { + "type": "object", + "properties": { + "fragment": { + "type": "string", + "enum": ["expandable-body"] + }, + "type": { + "type": "string", + "enum": ["expandable-body"] + }, + "nodes": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/DocumentBlocksEssentials" + }, + { + "$ref": "#/components/schemas/DocumentBlockCode" + } + ] + }, + "minItems": 1 + } + }, + "required": ["nodes", "fragment", "type"] + } + ] + } + ] + } + }, + "meta": { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "If true, feedback gathering is enabled" + "id": { + "description": "Unique ID to be used in an URL for the block.", + "type": "string" } }, - "required": ["enabled"] + "required": ["id"] + } + }, + "required": ["object", "type", "isVoid", "fragments", "data"] + }, + "DocumentBlockContentRef": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] }, - "aiSearch": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "If true, AI search is enabled" - } - }, - "required": ["enabled"] + "type": { + "type": "string", + "enum": ["content-ref"] }, - "git": { + "key": { + "type": "string" + }, + "data": { "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" + "ref": { + "$ref": "#/components/schemas/ContentRef" } }, - "required": ["showEditLink"] + "required": ["ref"] }, - "pagination": { + "isVoid": { + "type": "boolean", + "enum": [true] + } + }, + "required": ["object", "type", "data", "isVoid"] + }, + "ContentKitDefaultAction": { + "oneOf": [ + { "type": "object", + "description": "Action to open an overlay modal defined by \"componentId\".", "properties": { - "enabled": { - "type": "boolean", - "description": "Whether the pagination navigation should be displayed on pages." + "action": { + "type": "string", + "enum": ["@ui.modal.open"] + }, + "componentId": { + "type": "string" + }, + "props": { + "type": "object" } }, - "required": ["enabled"] + "required": ["action", "componentId", "props"] }, - "trademark": { + { "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": { - "enabled": { - "type": "boolean", - "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible" + "action": { + "type": "string", + "enum": ["@ui.modal.close"] + }, + "returnValue": { + "type": "object" } }, - "required": ["enabled"] + "required": ["action", "returnValue"] }, - "privacyPolicy": { + { "type": "object", + "description": "Action to open an url.", "properties": { + "action": { + "type": "string", + "enum": ["@ui.url.open"] + }, "url": { - "$ref": "#/components/schemas/URL" + "type": "string" } - } + }, + "required": ["action", "url"] }, - "socialPreview": { + { "type": "object", + "description": "Action when a link is being unfurled into a block.", "properties": { + "action": { + "type": "string", + "enum": ["@link.unfurl"] + }, "url": { - "$ref": "#/components/schemas/URL" + "type": "string" } - } - } - }, - "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": [ + }, + "required": ["action", "url"] + }, { "type": "object", + "description": "Action to update the properties stored in the related node.", "properties": { - "object": { - "type": "string", - "description": "Type of Object, always equals to \"publishing-auth\"", - "enum": ["publishing-auth"] - }, - "privateKey": { + "action": { "type": "string", - "description": "Private key used to sign JWT tokens." + "enum": ["@editor.node.updateProps"] }, - "fallbackURL": { - "type": "string", - "format": "uri", - "description": "URL to redirect to when the visitor auth secret is invalid." + "props": { + "type": "object" } }, - "required": ["object", "privateKey"] - }, - { - "$ref": "#/components/schemas/SpaceVisitorAuth" + "required": ["action", "props"] } ] }, - "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": { + "ContentKitAction": { + "anyOf": [ + { "type": "object", - "description": "URLs associated with the object", + "description": "Custom action to re-render the block.", "properties": { - "location": { - "type": "string", - "description": "URL of the custom hostname in the API", - "format": "uri" + "action": { + "type": "string" } }, - "required": ["location"] - } - }, - "required": ["object", "hostname", "target", "isActive", "urls"] - }, - "CustomHostnameStatus": { - "type": "string", - "oneOf": [ - { - "$ref": "#/components/schemas/CustomHostnameDnsStatus" - }, - { - "$ref": "#/components/schemas/CustomHostnameSslStatus" + "additionalProperties": true, + "required": ["action"] }, { - "$ref": "#/components/schemas/CustomHostnameErrorStatus" + "$ref": "#/components/schemas/ContentKitDefaultAction" } ] }, - "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": { + "DocumentBlockIntegration": { "type": "object", "properties": { "object": { "type": "string", - "enum": ["seat"] + "enum": ["block"] }, - "organization": { - "description": "The unique ID of the organization", - "type": "string" + "type": { + "type": "string", + "enum": ["integration"] }, - "member": { - "description": "The unique ID of the organization member", + "key": { "type": "string" }, - "createdAt": { - "type": "string", - "format": "date-time" + "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"] }, - "updatedAt": { - "type": "string", - "format": "date-time" + "isVoid": { + "type": "boolean", + "enum": [true] } }, - "required": ["object", "organization", "member", "createdAt", "updatedAt"] + "required": ["object", "type", "data", "isVoid"] }, - "SeatsUsage": { + "DocumentBlockTabsItem": { "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" - } - } - } + "object": { + "type": "string", + "enum": ["block"] }, - "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" - } + "type": { + "type": "string", + "enum": ["tabs-item"] }, - { - "$ref": "#/components/parameters/listPage" + "key": { + "type": "string" }, - { - "$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" - } - } - } - } - ] + "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" } - } + ] } }, - "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" + "data": { + "type": "object", + "properties": { + "title": { + "type": "string" + } } }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } - } + "meta": { + "type": "object", + "properties": { + "id": { + "description": "Unique ID to be used in an URL for the block.", + "type": "string" } - } + }, + "required": ["id"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "isVoid": { + "type": "boolean", + "enum": [false] } - } + }, + "required": ["object", "type", "nodes", "data"] }, - "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" - } + "DocumentBlockTabs": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["tabs"] + }, + "key": { + "type": "string" + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlockTabsItem" } + }, + "isVoid": { + "type": "boolean", + "enum": [false] + }, + "data": { + "type": "object", + "properties": {}, + "additionalProperties": false } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } + "required": ["object", "type", "nodes"] + }, + "DocumentBlockSwagger": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["swagger"] + }, + "key": { + "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"] }, - "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": [] + "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"] } - ], - "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"] + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlockSyncedBlock": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["block"] + }, + "type": { + "type": "string", + "enum": ["synced-block"] + }, + "key": { + "type": "string" + }, + "data": { + "type": "object", + "properties": { + "ref": { + "$ref": "#/components/schemas/ContentRefSyncedBlock" } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestions" - } + }, + "required": ["ref"] + }, + "meta": { + "type": "object", + "properties": { + "apiToken": { + "description": "API Token to use to fetch the synced block from the API.", + "type": "string" } - } + }, + "required": ["apiToken"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "isVoid": { + "type": "boolean", + "enum": [true] } - } - } - }, - "/user": { - "get": { - "operationId": "getAuthenticatedUser", - "summary": "Get profile of authenticated user", - "tags": ["users"], - "security": [ + }, + "required": ["object", "type", "data", "isVoid"] + }, + "DocumentBlocksTopLevels": { + "oneOf": [ { - "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" - } - } - } + "$ref": "#/components/schemas/DocumentBlocksEssentials" }, - "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/schemas/DocumentBlockQuote" + }, { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/User" - } - } - } + "$ref": "#/components/schemas/DocumentBlockHint" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}": { - "get": { - "operationId": "getSpaceById", - "summary": "Get the details about a space.", - "tags": ["spaces"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockImages" + }, { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } - } - } + "$ref": "#/components/schemas/DocumentBlockFile" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "patch": { - "operationId": "updateSpaceById", - "summary": "Update the details of a space", - "tags": ["spaces"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockDrawing" + }, { - "$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" - } - } - } + "$ref": "#/components/schemas/DocumentBlockEmbed" }, - "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/schemas/DocumentBlockCode" + }, { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "205": { - "description": "Space has been deleted" + "$ref": "#/components/schemas/DocumentBlockMath" + }, + { + "$ref": "#/components/schemas/DocumentBlockExpandable" + }, + { + "$ref": "#/components/schemas/DocumentBlockTabs" + }, + { + "$ref": "#/components/schemas/DocumentBlockTable" + }, + { + "$ref": "#/components/schemas/DocumentBlockSwagger" + }, + { + "$ref": "#/components/schemas/DocumentBlockContentRef" }, - "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" + "$ref": "#/components/schemas/DocumentBlockIntegration" + }, + { + "$ref": "#/components/schemas/DocumentBlockSyncedBlock" } - ], - "responses": { - "200": { - "description": "The JWT to access the space content in Hive.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HiveAccessToken" - } + ] + }, + "JSONDocument": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["document"] + }, + "data": { + "type": "object", + "properties": { + "schemaVersion": { + "description": "The schema version of the document. If undefined, the document is considered to be of the latest schema version.", + "type": "integer" } - } + }, + "additionalProperties": true }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocumentBlocksTopLevels" + } } - } - } - }, - "/spaces/{spaceId}/duplicate": { - "post": { - "operationId": "duplicateSpace", - "summary": "Create a duplicate of the space.", - "tags": ["spaces"], - "security": [ + }, + "required": ["object", "data", "nodes"] + }, + "Document": { + "oneOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/MarkdownDocument", + "title": "Markdown" + }, { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "201": { - "description": "Space duplicated", - "headers": { - "Location": { - "description": "API URL for the newly created space", - "schema": { - "type": "string" - } + "type": "object", + "title": "JSON Document", + "properties": { + "document": { + "$ref": "#/components/schemas/JSONDocument" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } - } - } + "required": ["document"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/restore": { - "post": { - "operationId": "restoreSpace", - "summary": "Restore a recently soft-deleted space.", - "tags": ["spaces"], - "security": [ { - "user": [] + "type": "object", + "title": "Empty", + "properties": {}, + "additionalProperties": false } - ], - "parameters": [ + ] + }, + "SearchAIAnswerSource": { + "allOf": [ { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "Space restored", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page", "capture"] } - } + }, + "required": ["type"] }, - "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": { + "discriminator": { + "propertyName": "type" + }, + "oneOf": [ + { "type": "object", - "minProperties": 1, + "title": "Page", "properties": { - "parent": { - "description": "The unique id of the parent collection", + "type": { "type": "string", - "nullable": true + "enum": ["page"] }, - "position": { - "description": "Where to move the space. By default, it will be moved at the end.", - "$ref": "#/components/schemas/ContentPosition" + "page": { + "type": "string" + }, + "revision": { + "type": "string" + }, + "space": { + "type": "string" + }, + "sections": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["type", "page", "revision", "space", "sections"] + }, + { + "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"] + } + ] + } + ] + }, + "SearchAIAnswer": { + "type": "object", + "description": "Answer from AI for a question asked on a content.", + "properties": { + "text": { + "deprecated": true, + "type": "string" + }, + "answer": { + "$ref": "#/components/schemas/Document" + }, + "followupQuestions": { + "type": "array", + "items": { + "type": "string" + } + }, + "sources": { + "type": "array", + "description": "The sources used to generate the answer.", + "items": { + "$ref": "#/components/schemas/SearchAIAnswerSource" + } + }, + "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"] } } }, - "responses": { - "200": { - "description": "Space moved", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } - } + "required": ["pages", "sources", "followupQuestions"] + }, + "SearchAIQuery": { + "type": "object", + "properties": { + "query": { + "type": "string" + }, + "previousQueries": { + "type": "array", + "deprecated": true, + "maxItems": 10, + "items": { + "type": "string" + } + } + }, + "required": ["query"] + }, + "SearchAIRecommendedQuestions": { + "type": "object", + "description": "Questions recommended by the AI for the given content.", + "properties": { + "questions": { + "type": "array", + "items": { + "type": "string" } + } + }, + "required": ["questions"] + }, + "User": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"user\"", + "enum": ["user"] }, - "400": { - "description": "Invalid position space or collection provided", - "$ref": "#/components/responses/BadRequestError" + "id": { + "type": "string", + "description": "Unique identifier for the user" }, - "404": { - "description": "No matching Space found for given ID", - "$ref": "#/components/responses/NotFoundError" + "displayName": { + "type": "string", + "description": "Full name for the user" }, - "409": { - "description": "Operation would not result in any update", - "$ref": "#/components/responses/ConflictError" + "email": { + "type": "string", + "description": "Email address of the user" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "photoURL": { + "type": "string", + "description": "URL of the user's profile picture" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the user in the API", + "format": "uri" + } + }, + "required": ["location"] } - } - } - }, - "/spaces/{spaceId}/transfer": { - "post": { - "operationId": "transferSpace", - "summary": "Transfer a space to another organization, collection or both.", - "tags": ["spaces"], - "security": [ - { - "user": [] + }, + "required": ["object", "id", "displayName", "urls"] + }, + "Timestamp": { + "type": "string", + "format": "date-time" + }, + "UserAPIToken": { + "type": "object", + "description": "The API token details, excluding the token itself.", + "properties": { + "id": { + "type": "string", + "description": "The API token ID." + }, + "label": { + "type": "string", + "description": "The API token name." + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp", + "description": "The API token creation date." } - ], - "parameters": [ + }, + "required": ["id", "label", "createdAt"] + }, + "UserAPITokenExtended": { + "description": "The API token details, including the token itself.", + "allOf": [ { - "$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"] + "$ref": "#/components/schemas/UserAPIToken" + }, + { + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "The actual token value." } - } + }, + "required": ["token"] + } + ] + }, + "SpaceTitle": { + "type": "string", + "description": "Title of the space", + "maxLength": 50 + }, + "Emoji": { + "type": "string", + "maxLength": 50, + "description": "Unicode codepoint or character of the emoji", + "example": "🎉" + }, + "ContentVisibility": { + "type": "string", + "description": "* `public`: Anyone can access the content, and the content is indexed by search engines.\n* `unlisted`: Anyone can access the content, and the content is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the content.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the content.\n* `in-collection`: Anyone who can access the parent collection can access the content.\n Only available for spaces in a collection.\n* `private`: Authorized members can access the content.\n", + "enum": [ + "public", + "unlisted", + "share-link", + "visitor-auth", + "in-collection", + "private" + ] + }, + "SpaceEditMode": { + "type": "string", + "description": "Determines how a Space can be edited.\n* `live`: Users can directly edit the space\n* `locked`: All edits are locked for this space.\n", + "enum": ["live", "locked"] + }, + "URL": { + "type": "string", + "format": "uri" + }, + "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"] + }, + "GitSyncOperation": { + "type": "object", + "properties": { + "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": "Error details, defined if state is `failure`." } }, - "responses": { - "200": { - "description": "Space transferred", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } - } - } + "required": ["state"] + }, + "GitSyncState": { + "type": "object", + "properties": { + "installationProvider": { + "type": "string", + "description": "The provider of the Git Sync installation." }, - "404": { - "description": "No matching Space found for given ID", - "$ref": "#/components/responses/NotFoundError" + "operation": { + "$ref": "#/components/schemas/GitSyncOperation" }, - "409": { - "description": "Transfer would not result in any update", - "$ref": "#/components/responses/ConflictError" + "url": { + "type": "string", + "description": "The URL to the repository tree, used when rendering public content." }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "updatedAt": { + "description": "When the Git provider details were last updated", + "$ref": "#/components/schemas/Timestamp" + } + } + }, + "VisitorAuthCustomBackend": { + "type": "object", + "title": "Custom backend for Visitor Authentication", + "properties": { + "backend": { + "type": "string", + "description": "Custom backend for Visitor Authentication", + "enum": ["custom"] + } + }, + "required": ["backend"] + }, + "VisitorAuthIntegrationBackend": { + "type": "object", + "title": "Integration backend for Visitor Authentication", + "properties": { + "backend": { + "type": "string", + "description": "Integration as backend for Visitor Authentication", + "enum": ["integration"] } - } - } - }, - "/spaces/{spaceId}/search": { - "get": { - "operationId": "searchSpaceContent", - "summary": "Search content in a space", - "security": [ + }, + "required": ["backend"] + }, + "VisitorAuth": { + "oneOf": [ { - "user": [] + "$ref": "#/components/schemas/VisitorAuthCustomBackend" + }, + { + "allOf": [ + { + "$ref": "#/components/schemas/VisitorAuthIntegrationBackend" + }, + { + "type": "object", + "properties": { + "integration": { + "type": "string", + "description": "Name of integration being used as the backend for Visitor Authentication" + } + }, + "required": ["integration"] + } + ] } - ], - "parameters": [ + ] + }, + "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": [ { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/schemas/MemberRole" }, { - "$ref": "#/components/parameters/spaceId" - }, + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "DefaultLevel": { + "description": "Default level for a piece of content", + "oneOf": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/MemberRoleOrGuest" }, { - "$ref": "#/components/parameters/listLimit" + "type": "string", + "enum": ["inherit"] } - ], - "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" - } - } - } - } - ] - } + ] + }, + "Space": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"space\"", + "enum": ["space"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the space" + }, + "title": { + "$ref": "#/components/schemas/SpaceTitle" + }, + "emoji": { + "description": "An emoji for this space. It'll match the emoji shown in the GitBook app.", + "$ref": "#/components/schemas/Emoji" + }, + "visibility": { + "$ref": "#/components/schemas/ContentVisibility" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "deletedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "editMode": { + "$ref": "#/components/schemas/SpaceEditMode" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the space in the API", + "format": "uri" + }, + "app": { + "type": "string", + "description": "URL of the space in the application", + "format": "uri" + }, + "published": { + "type": "string", + "description": "URL of the published version of the space. Only defined when visibility is not \"private.\"", + "format": "uri" + }, + "public": { + "type": "string", + "description": "URL of the public version of the space. Only defined when visibility is \"public\".", + "format": "uri" + }, + "icon": { + "description": "URL of the icon of this space, if defined.", + "$ref": "#/components/schemas/URL" } - } + }, + "required": ["app", "location"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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/VisitorAuth" + }, + "revision": { + "type": "string", + "description": "ID of the active revision in the space." + }, + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" } - } - } - }, - "/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" - } + }, + "required": [ + "object", + "id", + "type", + "title", + "emoji", + "organization", + "visibility", + "revision", + "createdAt", + "updatedAt", + "urls", + "defaultLevel" + ] + }, + "SpacePointer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["space"] }, - { - "$ref": "#/components/parameters/spaceId" + "space": { + "type": "string", + "description": "Unique identifier for the space" + } + }, + "required": ["type", "space"] + }, + "CollectionPointer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["collection"] }, - { - "$ref": "#/components/parameters/pageFormat" + "collection": { + "type": "string", + "description": "Unique identifier for the collection" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } - } + }, + "required": ["type", "collection"] + }, + "ContentPosition": { + "type": "object", + "description": "Position at which to insert an item", + "properties": { + "before": { + "oneOf": [ + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" } - } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "after": { + "oneOf": [ + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/CollectionPointer" + } + ] } } }, - "post": { - "operationId": "askQueryInSpace", - "summary": "Ask a question to an AI within the context of the space.", - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, + "IntegrationBlockMarkdown": { + "oneOf": [ { - "$ref": "#/components/parameters/pageFormat" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchAIQuery" + "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"] } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } - } - } - } + ] + }, + "IntegrationBlock": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique ID in the integration for the block. It also represents the UI component used." }, - "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" + "title": { + "type": "string", + "description": "Short descriptive title for the block.", + "minLength": 2, + "maxLength": 40 }, - { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + "description": { + "type": "string", + "description": "Long descriptive text for the block.", + "minLength": 0, + "maxLength": 150 }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "text/event-stream": { - "schema": { - "$ref": "#/components/schemas/SearchAIAnswerStream" - } - } - } + "icon": { + "type": "string", + "description": "URL of the icon to represent this block." }, - "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" - } - } + "urlUnfurl": { + "type": "array", + "description": "URLs patterns to convert as this block.", + "items": { + "type": "string" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "markdown": { + "$ref": "#/components/schemas/IntegrationBlockMarkdown" } - } - } - }, - "/spaces/{spaceId}/search/questions/stream": { - "get": { - "operationId": "streamRecommendedQuestionsInSpace", - "summary": "Stream a list of questions that can be asked in a space.", - "parameters": [ + }, + "required": ["id", "title"] + }, + "Embed": { + "allOf": [ { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "text/event-stream": { - "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" - } + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "site": { + "type": "string" + }, + "icon": { + "type": "string" } - } + }, + "required": ["title", "site"] }, - "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" + "oneOf": [ + { + "type": "object", + "title": "Link", + "properties": { + "type": { + "type": "string", + "enum": ["link"] + } + }, + "required": ["type"] + }, + { + "type": "object", + "title": "HTML", + "properties": { + "type": { + "type": "string", + "enum": ["rich"] + }, + "html": { + "type": "string" + } + }, + "required": ["type", "html"] + }, + { + "type": "object", + "title": "Integration", + "properties": { + "type": { + "type": "string", + "enum": ["integration"] + }, + "integration": { + "description": "The identifier of the integration performing the rendering", + "type": "string" + }, + "block": { + "$ref": "#/components/schemas/IntegrationBlock" + } + }, + "required": ["type", "integration", "block"] + } + ] } - ], - "responses": { - "204": { - "description": "Operation to import the repository has been started." + ] + }, + "SearchAIAnswerStream": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["answer"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "answer": { + "$ref": "#/components/schemas/SearchAIAnswer" } }, - "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" + "required": ["type"] + }, + "SearchAIRecommendedQuestionStream": { + "type": "object", + "properties": { + "question": { + "type": "string" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestExportToGitRepository" - } - } + "required": ["question"] + }, + "UpdateSpaceGitInfo": { + "type": "object", + "description": "Update metadata about the Git provider on the space", + "properties": { + "provider": { + "type": "string", + "description": "The git provider", + "enum": ["github", "gitlab"] + }, + "url": { + "type": "string", + "description": "The repository's tree URL" } } - } - }, - "/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." + }, + "ImportGitRepository": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL of the Git repository to import. It can contain basic auth credentials." }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "ref": { + "type": "string", + "description": "Git ref to import in the format \"refs/heads/main\"" + }, + "repoCacheID": { + "type": "string", + "description": "Unique identifier to use to cache the Git repository across multiple operations." + }, + "repoTreeURL": { + "type": "string", + "description": "URL to use as a prefix for external file references." + }, + "repoCommitURL": { + "type": "string", + "description": "URL to use as a prefix for the commit URL." + }, + "repoProjectDirectory": { + "type": "string", + "description": "Path to a root directory for the project in the repository." + }, + "timestamp": { + "description": "The timestamp of the event that triggered this import. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.\n", + "$ref": "#/components/schemas/Timestamp" + }, + "force": { + "type": "boolean" + }, + "standalone": { + "type": "boolean", + "description": "If true, the import will generate a revision without updating the space primary content." + }, + "gitInfo": { + "description": "Optional metadata to store on the space about the Git provider", + "$ref": "#/components/schemas/UpdateSpaceGitInfo" } }, - "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" - } - } - } + "required": ["url", "ref"] + }, + "ExportToGitRepository": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL of the Git repository to export to. It can contain basic auth credentials." }, - "404": { - "description": "No Git provider currently set up on the space", - "$ref": "#/components/responses/NotFoundError" + "ref": { + "type": "string", + "description": "Git ref to push the commit to in the format \"refs/heads/main\"" }, - "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" + "commitMessage": { + "type": "string", + "description": "Message for the commit generated by the export" + }, + "repoCacheID": { + "type": "string", + "description": "Unique identifier to use to cache the Git repository across multiple operations." + }, + "repoTreeURL": { + "type": "string", + "description": "URL to use as a prefix for external file references." + }, + "repoCommitURL": { + "type": "string", + "description": "URL to use as a prefix for the commit URL." + }, + "repoProjectDirectory": { + "type": "string", + "description": "Path to a root directory for the project in the repository." + }, + "timestamp": { + "description": "The timestamp of the event that triggered this export. It ensures that Git sync import and export operations are executed in the same order on GitBook and on the remote repository.\n", + "$ref": "#/components/schemas/Timestamp" + }, + "force": { + "type": "boolean" + }, + "gitInfo": { + "description": "Optional metadata to store on the space about the Git provider", + "$ref": "#/components/schemas/UpdateSpaceGitInfo" } - ], - "responses": { - "200": { - "description": "Content analytics per page.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsContentPages" - } - } - } + }, + "required": ["url", "ref", "commitMessage"] + }, + "SyncGitRepository": { + "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." }, - "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" + "commitMessageTemplate": { + "type": "string", + "description": "Template message for the commit generated during the synchronization." }, - { - "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" - } + "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"] }, - "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" + "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" }, - { - "name": "interval", - "required": false, - "in": "query", - "schema": { - "$ref": "#/components/schemas/AnalyticsTrafficInterval" - } + "gitInfo": { + "description": "Optional metadata to store on the space about the Git provider", + "$ref": "#/components/schemas/UpdateSpaceGitInfo" } - ], - "responses": { - "200": { - "description": "Traffic over time for the given space.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsTrafficPageViews" - } - } - } + }, + "required": [ + "ref", + "repoURL", + "repoTreeURL", + "repoCommitURL", + "commitMessageTemplate" + ] + }, + "Icon": { + "type": "string", + "maxLength": 50, + "description": "Name of the icon", + "example": "gear" + }, + "RevisionPageBase": { + "type": "object", + "properties": { + "id": { + "description": "Unique identifier for the page in the revision", + "type": "string" }, - "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." + "title": { + "description": "Title of the page", + "type": "string", + "maxLength": 100 }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "emoji": { + "description": "Emoji of the page, if one has been set.", + "$ref": "#/components/schemas/Emoji" + }, + "icon": { + "description": "Icon of the page, if one has been set.", + "$ref": "#/components/schemas/Icon" + }, + "createdAt": { + "description": "When the page was first created. Only present if page has been edited at least once.", + "$ref": "#/components/schemas/Timestamp" + }, + "updatedAt": { + "description": "When the page was last edited. Only present if page has been edited at least once.", + "$ref": "#/components/schemas/Timestamp" } }, - "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": [ + "required": ["id", "title"] + }, + "RevisionPageDocument": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/RevisionPageBase" + }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/Document" }, { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Revision" + "type": "object", + "properties": { + "kind": { + "type": "string", + "deprecated": true, + "enum": ["sheet"] + }, + "type": { + "type": "string", + "enum": ["document"] + }, + "urls": { + "required": ["app"], + "properties": { + "app": { + "description": "Location of the page in the app", + "$ref": "#/components/schemas/URL" + } + } + }, + "slug": { + "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" + }, + "hidden": { + "type": "boolean", + "description": "If true, the page is not displayed in the navigation, while still being accessible.", + "default": false + }, + "noIndex": { + "type": "boolean", + "description": "If true, the page is not indexable in the search and ask features.", + "default": false + }, + "noRobotsIndex": { + "type": "boolean", + "description": "If true, the page is not indexable by search engine robots.", + "default": false } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["kind", "type", "urls", "slug", "path", "pages", "layout"] } - } - } - }, - "/spaces/{spaceId}/content/import": { - "post": { - "summary": "Import content in a space.", - "operationId": "importContent", - "security": [ + ] + }, + "RevisionPageLink": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/RevisionPageBase" + }, { - "$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" - } + "type": "object", + "properties": { + "kind": { + "type": "string", + "deprecated": true, + "enum": ["link"] + }, + "type": { + "type": "string", + "enum": ["link"] + }, + "target": { + "$ref": "#/components/schemas/ContentRef" + }, + "href": { + "type": "string" + }, + "hidden": { + "type": "boolean", + "description": "If true, the page is not displayed in the navigation, while still being accessible.", + "default": false } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ImportContentResult" - } - } - } + "required": ["kind", "type", "target"] + } + ] + }, + "GitSyncBlob": { + "type": "object", + "properties": { + "oid": { + "type": "string", + "description": "SHA for the blob" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "path": { + "type": "string", + "description": "Path of the blob in the Git tree" } }, - "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" + "required": ["oid", "path"] + }, + "RevisionPageLayoutOptionsCoverSize": { + "type": "string", + "description": "Size of the cover image.", + "enum": ["hero", "full"] + }, + "RevisionPageLayoutOptions": { + "type": "object", + "properties": { + "cover": { + "type": "boolean", + "description": "Should the cover be visible?" }, - { - "$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"] - } - } - } + "coverSize": { + "$ref": "#/components/schemas/RevisionPageLayoutOptionsCoverSize" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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?" } } - } - }, - "/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" + }, + "RevisionPageDocumentCover": { + "type": "object", + "properties": { + "ref": { + "description": "Content reference pointing to the source image.", + "$ref": "#/components/schemas/ContentRefFile" }, - { - "$ref": "#/components/parameters/listPage" + "yPos": { + "description": "Vertical position of the cover image.", + "type": "number" + } + }, + "required": ["yPos"] + }, + "AnalyticsContentPage": { + "type": "object", + "description": "Page entry in the content analytics.", + "required": ["page", "pageViews"], + "properties": { + "page": { + "$ref": "#/components/schemas/RevisionPageDocument" }, - { - "$ref": "#/components/parameters/listLimit" + "pageViews": { + "type": "number" }, - { - "$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" - } - } - } - } - ] - } + "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." } } - }, - "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": [] + }, + "AnalyticsContentPages": { + "type": "object", + "required": ["pages"], + "properties": { + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AnalyticsContentPage" + } } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + } + }, + "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" }, - { - "$ref": "#/components/parameters/fileId" + "searches": { + "description": "Number of searches done by users.", + "type": "number" }, - { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionFile" - } - } - } + "hits": { + "description": "Number of objects matching this search.", + "type": "number" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "pageHits": { + "description": "Number of pages matching this search.", + "type": "number" + }, + "sectionHits": { + "description": "Number of sections matching this search.", + "type": "number" } } - } - }, - "/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" + }, + "AnalyticsTopSearches": { + "type": "object", + "description": "Top search queries for a content.", + "required": ["searches", "queries"], + "properties": { + "searches": { + "description": "Number of searches done by users.", + "type": "number" }, - { - "$ref": "#/components/parameters/revisionMetadata" + "queries": { + "description": "Top queries searched for this content.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AnalyticsSearchQuery" + } } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionPage" + } + }, + "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" + }, + "views": { + "description": "Page views per interval (day, week, month).", + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "string" + }, + "count": { + "type": "number" } - } + }, + "required": ["timestamp", "count"] } - }, - "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" + }, + "SpaceTrackPageView": { + "type": "object", + "properties": { + "pageId": { + "type": "string", + "description": "Unique identifier of the page." }, - { - "$ref": "#/components/parameters/pageId" - } - ], - "responses": { - "201": { - "description": "Content imported in a new revision", - "headers": { - "Location": { - "description": "API URL for the newly created revision", - "schema": { + "visitor": { + "type": "object", + "description": "Analytics info on the GitBook's content visitor.", + "properties": { + "anonymousId": { + "type": "string", + "description": "GitBook's unique identifier of the visitor." + }, + "cookies": { + "type": "object", + "description": "The visitors cookies.", + "additionalProperties": { "type": "string" } + }, + "ip": { + "type": "string", + "description": "IP address of the visitor.\nIf undefined, it'll default to the IP executing the request.\n" + }, + "userAgent": { + "type": "string", + "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" + }, + "language": { + "type": "string", + "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ImportContentResult" - } - } - } + "required": ["anonymousId", "cookies", "userAgent"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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." } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestImportContent" - } + "required": ["visitor", "url", "referrer"] + }, + "InviteEmailsUsersTeamsToSpace": { + "type": "object", + "properties": { + "teams": { + "type": "array", + "items": { + "type": "string", + "description": "The ID of the team to be invited" } - } - } - } - }, - "/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" }, + "role": { + "description": "Role to set on the team.", + "$ref": "#/components/schemas/MemberRoleOrGuest" + } + }, + "required": ["teams", "role"] + }, + "RevisionPageGroup": { + "allOf": [ { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/schemas/RevisionPageBase" }, { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "deprecated": true, + "enum": ["group"] + }, + "type": { + "type": "string", + "enum": ["group"] + }, + "slug": { + "description": "Page's slug in its direct parent", + "type": "string" + }, + "path": { + "description": "Complete path to access the page in the revision.", + "type": "string" + }, + "hidden": { + "type": "boolean", + "description": "If true, the page is not displayed in the navigation, while still being accessible.", + "default": false + }, + "noIndex": { + "type": "boolean", + "description": "If true, the page is not indexable in the search and ask features.", + "default": false + }, + "noRobotsIndex": { + "type": "boolean", + "description": "If true, the page is not indexable by search engine robots.", + "default": false + }, + "pages": { + "type": "array", + "items": { "oneOf": [ { "$ref": "#/components/schemas/RevisionPageDocument" }, { - "$ref": "#/components/schemas/RevisionPageGroup" + "$ref": "#/components/schemas/RevisionPageLink" } ] } } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/documents/{documentId}": { - "get": { - "operationId": "getDocumentById", - "summary": "Get a document by its ID in a space.", - "security": [ - { - "user": [] + }, + "required": ["kind", "type", "slug", "path", "pages"] } - ], - "parameters": [ + ] + }, + "RevisionPage": { + "oneOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionPageDocument" }, { - "name": "documentId", - "in": "path", - "required": true, - "description": "ID of the document in the space", - "schema": { - "type": "string" - } + "$ref": "#/components/schemas/RevisionPageGroup" }, { - "$ref": "#/components/parameters/documentSchema" + "$ref": "#/components/schemas/RevisionPageLink" } ], - "responses": { - "200": { - "description": "Document", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/JSONDocument" - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } + "discriminator": { + "propertyName": "type" } - } - }, - "/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" - } + }, + "RevisionFile": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "contentType": { + "type": "string" + }, + "downloadURL": { + "type": "string" + }, + "size": { + "type": "number" + }, + "dimensions": { + "type": "object", + "description": "For images, it contains the dimensions of it.", + "properties": { + "width": { + "type": "number" + }, + "height": { + "type": "number" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChangeRequest" - } - } - } + "required": ["width", "height"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "git": { + "$ref": "#/components/schemas/GitSyncBlob" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestCreateChangeRequest" - } + "required": ["id", "name", "contentType", "downloadURL", "size"] + }, + "GitSyncCommit": { + "type": "object", + "properties": { + "oid": { + "type": "string", + "description": "SHA for the commit" + }, + "message": { + "type": "string", + "description": "Message describing the purpose of the commit" + }, + "createdByGitBook": { + "type": "boolean", + "description": "If true, the Git commit was generated by an export from GitBook" + }, + "url": { + "type": "string", + "description": "URL of the commit in the GitSync provider" + }, + "ref": { + "type": "string", + "description": "Original name of the ref where the commit originated from" + } + }, + "required": ["oid", "message", "createdByGitBook"] + }, + "RevisionBase": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"revision\"", + "enum": ["revision"] + }, + "id": { + "description": "Unique identifier for the revision", + "type": "string" + }, + "parents": { + "description": "IDs of the parent revisions", + "type": "array", + "items": { + "type": "string" + } + }, + "pages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionPage" + } + }, + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionFile" } + }, + "createdAt": { + "description": "When the revision was created.", + "$ref": "#/components/schemas/Timestamp" + }, + "git": { + "description": "Metadata about a potential associated git commit.", + "$ref": "#/components/schemas/GitSyncCommit" + }, + "urls": { + "type": "object", + "properties": { + "app": { + "type": "string", + "format": "uri", + "description": "URL in the application for the revision" + }, + "published": { + "type": "string", + "description": "URL of the published version of the revision. Only defined when the space visibility is not \"private.\"", + "format": "uri" + }, + "public": { + "type": "string", + "description": "URL of the public version of the revision. Only defined when the space visibility is \"public\".", + "format": "uri" + } + }, + "required": ["app"] } - } + }, + "required": ["object", "id", "parents", "pages", "files", "urls", "createdAt"] }, - "get": { - "operationId": "listChangeRequestsForSpace", - "summary": "List change requests for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" - }, + "RevisionTypeEdits": { + "allOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionBase" }, { - "name": "status", - "in": "query", - "required": false, - "schema": { - "$ref": "#/components/schemas/ChangeRequestStatus", - "default": "open" + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Revision created by editing the content.", + "enum": ["edits"] + } }, - "description": "If defined, only change requests matching this status will be returned" + "required": ["type"] } - ], - "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" - } - } - } - } - ] - } - } - } + ] + }, + "ChangeRequestStatus": { + "type": "string", + "enum": ["draft", "open", "archived", "merged"] + }, + "ChangeRequestSubject": { + "type": "string", + "description": "Subject of the change request", + "minLength": 0, + "maxLength": 100 + }, + "ChangeRequest": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"change-request\"", + "enum": ["change-request"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}": { - "get": { - "operationId": "getChangeRequestById", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "id": { + "type": "string", + "description": "Unique identifier for the change request" }, - { - "$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" - } - } - } + "number": { + "type": "number", + "description": "Incremental identifier of the change request" }, - "404": { - "description": "The change request could not be found.", - "$ref": "#/components/responses/NotFoundError" + "status": { + "$ref": "#/components/schemas/ChangeRequestStatus" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "subject": { + "$ref": "#/components/schemas/ChangeRequestSubject" + }, + "createdBy": { + "$ref": "#/components/schemas/User" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "revision": { + "type": "string", + "description": "ID of the active revision in the change request." + }, + "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" + ] }, - "patch": { - "operationId": "updateChangeRequestById", - "summary": "Update the details of a change request", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ + "RevisionTypeMerge": { + "allOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionBase" }, { - "$ref": "#/components/parameters/changeRequestId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/ChangeRequestSubject" - } - } + "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"] } - }, - "responses": { - "200": { - "description": "The change request has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChangeRequest" - } - } - } + ] + }, + "RevisionTypeRollback": { + "allOf": [ + { + "$ref": "#/components/schemas/RevisionBase" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Revision created as a rollback of a previous revision.", + "enum": ["rollback"] + } + }, + "required": ["type"] } - } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/merge": { - "post": { - "operationId": "mergeChangeRequest", - "summary": "Merge a change request in the primary content of a space.", - "tags": ["spaces"], - "security": [ + ] + }, + "RevisionTypeUpdate": { + "allOf": [ { - "user": [] + "$ref": "#/components/schemas/RevisionBase" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Revision created when updating a change request with changes from primary.", + "enum": ["update"] + } + }, + "required": ["type"] } - ], - "parameters": [ + ] + }, + "Revision": { + "oneOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionTypeEdits" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/schemas/RevisionTypeMerge" + }, + { + "$ref": "#/components/schemas/RevisionTypeRollback" + }, + { + "$ref": "#/components/schemas/RevisionTypeUpdate" } ], - "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"] - } - } - } + "discriminator": { + "propertyName": "type" + } + }, + "ImportContentSource": { + "type": "string", + "enum": [ + "website", + "docx", + "markdown", + "html", + "zip", + "confluence", + "github-wiki", + "dropbox-paper", + "notion", + "quip", + "google-docs", + "open-api" + ] + }, + "ImportContent": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "URL of the content to import." }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "source": { + "$ref": "#/components/schemas/ImportContentSource" + } + }, + "required": ["url", "source"] + }, + "ImportContentResult": { + "type": "object", + "required": ["revision", "importedResources", "totalResources"], + "properties": { + "revision": { + "type": "string", + "description": "ID of the newly created revision." + }, + "importedResources": { + "type": "number", + "description": "How many resources were imported" + }, + "totalResources": { + "type": "number", + "description": "How many resources were processed" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/update": { - "post": { - "operationId": "updateChangeRequest", - "summary": "Update a change-request with changes from primary content.", - "tags": ["spaces"], - "security": [ - { - "user": [] + }, + "OrganizationTitle": { + "type": "string", + "description": "Name of the organization", + "minLength": 2, + "maxLength": 255 + }, + "OrganizationEmailDomains": { + "type": "array", + "items": { + "type": "string" + } + }, + "OrganizationHostname": { + "type": "string", + "description": "Default hostname for the organization's public content, e.g. .gitbook.io", + "minLength": 3, + "maxLength": 32 + }, + "OrganizationType": { + "type": "string", + "enum": ["business", "community"] + }, + "OrganizationUseCase": { + "type": "string", + "enum": [ + "internalDocs", + "docsSite", + "audienceControlledSite", + "productDocs", + "teamKnowledgeBase", + "designSystem", + "openSourceDocs", + "notes", + "other" + ] + }, + "OrganizationCommunityType": { + "type": "string", + "enum": ["nonProfit", "openSource", "education"] + }, + "SitePointer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["site"] + }, + "site": { + "type": "string", + "description": "Unique identifier for the site" } - ], - "parameters": [ + }, + "required": ["type", "site"] + }, + "OrganizationDefaultContent": { + "description": "The default content for the organization", + "oneOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/SpacePointer" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/schemas/CollectionPointer" + }, + { + "$ref": "#/components/schemas/SitePointer" } - ], - "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"] - } + ] + }, + "Organization": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"organization\"", + "enum": ["organization"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the organization" + }, + "title": { + "$ref": "#/components/schemas/OrganizationTitle" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "emailDomains": { + "$ref": "#/components/schemas/OrganizationEmailDomains" + }, + "hostname": { + "$ref": "#/components/schemas/OrganizationHostname" + }, + "type": { + "$ref": "#/components/schemas/OrganizationType" + }, + "useCase": { + "$ref": "#/components/schemas/OrganizationUseCase" + }, + "communityType": { + "$ref": "#/components/schemas/OrganizationCommunityType" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "defaultContent": { + "$ref": "#/components/schemas/OrganizationDefaultContent" + }, + "sso": { + "description": "Whether SSO is enforced organization wide", + "type": "boolean" + }, + "ai": { + "description": "If true, the organization is configured to use all our AI features.", + "type": "boolean" + }, + "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": ["object", "id", "title", "createdAt", "type", "emailDomains", "urls"] + }, + "ContentLocationRevisionContext": { + "type": "object", + "required": ["type", "revision"], + "properties": { + "type": { + "type": "string", + "enum": ["revision"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "revision": { + "$ref": "#/components/schemas/Revision" } } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/reviews": { - "get": { - "operationId": "getReviewsByChangeRequestId", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "ContentLocationChangeRequestContext": { + "type": "object", + "required": ["type", "changeRequest"], + "properties": { + "type": { + "type": "string", + "enum": ["changeRequest"] }, - { - "$ref": "#/components/parameters/changeRequestId" + "changeRequest": { + "$ref": "#/components/schemas/ChangeRequest" + } + } + }, + "ContentLocationFile": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["file"] }, - { - "$ref": "#/components/parameters/pageFormat" + "organization": { + "$ref": "#/components/schemas/Organization" }, - { - "$ref": "#/components/parameters/listPage" + "space": { + "$ref": "#/components/schemas/Space" }, - { - "$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" - } - } - } - } - ] - } + "versionContext": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentLocationRevisionContext" + }, + { + "$ref": "#/components/schemas/ContentLocationChangeRequestContext" } - } - }, - "404": { - "description": "The change request or space could not be found.", - "$ref": "#/components/responses/NotFoundError" + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "file": { + "$ref": "#/components/schemas/RevisionFile" } - } + }, + "required": ["kind", "organization", "space", "file"] }, - "post": { - "operationId": "submitChangeRequestReview", - "tags": ["spaces"], - "security": [ - { - "user": [] + "ContentLocationURL": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["url"] + }, + "url": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["kind", "url"] + }, + "ContentLocationPageAnchor": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["anchor"] }, - { - "$ref": "#/components/parameters/changeRequestId" + "anchor": { + "description": "The anchor within the page.", + "type": "string" } - ], - "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" - } - } - } + }, + "required": ["type", "anchor"] + }, + "ContentLocationPageNode": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["node"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "node": { + "description": "The node id within the page.", + "type": "string" } }, - "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"] + "required": ["type", "node"] + }, + "ContentLocationPage": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["page"] + }, + "organization": { + "$ref": "#/components/schemas/Organization" + }, + "page": { + "$ref": "#/components/schemas/RevisionPage" + }, + "space": { + "$ref": "#/components/schemas/Space" + }, + "versionContext": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentLocationRevisionContext" + }, + { + "$ref": "#/components/schemas/ContentLocationChangeRequestContext" } - } + ] + }, + "internalLocation": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentLocationPageAnchor" + }, + { + "$ref": "#/components/schemas/ContentLocationPageNode" + } + ] } - } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/requested-reviewers": { - "get": { - "operationId": "getRequestedReviewersByChangeRequestId", - "summary": "Get all requested reviewers for a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] + }, + "required": ["kind", "organization", "space", "page"] + }, + "ContentLocationUser": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["user"] + }, + "user": { + "$ref": "#/components/schemas/User" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["kind", "user"] + }, + "CollectionTitle": { + "type": "string", + "description": "Title of the collection", + "maxLength": 50 + }, + "CollectionDescription": { + "type": "string", + "description": "Description of the collection", + "minLength": 0, + "maxLength": 100 + }, + "Collection": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"collection\"", + "enum": ["collection"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the collection" + }, + "title": { + "$ref": "#/components/schemas/CollectionTitle" + }, + "description": { + "$ref": "#/components/schemas/CollectionDescription" + }, + "path": { + "type": "string", + "description": "Path in the published URL" + }, + "visibility": { + "$ref": "#/components/schemas/ContentVisibility" }, - { - "$ref": "#/components/parameters/changeRequestId" + "publishingType": { + "type": "string", + "enum": ["variants"] }, - { - "$ref": "#/components/parameters/listPage" + "organization": { + "type": "string", + "description": "ID of the organization owning this collection" }, - { - "$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" - } - } - } - } - ] - } - } - } + "parent": { + "type": "string", + "description": "ID of the parent collection, if any" }, - "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" + "collection": { + "type": "string", + "deprecated": true, + "description": "ID of the parent collection, if any" }, - { - "$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" - } - } - } - } - } - } + "defaultLevel": { + "$ref": "#/components/schemas/DefaultLevel" }, - "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"] + "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" } - } - } - } - } - }, - "/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": [] + }, + "required": ["app", "location"] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + }, + "required": [ + "object", + "id", + "title", + "organization", + "visibility", + "urls", + "defaultLevel" + ] + }, + "ContentLocationCollection": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["collection"] }, - { - "$ref": "#/components/parameters/listPage" + "organization": { + "$ref": "#/components/schemas/Organization" }, - { - "$ref": "#/components/parameters/listLimit" + "collection": { + "$ref": "#/components/schemas/Collection" + } + }, + "required": ["kind", "organization", "collection"] + }, + "ContentLocationSpace": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["space"] }, - { - "name": "status", - "in": "query", - "required": false, - "schema": { - "$ref": "#/components/schemas/ContentReferenceStatus" - } + "organization": { + "$ref": "#/components/schemas/Organization" }, - { - "name": "brokenContext", - "in": "query", - "required": false, - "schema": { - "type": "string", - "enum": ["change-request", "space"] - } + "space": { + "$ref": "#/components/schemas/Space" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ + }, + "required": ["kind", "organization", "space"] + }, + "IntegrationTitle": { + "type": "string", + "description": "Title of the integration", + "minLength": 2, + "maxLength": 30 + }, + "IntegrationDescription": { + "type": "string", + "description": "Description of the integration", + "maxLength": 100 + }, + "IntegrationSummary": { + "type": "string", + "description": "Long form markdown summary of the integration", + "maxLength": 2048 + }, + "IntegrationTarget": { + "type": "string", + "enum": ["organization", "all"] + }, + "IntegrationVisibility": { + "type": "string", + "enum": ["public", "private", "unlisted"] + }, + "IntegrationScope": { + "type": "string", + "enum": [ + "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:metadata:read", + "site:views:read", + "site:script:inject", + "site:script:cookies", + "site:visitor:auth" + ] + }, + "IntegrationScopes": { + "type": "array", + "description": "Permissions that should be granted to the integration", + "items": { + "$ref": "#/components/schemas/IntegrationScope" + } + }, + "IntegrationCategory": { + "type": "string", + "enum": [ + "analytics", + "captures", + "collaboration", + "content", + "gitsync", + "marketing", + "visitor-auth", + "other" + ] + }, + "IntegrationCategories": { + "type": "array", + "description": "Categories for which the integration is listed in the marketplace", + "items": { + "$ref": "#/components/schemas/IntegrationCategory" + } + }, + "IntegrationBlocks": { + "type": "array", + "description": "Custom blocks defined by this integration.", + "items": { + "$ref": "#/components/schemas/IntegrationBlock" + } + }, + "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": [ { - "$ref": "#/components/schemas/List" + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["string"] + }, + "default": { + "type": "string" + } + }, + "required": ["type"] }, { "type": "object", "properties": { - "stats": { - "$ref": "#/components/schemas/ContentReferencesStats" + "type": { + "type": "string", + "enum": ["number"] }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentReferenceUsage" - } + "default": { + "type": "number" } }, - "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": [ + "required": ["type"] + }, { - "$ref": "#/components/schemas/List" + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["boolean"] + }, + "default": { + "type": "boolean" + } + }, + "required": ["type"] }, { "type": "object", - "required": ["items"], "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Comment" - } + "type": { + "type": "string", + "enum": ["button"] + }, + "callback_url": { + "type": "string" + }, + "button_text": { + "type": "string" } - } + }, + "required": ["type", "callback_url", "button_text"] } ] } - } - } - }, - "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" + "required": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string" + } } - } + }, + "required": ["properties"] }, - "delete": { - "operationId": "deleteCommentInChangeRequest", - "summary": "Delete a comment in a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "IntegrationConfigurationComponent": { + "type": "object", + "description": "ContentKit component for configuration", + "properties": { + "componentId": { + "type": "string", + "description": "ID of the ContentKit component defined in the integration" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, + }, + "required": ["componentId"] + }, + "IntegrationConfiguration": { + "oneOf": [ { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/schemas/IntegrationConfigurationSchema" }, { - "$ref": "#/components/parameters/commentId" - } - ], - "responses": { - "205": { - "description": "The comment has been deleted." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "$ref": "#/components/schemas/IntegrationConfigurationComponent" } - } + ] }, - "put": { - "operationId": "updateCommentInChangeRequest", - "summary": "Update a comment in a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "IntegrationConfigurations": { + "type": "object", + "properties": { + "account": { + "$ref": "#/components/schemas/IntegrationConfiguration" }, - { - "$ref": "#/components/parameters/changeRequestId" + "space": { + "$ref": "#/components/schemas/IntegrationConfiguration" }, - { - "$ref": "#/components/parameters/commentId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" - } - } + "site": { + "$ref": "#/components/schemas/IntegrationConfiguration" } - }, - "responses": { - "200": { - "description": "The comment was updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Comment" - } - } + } + }, + "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" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } + "required": ["url", "label"] } - } - }, - "/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" - }, + }, + "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": [ { - "$ref": "#/components/parameters/listLimit" + "type": "string" }, { - "$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" - } - } - } - } - ] - } + "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" } } - }, - "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" + "Integration": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["integration"] }, - { - "$ref": "#/components/parameters/changeRequestId" + "name": { + "type": "string", + "description": "Unique named identifier for the integration" }, - { - "$ref": "#/components/parameters/commentId" + "version": { + "type": "number", + "description": "Version of the integration" }, - { - "$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" - } - } + "title": { + "$ref": "#/components/schemas/IntegrationTitle" + }, + "description": { + "$ref": "#/components/schemas/IntegrationDescription" + }, + "summary": { + "$ref": "#/components/schemas/IntegrationSummary" + }, + "previewImages": { + "type": "array", + "description": "URLs of images to showcase the integration", + "maxItems": 3, + "items": { + "type": "string" } }, - "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" + "target": { + "$ref": "#/components/schemas/IntegrationTarget" }, - { - "$ref": "#/components/parameters/changeRequestId" + "verified": { + "type": "boolean", + "description": "If true, the integration has been verified by the GitBook team" }, - { - "$ref": "#/components/parameters/commentId" + "visibility": { + "$ref": "#/components/schemas/IntegrationVisibility" }, - { - "$ref": "#/components/parameters/commentReplyId" + "scopes": { + "$ref": "#/components/schemas/IntegrationScopes" }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "The returned comment reply.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CommentReply" - } - } - } + "categories": { + "$ref": "#/components/schemas/IntegrationCategories" }, - "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" + "blocks": { + "$ref": "#/components/schemas/IntegrationBlocks" }, - { - "$ref": "#/components/parameters/changeRequestId" + "configurations": { + "$ref": "#/components/schemas/IntegrationConfigurations" }, - { - "$ref": "#/components/parameters/commentId" + "externalLinks": { + "$ref": "#/components/schemas/IntegrationExternalLinks" }, - { - "$ref": "#/components/parameters/commentReplyId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" + "owner": { + "$ref": "#/components/schemas/Organization" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the integration in the API", + "format": "uri" + }, + "icon": { + "type": "string", + "description": "URL of the icon associated to the integration", + "format": "uri" + }, + "app": { + "type": "string", + "description": "URL of the integration in the application", + "format": "uri" + }, + "assets": { + "type": "string", + "description": "URL of the integration's assets.", + "format": "uri" + }, + "publicEndpoint": { + "type": "string", + "description": "Public HTTP endpoint for the integration", + "format": "uri" } - } - } - }, - "responses": { - "200": { - "description": "The reply was updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CommentReply" - } + }, + "required": ["location", "app", "assets", "publicEndpoint"] + }, + "permissions": { + "type": "object", + "description": "The set of permissions for the integration", + "properties": { + "admin": { + "type": "boolean" } - } + }, + "required": ["admin"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "contentSecurityPolicy": { + "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" } - } + }, + "required": [ + "object", + "name", + "version", + "title", + "scopes", + "categories", + "visibility", + "target", + "verified", + "previewImages", + "externalLinks", + "owner", + "permissions", + "urls" + ] }, - "delete": { - "operationId": "deleteCommentReplyInChangeRequest", - "summary": "Delete a comment reply in a change request.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "Snippet": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the snippet" + }, + "organization": { + "type": "string", + "description": "ID of the organization owning this snippet" + }, + "createdAt": { + "type": "string", + "format": "date-time" }, - { - "$ref": "#/components/parameters/changeRequestId" + "editedAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp of when the snippet was last edited, if it has been edited since its creation." }, - { - "$ref": "#/components/parameters/commentId" + "archived": { + "type": "boolean", + "description": "Whether the snippet is archived. Archived snippets don't appear in search results or in the app." }, - { - "$ref": "#/components/parameters/commentReplyId" - } - ], - "responses": { - "205": { - "description": "The comment has been deleted." + "title": { + "type": "string", + "description": "Title describing the snippet.", + "maxLength": 100 }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/change-requests/{changeRequestId}/contributors": { - "get": { - "operationId": "getContributorsByChangeRequestId", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "source": { + "description": "The source of the snippet.", + "type": "object", + "properties": { + "sourceId": { + "type": "string", + "description": "An ID identifying the source, unique across all sources." + }, + "name": { + "type": "string", + "description": "A display name for the source." + }, + "externalId": { + "type": "string", + "description": "An ID identifying the snippet in the source system, if available." + }, + "externalUrl": { + "description": "URL of the snippet in the source system, if available.", + "$ref": "#/components/schemas/URL" + } + }, + "required": ["sourceId", "name"] }, - { - "$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" - } - } - } - } - ] + "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" } - } + ] } }, - "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": [] + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "description": "URL of the snippet in the API", + "$ref": "#/components/schemas/URL" + }, + "app": { + "description": "URL of the snippet in the app", + "$ref": "#/components/schemas/URL" + } + }, + "required": ["location", "app"] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": [ + "id", + "organization", + "source", + "createdAt", + "archived", + "contributors", + "urls" + ] + }, + "ContentLocationSnippet": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["snippet"] }, - { - "$ref": "#/components/parameters/changeRequestId" + "organization": { + "$ref": "#/components/schemas/Organization" }, - { - "$ref": "#/components/parameters/revisionMetadata" + "snippet": { + "$ref": "#/components/schemas/Snippet" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Revision" - } - } - } + }, + "required": ["kind", "organization", "snippet"] + }, + "SyncedBlock": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the synced block" }, - "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" + "organization": { + "type": "string", + "description": "ID of the organization owning this synced block" }, - { - "$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" - } + "createdAt": { + "type": "string", + "format": "date-time" + }, + "title": { + "type": "string", + "description": "Title describing the synced block.", + "maxLength": 100 + }, + "usage": { + "type": "object", + "description": "Usage of synced block", + "properties": { + "spaces": { + "description": "Number of spaces where the synced block is used in", + "type": "integer" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ImportContentResult" - } + "required": ["spaces"] + }, + "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", "organization", "source", "createdAt", "usage", "urls"] + }, + "ContentLocationSyncedBlock": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["synced-block"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "organization": { + "$ref": "#/components/schemas/Organization" + }, + "syncedBlock": { + "$ref": "#/components/schemas/SyncedBlock" } }, - "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": [ + "required": ["kind", "organization", "syncedBlock"] + }, + "ContentLocation": { + "description": "An absolute reference to content in GitBook.", + "oneOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/ContentLocationFile" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/schemas/ContentLocationURL" }, { - "$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"] - } - } - } + "$ref": "#/components/schemas/ContentLocationPage" }, - "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/schemas/ContentLocationUser" }, { - "$ref": "#/components/parameters/changeRequestId" + "$ref": "#/components/schemas/ContentLocationCollection" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/ContentLocationSpace" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/ContentLocationSnippet" }, { - "$ref": "#/components/parameters/revisionMetadata" + "$ref": "#/components/schemas/ContentLocationSyncedBlock" } ], - "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" - } + "discriminator": { + "propertyName": "kind" } - } - }, - "/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": [] + }, + "CreateChangeRequest": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "Subject of the change-request" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/changeRequestId" + } + }, + "ChangeRequestReviewStatus": { + "type": "string", + "description": "Status of a change request review.", + "enum": ["changes-requested", "approved"] + }, + "EmojiReaction": { + "type": "object", + "description": "An emoji reaction by one or many users", + "properties": { + "emoji": { + "type": "string", + "description": "The Emoji of the reaction" }, - { - "$ref": "#/components/parameters/fileId" + "count": { + "type": "number", + "description": "The number of users who reacted with this emoji" }, - { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionFile" + "users": { + "type": "array", + "description": "The users who reacted with this emoji", + "items": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/User" + }, + "reactedAt": { + "$ref": "#/components/schemas/Timestamp" } + }, + "required": ["user", "reactedAt"] + } + } + }, + "required": ["emoji", "count", "users"] + }, + "EmojiReactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EmojiReaction" + } + }, + "Comment": { + "allOf": [ + { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"comment\"", + "enum": ["comment"] + }, + "id": { + "description": "Unique identifier for the comment.", + "type": "string" + }, + "postedBy": { + "description": "The user who posted the comment.", + "$ref": "#/components/schemas/User" + }, + "postedAt": { + "description": "When the comment was posted.", + "$ref": "#/components/schemas/Timestamp" + }, + "editedAt": { + "description": "Date when the comment was edited, if it has been edited.", + "$ref": "#/components/schemas/Timestamp" + }, + "reactions": { + "description": "Any emoji reactions to the comment.", + "$ref": "#/components/schemas/EmojiReactions" + }, + "replies": { + "description": "The number of replies to this comment.", + "type": "number" + }, + "body": { + "description": "The content of the comment.", + "$ref": "#/components/schemas/Document" + }, + "target": { + "description": "Information about the target of the comment.", + "type": "object", + "properties": { + "node": { + "description": "The node this comment is attached to.", + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "preview": { + "type": "string" + } + }, + "required": ["id"] + }, + "changeRequest": { + "description": "The change request containing this comment, if the comment was made inside a change request.", + "type": "string" + }, + "review": { + "description": "The review containing this comment, if this comment was made as part of a review.", + "type": "string" + }, + "page": { + "description": "Information about the page, if this comment refers to a specific page.", + "allOf": [ + { + "$ref": "#/components/schemas/RevisionPageBase" + }, + { + "type": "object", + "properties": { + "path": { + "description": "The fully qualified path to the page", + "type": "string" + }, + "outdated": { + "description": "True if the target of this comment no longer exists in the primary content", + "type": "boolean" + } + }, + "required": ["path", "outdated"] + } + ] + }, + "space": { + "description": "The space containing this comment.", + "type": "string" + }, + "revision": { + "description": "The revision in which the target can be found in.", + "type": "string" + } + }, + "required": ["space", "revision"] + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the comment in the API", + "format": "uri" + } + }, + "required": ["location"] } - } - }, - "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" + }, + "required": [ + "object", + "id", + "replies", + "body", + "postedBy", + "postedAt", + "reactions", + "target", + "urls" + ] }, { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionPage" - } + "oneOf": [ + { + "type": "object", + "title": "Resolved", + "properties": { + "status": { + "description": "Status of the comment.", + "type": "string", + "enum": ["resolved"] + }, + "resolvedAt": { + "description": "If the comment has been resolved, the date at which it was resolved. If this field is not defined, the comment is not resolved.", + "$ref": "#/components/schemas/Timestamp" + }, + "resolvedBy": { + "description": "If the comment has been resolved, the user who resolved it. If this field is not defined, the comment is not resolved.", + "$ref": "#/components/schemas/User" + } + }, + "required": ["status", "resolvedAt", "resolvedBy"] + }, + { + "type": "object", + "title": "Open", + "properties": { + "status": { + "description": "Status of the comment.", + "type": "string", + "enum": ["open"] + } + }, + "required": ["status"] } - } - }, - "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" + ] + }, + "ChangeRequestReview": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"change-request-review\"", + "enum": ["change-request-review"] }, - { - "$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" - } - } - } + "id": { + "type": "string", + "description": "Unique identifier for the review." }, - "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" + "revision": { + "type": "string", + "description": "The revision this review was made against." }, - { - "$ref": "#/components/parameters/changeRequestId" + "reviewer": { + "description": "The user who performed the review.", + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/parameters/pagePath" + "requestedBy": { + "description": "The user who requested the review. If undefined, the review was left without a request.", + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/parameters/pageFormat" + "status": { + "description": "The status of the review.", + "$ref": "#/components/schemas/ChangeRequestReviewStatus" }, - { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" - } - ] - } - } - } + "comment": { + "$ref": "#/components/schemas/Comment" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/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" + "createdAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$ref": "#/components/parameters/changeRequestId" + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" } - ], - "responses": { - "200": { - "description": "Content marked as touched.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ChangeRequest" - } - } - } + }, + "required": [ + "object", + "id", + "revision", + "reviewer", + "status", + "createdAt", + "updatedAt" + ] + }, + "Team": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"team\"", + "enum": ["team"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "id": { + "type": "string", + "description": "Unique identifier for the team" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + "required": ["object", "id"] + }, + "ChangeRequestRequestedReviewer": { + "type": "object", + "allOf": [ + { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"change-request-requested-reviewer\"", + "enum": ["change-request-requested-reviewer"] + }, + "revision": { + "type": "string", + "description": "The revision of the content when the request was made." + }, + "requestedBy": { + "description": "The user who made the request.", + "$ref": "#/components/schemas/User" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + } + }, + "required": ["object", "revision", "requestedBy", "createdAt"] + }, + { + "type": "object", + "oneOf": [ + { "type": "object", "properties": { - "contentId": { + "kind": { "type": "string", - "description": "The content id of the touched content." + "enum": ["user"] }, - "branchId": { + "user": { + "description": "The user who was requested to review.", + "$ref": "#/components/schemas/User" + } + }, + "required": ["kind", "user"] + }, + { + "type": "object", + "properties": { + "kind": { "type": "string", - "description": "The branch id of the touched content." + "enum": ["team"] }, - "relation": { - "type": "string", - "description": "The relation of the touched content to the change request.", - "enum": ["synced-block"] + "team": { + "description": "The team who was requested to review.", + "$ref": "#/components/schemas/Team" } }, - "required": ["contentId", "branchId", "relation"] + "required": ["kind", "team"] } - } - } - } - } - }, - "/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" + ] + }, + "ContentReferenceStatus": { + "type": "string", + "enum": ["ok", "broken", "in-app"], + "description": "Text to display to represent the reference. Possible values include:\n- `ok` - No problems detected for this content reference.\n- `broken` - The target does not exist in the revision.\n- `in-app` - The target is a URL link pointing to an internal location in the app.\n" + }, + "ContentReferencesStats": { + "type": "object", + "properties": { + "total": { + "description": "Total count of links", + "type": "number" }, - { - "$ref": "#/components/parameters/revisionMetadata" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Revision" - } + "broken": { + "type": "object", + "properties": { + "total": { + "description": "Count of broken links", + "type": "number" + }, + "changeRequest": { + "description": "Count of broken links that were broken in current change request, if applicable.", + "type": "number" } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/changes": { - "get": { - "summary": "Return the semantic changes between a revision and its parent.", - "operationId": "getRevisionSemanticChanges", - "security": [ - { - "user": [] + }, + "required": ["total"] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/revisionId" + }, + "required": ["total", "broken"] + }, + "ContentReferenceUsage": { + "type": "object", + "properties": { + "status": { + "$ref": "#/components/schemas/ContentReferenceStatus" }, - { - "$ref": "#/components/parameters/revisionMetadata" + "targetReference": { + "description": "The reference target where a list of pages are pointing at", + "$ref": "#/components/schemas/ContentLocation" }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of changes returned", - "schema": { - "type": "number", - "default": 10 + "locationReferences": { + "description": "Pages locations where a link to the target is found.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLocation" } } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "changes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RevisionSemanticChange" - } - }, - "more": { - "type": "number", - "description": "How many changes were omitted because above the result limit" - } - }, - "required": ["changes"] - } - } - } + }, + "required": ["status", "locationReferences"] + }, + "PostCommentSchema": { + "type": "object", + "properties": { + "node": { + "description": "The node to which the comment is posted, if any.", + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/pages": { - "get": { - "summary": "List all pages in a revision", - "operationId": "listPagesInRevisionById", - "security": [ - { - "user": [] + "page": { + "description": "The page to which the comment is posted, if any.", + "type": "string" + }, + "body": { + "description": "The content of the comment.", + "$ref": "#/components/schemas/Document" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["body"] + }, + "UpdateCommentSchema": { + "type": "object", + "properties": { + "resolved": { + "type": "boolean", + "description": "Whether the comment is resolved or not." }, - { - "$ref": "#/components/parameters/revisionId" + "body": { + "description": "Content of the comment.", + "$ref": "#/components/schemas/Document" }, - { - "$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"] - } - } + "addedReactions": { + "type": "array", + "description": "Reactions to add to the comment.", + "items": { + "type": "string" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "removedReactions": { + "type": "array", + "description": "Reactions to remove from the comment.", + "items": { + "type": "string" + } } } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/files": { - "get": { - "summary": "List all files in a revision", - "operationId": "listFilesInRevisionById", - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "CommentReply": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"comment-reply\"", + "enum": ["comment-reply"] }, - { - "$ref": "#/components/parameters/revisionId" + "id": { + "type": "string", + "description": "Unique identifier for the reply." }, - { - "$ref": "#/components/parameters/listPage" + "postedBy": { + "$ref": "#/components/schemas/User" }, - { - "$ref": "#/components/parameters/listLimit" + "postedAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$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" - } - } - } - } - ] - } - } - } + "editedAt": { + "description": "Date when the reply was edited, if it has been edited.", + "$ref": "#/components/schemas/Timestamp" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "reactions": { + "$ref": "#/components/schemas/EmojiReactions" + }, + "body": { + "$ref": "#/components/schemas/Document" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the comment reply in the API", + "format": "uri" + } + }, + "required": ["location"] } - } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/files/{fileId}": { - "get": { - "summary": "Get a file in a revision by its ID", - "operationId": "getFileInRevisionById", - "security": [ - { - "user": [] + }, + "required": ["object", "id", "body", "postedBy", "postedAt", "reactions", "urls"] + }, + "PostCommentReplySchema": { + "type": "object", + "properties": { + "body": { + "description": "The content of the comment.", + "$ref": "#/components/schemas/Document" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/revisionId" + }, + "required": ["body"] + }, + "UserContributor": { + "type": "object", + "description": "Contributor towards content.", + "properties": { + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "$ref": "#/components/parameters/fileId" + "count": { + "type": "integer" }, - { - "$ref": "#/components/parameters/revisionMetadata" + "user": { + "$ref": "#/components/schemas/User" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionFile" - } - } - } + }, + "required": ["updatedAt", "count", "user"] + }, + "RevisionPageType": { + "type": "string", + "enum": ["document", "group", "link"] + }, + "ChangedRevisionPage": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/revisions/{revisionId}/page/{pageId}": { - "get": { - "operationId": "getPageInRevisionById", - "summary": "Get a page by its ID in a revision.", - "security": [ - { - "user": [] + "type": { + "$ref": "#/components/schemas/RevisionPageType" + }, + "title": { + "type": "string" + }, + "path": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["id", "type", "title"] + }, + "RevisionSemanticChangePageCreated": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_created"] }, - { - "$ref": "#/components/parameters/revisionId" + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" + } + }, + "required": ["type", "page"] + }, + "ChangeAttributeString": { + "type": "object", + "properties": { + "before": { + "type": "string" }, - { - "$ref": "#/components/parameters/pageId" + "after": { + "type": "string" + } + } + }, + "ChangeAttributeRevisionPageDocumentCover": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/RevisionPageDocumentCover" }, + "after": { + "$ref": "#/components/schemas/RevisionPageDocumentCover" + } + } + }, + "RevisionPageLayoutPreset": { + "type": "string", + "description": "The core layout presets for a page.", + "enum": ["docs", "editorial", "landing"] + }, + "RevisionPageLayout": { + "oneOf": [ { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/schemas/RevisionPageLayoutPreset" }, { - "$ref": "#/components/parameters/revisionMetadata" + "$ref": "#/components/schemas/RevisionPageLayoutOptions" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RevisionPage" - } - } - } + ] + }, + "ChangeAttributeRevisionPageLayout": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/RevisionPageLayout" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "after": { + "$ref": "#/components/schemas/RevisionPageLayout" } } - } - }, - "/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" - }, + }, + "CustomFieldValue": { + "oneOf": [ { - "$ref": "#/components/parameters/revisionId" + "type": "string", + "maxLength": 256 }, { - "$ref": "#/components/parameters/pagePath" + "type": "number" }, { - "$ref": "#/components/parameters/pageFormat" + "type": "boolean" }, { - "$ref": "#/components/parameters/revisionMetadata" + "type": "array", + "items": { + "type": "string", + "maxLength": 256 + } } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" - } - ] + ] + }, + "ChangeAttributeCustomFields": { + "type": "object", + "properties": { + "before": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" } - } + }, + "required": ["value"] } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "after": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } + }, + "required": ["value"] + } } } - } - }, - "/spaces/{spaceId}/comments": { - "get": { - "operationId": "listCommentsInSpace", - "summary": "List all the comments in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "RevisionPageDocumentChangeAttributes": { + "type": "object", + "minProperties": 1, + "properties": { + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$ref": "#/components/parameters/listPage" + "description": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$ref": "#/components/parameters/listLimit" + "slug": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$ref": "#/components/parameters/listOrder" + "document": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$ref": "#/components/parameters/commentStatus" + "cover": { + "$ref": "#/components/schemas/ChangeAttributeRevisionPageDocumentCover" }, - { - "$ref": "#/components/parameters/pageFormat" + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$ref": "#/components/parameters/commentTargetPage" + "layout": { + "$ref": "#/components/schemas/ChangeAttributeRevisionPageLayout" + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - ], - "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" - } - } - } - } - ] - } - } - } + } + }, + "RevisionPageGroupChangeAttributes": { + "type": "object", + "minProperties": 1, + "properties": { + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "slug": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } } }, - "post": { - "operationId": "postCommentInSpace", - "summary": "Post a new comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "ChangeAttributeContentReference": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/ContentRef" + }, + "after": { + "$ref": "#/components/schemas/ContentRef" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + } + }, + "RevisionPageLinkChangeAttributes": { + "type": "object", + "minProperties": 1, + "properties": { + "title": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "emoji": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "target": { + "$ref": "#/components/schemas/ChangeAttributeContentReference" + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PostCommentSchema" + } + }, + "RevisionSemanticChangePageEdited": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_edited"] + }, + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" + }, + "attributes": { + "oneOf": [ + { + "$ref": "#/components/schemas/RevisionPageDocumentChangeAttributes" + }, + { + "$ref": "#/components/schemas/RevisionPageGroupChangeAttributes" + }, + { + "$ref": "#/components/schemas/RevisionPageLinkChangeAttributes" } - } + ] } }, - "responses": { - "200": { - "description": "The comment was posted.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Comment" - } - } - } + "required": ["type", "page", "attributes"] + }, + "RevisionSemanticChangePageDeleted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_deleted"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/comments/{commentId}": { - "get": { - "operationId": "getCommentInSpace", - "summary": "Get a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["type", "page"] + }, + "RevisionSemanticChangePageMoved": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["page_moved"] }, - { - "$ref": "#/components/parameters/commentId" + "page": { + "$ref": "#/components/schemas/ChangedRevisionPage" }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "The returned comment.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Comment" - } + "parent": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/ChangedRevisionPage" + }, + "after": { + "$ref": "#/components/schemas/ChangedRevisionPage" } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } - } + }, + "required": ["type", "page", "parent"] }, - "delete": { - "operationId": "deleteCommentInSpace", - "summary": "Delete a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "ChangedRevisionFile": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "contentType": { + "type": "string" + }, + "downloadURL": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["id", "name", "contentType", "downloadURL"] + }, + "RevisionSemanticChangeFileCreated": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file_created"] }, - { - "$ref": "#/components/parameters/commentId" + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" } - ], - "responses": { - "205": { - "description": "The comment has been deleted." + }, + "required": ["type", "file"] + }, + "ChangeAttributeNumber": { + "type": "object", + "properties": { + "before": { + "type": "number" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "after": { + "type": "number" } } }, - "put": { - "operationId": "updateCommentInSpace", - "summary": "Update a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "RevisionFileImageDimensions": { + "type": "object", + "properties": { + "height": { + "type": "number" }, - { - "$ref": "#/components/parameters/commentId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentSchema" - } - } + "width": { + "type": "number" } }, - "responses": { - "200": { - "description": "The comment was updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Comment" - } - } - } + "required": ["height", "width"] + }, + "ChangeAttributeRevisionFileImageDimensions": { + "type": "object", + "properties": { + "before": { + "$ref": "#/components/schemas/RevisionFileImageDimensions" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "after": { + "$ref": "#/components/schemas/RevisionFileImageDimensions" } } - } - }, - "/spaces/{spaceId}/comments/{commentId}/replies": { - "get": { - "operationId": "listCommentRepliesInSpace", - "summary": "List all the replies to a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/commentId" - }, - { - "$ref": "#/components/parameters/listPage" - }, - { - "$ref": "#/components/parameters/listLimit" + }, + "RevisionFileChangeAttributes": { + "type": "object", + "minProperties": 1, + "properties": { + "name": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - { - "$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" - } - } - } - } - ] - } - } - } + "downloadURL": { + "$ref": "#/components/schemas/ChangeAttributeString" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "size": { + "$ref": "#/components/schemas/ChangeAttributeNumber" + }, + "contentType": { + "$ref": "#/components/schemas/ChangeAttributeString" + }, + "dimensions": { + "$ref": "#/components/schemas/ChangeAttributeRevisionFileImageDimensions" } } }, - "post": { - "operationId": "postCommentReplyInSpace", - "summary": "Post a new reply to a comment in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "RevisionSemanticChangeFileEdited": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file_edited"] }, - { - "$ref": "#/components/parameters/commentId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PostCommentReplySchema" - } - } + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" + }, + "attributes": { + "$ref": "#/components/schemas/RevisionFileChangeAttributes" } }, - "responses": { - "200": { - "description": "The reply was posted.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CommentReply" - } - } - } + "required": ["type", "file", "attributes"] + }, + "RevisionSemanticChangeFileDeleted": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file_deleted"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "file": { + "$ref": "#/components/schemas/ChangedRevisionFile" } - } - } - }, - "/spaces/{spaceId}/comments/{commentId}/replies/{commentReplyId}": { - "get": { - "operationId": "getCommentReplyInSpace", - "summary": "Get a comment reply in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] + }, + "required": ["type", "file"] + }, + "RevisionSemanticChangeCustomFieldsEdited": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["custom_fields_edited"] + }, + "customFields": { + "$ref": "#/components/schemas/ChangeAttributeCustomFields" } - ], - "parameters": [ + }, + "required": ["type", "customFields"] + }, + "RevisionSemanticChange": { + "oneOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionSemanticChangePageCreated" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/schemas/RevisionSemanticChangePageEdited" }, { - "$ref": "#/components/parameters/commentReplyId" + "$ref": "#/components/schemas/RevisionSemanticChangePageDeleted" }, { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "The returned comment reply.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CommentReply" - } - } - } + "$ref": "#/components/schemas/RevisionSemanticChangePageMoved" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "put": { - "operationId": "updateCommentReplyInSpace", - "summary": "Update a comment reply in a space.", - "tags": ["spaces"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/RevisionSemanticChangeFileCreated" + }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/RevisionSemanticChangeFileEdited" }, { - "$ref": "#/components/parameters/commentId" + "$ref": "#/components/schemas/RevisionSemanticChangeFileDeleted" }, { - "$ref": "#/components/parameters/commentReplyId" + "$ref": "#/components/schemas/RevisionSemanticChangeCustomFieldsEdited" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCommentReplySchema" - } + ] + }, + "RevisionSemanticChanges": { + "type": "object", + "properties": { + "changes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RevisionSemanticChange" } + }, + "more": { + "type": "number", + "description": "How many changes were omitted because above the result limit" } }, - "responses": { - "200": { - "description": "The reply was updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CommentReply" - } - } + "required": ["changes"] + }, + "UpdateCommentReplySchema": { + "type": "object", + "properties": { + "body": { + "description": "Content of the comment.", + "$ref": "#/components/schemas/Document" + }, + "addedReactions": { + "type": "array", + "description": "Reactions to add to the comment.", + "items": { + "type": "string" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "removedReactions": { + "type": "array", + "description": "Reactions to remove from the comment.", + "items": { + "type": "string" + } } } }, - "delete": { - "operationId": "deleteCommentReplyInSpace", - "summary": "Delete a comment reply in a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "UserContentPermission": { + "type": "object", + "description": "Permission of a user in a content.", + "properties": { + "permission": { + "$ref": "#/components/schemas/MemberRole" + }, + "user": { + "$ref": "#/components/schemas/User" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["permission", "user"] + }, + "Color": { + "type": "string", + "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$" + }, + "CustomizationThemedColor": { + "type": "object", + "properties": { + "light": { + "$ref": "#/components/schemas/Color" }, - { - "$ref": "#/components/parameters/commentId" + "dark": { + "$ref": "#/components/schemas/Color" + } + }, + "required": ["light", "dark"] + }, + "CustomizationCorners": { + "type": "string", + "enum": ["straight", "rounded"] + }, + "CustomizationFont": { + "type": "string", + "enum": [ + "ABCFavorit", + "Inter", + "Roboto", + "RobotoSlab", + "OpenSans", + "SourceSansPro", + "Lato", + "Ubuntu", + "Raleway", + "Merriweather", + "Overpass", + "NotoSans", + "IBMPlexSerif", + "Poppins", + "FiraSans" + ] + }, + "CustomizationBackground": { + "type": "string", + "enum": ["plain", "match"] + }, + "CustomizationLocale": { + "type": "string", + "description": "Language for the UI element", + "enum": ["en", "fr", "es", "zh", "ja", "de", "nl", "no", "pt-br"] + }, + "CustomizationThemedURL": { + "type": "object", + "properties": { + "light": { + "$ref": "#/components/schemas/URL" }, - { - "$ref": "#/components/parameters/commentReplyId" + "dark": { + "$ref": "#/components/schemas/URL" } - ], - "responses": { - "205": { - "description": "The comment has been deleted." + }, + "required": ["light", "dark"] + }, + "CustomizationHeaderPreset": { + "type": "string", + "enum": ["default", "bold", "contrast", "custom", "none"] + }, + "CustomizationContentLink": { + "type": "object", + "properties": { + "title": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/permissions/aggregate": { - "get": { - "operationId": "listPermissionsAggregateInSpace", - "summary": "List permissions for all users in a space.", - "tags": ["permissions", "spaces"], - "security": [ - { - "user": [] + "to": { + "$ref": "#/components/schemas/ContentRef" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - }, - { - "$ref": "#/components/parameters/listPage" - }, + }, + "required": ["title", "to"] + }, + "CustomizationHeaderLink": { + "allOf": [ { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/CustomizationContentLink" }, { - "name": "role", - "in": "query", - "description": "If defined, only members with this role will be returned.", - "schema": { - "$ref": "#/components/schemas/MemberRole" - } - } - ], - "responses": { - "200": { - "description": "Listing of users who can access the space.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/UserContentPermission" - } - } - } - } - ] + "type": "object", + "properties": { + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationContentLink" } } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/publishing/customization": { - "get": { - "operationId": "getSpacePublishingCustomizationById", - "summary": "Get the publishing customization configuration for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + ] + }, + "CustomizationFooterGroup": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "links": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationContentLink" + } } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationSettings" - } + }, + "required": ["title", "links"] + }, + "CustomizationThemeMode": { + "type": "string", + "enum": ["light", "dark"] + }, + "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"] }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "internationalization": { + "type": "object", + "properties": { + "locale": { + "$ref": "#/components/schemas/CustomizationLocale" + }, + "inherit": { + "type": "boolean", + "description": "Inherit locale from the parent collection." + } + }, + "required": ["locale", "inherit"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "put": { - "operationId": "updateSpacePublishingCustomizationById", - "summary": "Update the publishing customization configuration for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationSettings" + "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 } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationSettings" + ] + }, + "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" } } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + }, + "required": ["preset", "links"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/publishing/auth": { - "get": { - "operationId": "getSpacePublishingAuthById", - "summary": "Get the publishing authentication configuration for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" + "footer": { + "type": "object", + "properties": { + "logo": { + "$ref": "#/components/schemas/CustomizationThemedURL" + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationFooterGroup" } + }, + "copyright": { + "type": "string", + "maxLength": 300 } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + }, + "required": ["groups"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "updateSpacePublishingAuthById", - "summary": "Update the publishing authentication configuration for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" - } + "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"] }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "pdf": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, PDF export is enabled for the published content." + } + }, + "required": ["enabled"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/publishing/preview": { - "get": { - "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": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "url": { - "$ref": "#/components/schemas/URL" - } - }, - "required": ["url"] - } + "feedback": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, feedback gathering is enabled" } - } + }, + "required": ["enabled"] }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "aiSearch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, AI search is enabled" + } + }, + "required": ["enabled"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/integrations": { - "get": { - "operationId": "listSpaceIntegrations", - "summary": "List integrations enabled in a space.", - "tags": ["integrations", "spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "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"] }, - { - "$ref": "#/components/schemas/IntegrationSearchQuery" - } - ], - "responses": { - "200": { - "description": "Listing of integrations enabled in the space.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Integration" - } - } - } - } - ] - } + "pagination": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the pagination navigation should be displayed on pages." } - } + }, + "required": ["enabled"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/integration-blocks": { - "get": { - "operationId": "listSpaceIntegrationsBlocks", - "summary": "List integrations blocks for a space", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "list of installed integration blocks", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SpaceIntegrationBlocks" - } + "trademark": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible" } - } - }, - "404": { - "$ref": "#/components/responses/NotFoundError" + }, + "required": ["enabled"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/integration-scripts": { - "get": { - "operationId": "listSpaceIntegrationScripts", - "summary": "List the scripts to embed in published content for a space.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SpaceIntegrationScript" - } - } + "privacyPolicy": { + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" } } }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/custom-fields": { - "get": { - "operationId": "getSpaceCustomFields", - "summary": "Get the values of the custom fields set on a space", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomFieldValues" - } + "socialPreview": { + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } - } + }, + "required": [ + "inherit", + "styling", + "internationalization", + "favicon", + "header", + "footer", + "themes", + "pdf", + "feedback", + "aiSearch", + "trademark", + "pagination", + "git", + "privacyPolicy", + "socialPreview" + ] }, - "patch": { - "operationId": "updateSpaceCustomFields", - "summary": "Update the custom fields in a space", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateCustomFieldValues" + "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" } } } - }, - "responses": { - "204": { - "description": "Custom fields updated" + } + }, + "SpaceIntegrationScript": { + "type": "object", + "properties": { + "script": { + "description": "Script URL to load.", + "$ref": "#/components/schemas/URL" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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"] + }, + "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"] + }, + "CustomFieldPlaceholder": { + "type": "string", + "maxLength": 100 + }, + "CustomFieldOptions": { + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 40 } - } - }, - "/spaces/{spaceId}/pages/{pageId}/feedbacks/{visitorId}": { - "get": { - "operationId": "getPageFeedback", - "summary": "Get a page feedback by a visitor.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "CustomField": { + "type": "object", + "description": "Custom field", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/parameters/pageId" + "name": { + "$ref": "#/components/schemas/CustomFieldName" }, - { - "$ref": "#/components/parameters/visitorId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PageFeedback" - } + "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" + ] + }, + "CustomFieldValues": { + "type": "array", + "items": { + "type": "object", + "properties": { + "customField": { + "$ref": "#/components/schemas/CustomField" + }, + "value": { + "$ref": "#/components/schemas/CustomFieldValue" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } + "required": ["customField"] } }, - "put": { - "operationId": "createPageFeedback", - "summary": "Create a page feedback by a visitor.", - "tags": ["spaces"], - "security": [ - { - "user": [] + "UpdateCustomFieldValues": { + "type": "object", + "properties": { + "values": { + "type": "object", + "additionalProperties": { + "type": "object", + "maxProperties": 100, + "minProperties": 1, + "properties": { + "value": { + "$ref": "#/components/schemas/CustomFieldValue" + } + }, + "required": ["value"] + } } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + }, + "required": ["values"] + }, + "PageFeedbackRating": { + "type": "string", + "enum": ["bad", "ok", "good"] + }, + "PageFeedback": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equal to \"page-feedback\"", + "enum": ["page-feedback"] }, - { - "$ref": "#/components/parameters/pageId" + "visitorId": { + "type": "string" }, - { - "$ref": "#/components/parameters/visitorId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "rating": { - "$ref": "#/components/schemas/PageFeedbackRating" - } - }, - "required": ["rating"] + "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"] } }, - "responses": { - "200": { - "description": "Feedback updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PageFeedback" - } - } - } + "required": ["object", "visitorId", "rating", "createdAt", "revision", "urls"] + }, + "ShareLinkName": { + "type": "string", + "description": "Name of the share link", + "minLength": 0, + "maxLength": 50 + }, + "ShareLink": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"share-link\"", + "enum": ["share-link"] }, - "201": { - "description": "Feedback created", - "headers": { - "Location": { - "description": "URL for the feedback", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PageFeedback" - } - } - } + "id": { + "type": "string", + "description": "Unique identifier for the share-link" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/pdf": { - "get": { - "operationId": "getSpacePDF", - "summary": "Generate a URL to export the content of the space as a PDF.", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + "createdAt": { + "$ref": "#/components/schemas/Timestamp" }, - { - "in": "query", - "name": "only", - "description": "Generate a PDF only for the provided page.", - "schema": { - "type": "boolean" - } + "name": { + "$ref": "#/components/schemas/ShareLinkName" }, - { - "in": "query", - "name": "page", - "description": "ID of a specific page to generate a PDF for.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "URL of the PDF", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "url": { - "description": "Temporary URL to print the content. The URL will work for 1h.", - "$ref": "#/components/schemas/URL" - } - }, - "required": ["url"] - } - } - } + "active": { + "type": "boolean" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/share-links": { - "post": { - "operationId": "createSpaceShareLink", - "summary": "Creates a new space share link", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "$ref": "#/components/schemas/ShareLinkName" - } - }, - "required": ["name"] + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "published": { + "type": "string", + "description": "URL of the published version of the share-link.", + "format": "uri" } } } }, - "responses": { - "201": { - "description": "The space share link has been created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShareLink" - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/spaces/{spaceId}/share-links/{shareLinkId}": { - "patch": { - "operationId": "updateSpaceShareLinkById", - "summary": "Update the details of a space share link", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ + "required": ["object", "id", "createdAt", "urls"] + }, + "CustomizationCollectionSettings": { + "allOf": [ { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/CustomizationSettings" }, { - "$ref": "#/components/parameters/shareLinkId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + "type": "object", + "properties": { + "collection": { "type": "object", - "minProperties": 1, "properties": { - "active": { - "type": "boolean" - }, - "name": { - "$ref": "#/components/schemas/ShareLinkName" + "defaultSpace": { + "type": "string", + "description": "ID of the space used by default in the collection" } } } - } + }, + "required": ["collection"] } - }, - "responses": { - "200": { - "description": "The space share link has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShareLink" - } - } + ] + }, + "IntegrationSecrets": { + "type": "object", + "description": "Secrets stored on the integration and passed at runtime.", + "properties": {}, + "maxProperties": 20, + "additionalProperties": { + "type": "string" + } + }, + "PublishIntegration": { + "type": "object", + "properties": { + "icon": { + "type": "string", + "format": "byte", + "description": "Base64 content of the icon" + }, + "title": { + "$ref": "#/components/schemas/IntegrationTitle" + }, + "description": { + "$ref": "#/components/schemas/IntegrationDescription" + }, + "summary": { + "$ref": "#/components/schemas/IntegrationSummary" + }, + "previewImages": { + "type": "array", + "maxItems": 3, + "items": { + "type": "string", + "format": "byte", + "description": "Base64 content of the image" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "visibility": { + "$ref": "#/components/schemas/IntegrationVisibility" + }, + "target": { + "description": "Allowed installation target for the integration. If not specified, the integration can be installed at `all` targets (org, spaces etc)", + "$ref": "#/components/schemas/IntegrationTarget" + }, + "scopes": { + "$ref": "#/components/schemas/IntegrationScopes" + }, + "categories": { + "$ref": "#/components/schemas/IntegrationCategories" + }, + "blocks": { + "$ref": "#/components/schemas/IntegrationBlocks" + }, + "externalLinks": { + "$ref": "#/components/schemas/IntegrationExternalLinks" + }, + "configurations": { + "$ref": "#/components/schemas/IntegrationConfigurations" + }, + "script": { + "type": "string", + "description": "Content of the script to use" + }, + "organization": { + "type": "string", + "description": "The ID or subdomain of the organization under which the integration should be published" + }, + "secrets": { + "$ref": "#/components/schemas/IntegrationSecrets" + }, + "contentSecurityPolicy": { + "$ref": "#/components/schemas/IntegrationContentSecurityPolicy" + } + }, + "required": ["organization", "title", "description", "script", "scopes"] + }, + "IntegrationInstallationStatus": { + "type": "string", + "enum": ["active", "pending", "paused"] + }, + "IntegrationInstallationSpaceSelection": { + "type": "string", + "description": "Describe whether all spaces have been selected or there's a selection involved", + "enum": ["all", "selected"] + }, + "IntegrationInstallationSiteSelection": { + "type": "string", + "description": "Describe whether all sites have been selected or there's a selection involved", + "enum": ["all", "selected"] + }, + "IntegrationInstallationConfiguration": { + "type": "object", + "description": "Configuration of the integration at the account level", + "additionalProperties": true + }, + "IntegrationInstallationExternalIds": { + "type": "array", + "description": "External IDs assigned by the integration.", + "maxItems": 5, + "items": { + "type": "string" + } + }, + "OrganizationTarget": { + "type": "object", + "required": ["organization"], + "properties": { + "organization": { + "type": "string" } } }, - "delete": { - "operationId": "deleteSpaceShareLinkById", - "summary": "Deletes a space share link", - "tags": ["spaces"], - "security": [ + "IntegrationInstallationTarget": { + "oneOf": [ { - "user": [] + "$ref": "#/components/schemas/OrganizationTarget" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/spaceId" + ] + }, + "IntegrationInstallation": { + "type": "object", + "description": "Installation of an integration on an account", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/parameters/shareLinkId" + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + }, + "space_selection": { + "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" + }, + "site_selection": { + "$ref": "#/components/schemas/IntegrationInstallationSiteSelection" + }, + "spaces": { + "type": "number", + "description": "Count of spaces, the installation is managing" + }, + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + }, + "createdAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the installation in the API", + "format": "uri" + }, + "app": { + "type": "string", + "description": "URL of the integration's installation in the application", + "format": "uri" + }, + "publicEndpoint": { + "type": "string", + "description": "Public HTTP endpoint for the integration's installation", + "format": "uri" + } + }, + "required": ["location", "app", "publicEndpoint"] + }, + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" + }, + "target": { + "$ref": "#/components/schemas/IntegrationInstallationTarget", + "description": "Target of the integration installation" } - ], - "responses": { - "205": { - "description": "Space share link has been deleted" + }, + "required": [ + "id", + "status", + "space_selection", + "site_selection", + "spaces", + "configuration", + "urls", + "externalIds", + "target", + "createdAt", + "updatedAt" + ] + }, + "BaseEvent": { + "description": "Common properties for all events.", + "type": "object", + "properties": { + "eventId": { + "description": "Unique identifier for the event.", + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "type": { + "description": "Type of the event.", + "type": "string" } - } - } - }, - "/collections/{collectionId}": { - "get": { - "operationId": "getCollectionById", - "summary": "Get the details about a collection using its ID", - "tags": ["collections"], - "security": [ + }, + "required": ["eventId", "type"] + }, + "InstallationEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/BaseEvent" + }, { - "$ref": "#/components/parameters/collectionId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" - } + "type": "object", + "description": "Common properties for all events related to an installation", + "properties": { + "installationId": { + "type": "string", + "description": "ID of the integration installation" } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["installationId"] } - } + ] }, - "patch": { - "operationId": "updateCollectionById", - "summary": "Update the details of a collection", - "tags": ["collections"], - "security": [ + "InstallationSetupEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/InstallationEvent" + }, { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + "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": { - "visibility": { - "$ref": "#/components/schemas/ContentVisibility" - }, - "title": { - "$ref": "#/components/schemas/CollectionTitle" - }, - "description": { - "$ref": "#/components/schemas/CollectionDescription" + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" }, - "defaultLevel": { - "$ref": "#/components/schemas/DefaultLevel" + "configuration": { + "type": "object", + "description": "The previous configuration of the installation at the account level." } - } - } - } - } - }, - "responses": { - "200": { - "description": "The collection has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" - } + }, + "required": ["status"] } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["type", "status"] } - } + ] }, - "delete": { - "operationId": "deleteCollectionById", - "summary": "Deletes a collection", - "tags": ["collections"], - "security": [ - { - "user": [] - } - ], - "parameters": [ + "SpaceEvent": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" - } - ], - "responses": { - "205": { - "description": "Collection has been deleted" + "$ref": "#/components/schemas/InstallationEvent" }, - "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": [ { - "user": [] + "type": "object", + "description": "Common properties for all events related to a specific space.", + "properties": { + "spaceId": { + "type": "string", + "description": "ID of the space" + } + }, + "required": ["spaceId"] } - ], - "parameters": [ + ] + }, + "SpaceInstallationSetupEvent": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/schemas/SpaceEvent" }, { - "$ref": "#/components/parameters/listPage" + "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" }, { - "$ref": "#/components/parameters/listLimit" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Space" - } - } - } - } - ] + "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." + } } } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["type", "previous"] } - } - } - }, - "/collections/{collectionId}/move": { - "post": { - "operationId": "moveCollection", - "summary": "Move a collection to a new position.", - "tags": ["collections"], - "security": [ + ] + }, + "SiteEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/InstallationEvent" + }, { - "$ref": "#/components/parameters/collectionId" + "type": "object", + "description": "Common properties for all events related to a specific site.", + "properties": { + "siteId": { + "type": "string", + "description": "ID of the site" + } + }, + "required": ["siteId"] } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + ] + }, + "SiteInstallationSetupEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/SiteEvent" + }, + { + "type": "object", + "description": "Event received when integration has been installed or updated on a site.", + "properties": { + "type": { + "type": "string", + "enum": ["site_installation_setup"] + }, + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" + }, + "previous": { "type": "object", - "minProperties": 1, + "description": "The state of the site installation before it was updated.", "properties": { - "parent": { - "description": "The unique id of the parent collection", - "type": "string", - "nullable": true + "status": { + "$ref": "#/components/schemas/IntegrationInstallationStatus" }, - "position": { - "description": "Where to move the collection. By default, it will be moved at the end.", - "$ref": "#/components/schemas/ContentPosition" + "configuration": { + "type": "object", + "description": "The previous configuration of the site installation." } - } + }, + "required": ["status"] } - } + }, + "required": ["type", "status"] } - }, - "responses": { - "200": { - "description": "Collection moved", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" + ] + }, + "SiteInstallationDeletedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/SiteEvent" + }, + { + "type": "object", + "description": "Event received when integration has been uninstalled from a site.", + "properties": { + "type": { + "type": "string", + "enum": ["site_installation_deleted"] + }, + "previous": { + "type": "object", + "description": "The state of the site installation before it was deleted.", + "properties": { + "configuration": { + "type": "object", + "description": "The previous configuration of the site installation." + } } } - } - }, - "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" + }, + "required": ["type", "previous"] } - } - } - }, - "/collections/{collectionId}/transfer": { - "post": { - "operationId": "transferCollection", - "summary": "Transfer a collection to another organization.", - "tags": ["collections"], - "security": [ + ] + }, + "SpaceViewEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SpaceEvent" + }, { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + "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": { - "organization": { + "anonymousId": { "type": "string", - "description": "The unique id of the target organization" + "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": ["organization"] + "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"] } - }, - "responses": { - "200": { - "description": "Collection transferred", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" - } + ] + }, + "SiteViewEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/SiteEvent" + }, + { + "type": "object", + "description": "Event received when a page has been visited on a site.", + "properties": { + "type": { + "type": "string", + "enum": ["site_view"] + }, + "spaceId": { + "type": "string", + "description": "Unique identifier of the visited space in the site." + }, + "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." } - } - }, - "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" + }, + "required": ["type", "visitor", "url", "referrer", "spaceId"] } - } - } - }, - "/collections/{collectionId}/permissions/aggregate": { - "get": { - "operationId": "listPermissionsAggregateInCollection", - "summary": "List permissions for all users in a collection.", - "tags": ["permissions", "spaces"], - "security": [ + ] + }, + "SpaceContentUpdatedEvent": { + "allOf": [ { - "user": [] + "$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"] } - ], - "parameters": [ + ] + }, + "SpaceGitSyncCompletedEvent": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/schemas/SpaceEvent" }, { - "$ref": "#/components/parameters/listPage" - }, + "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/parameters/listLimit" + "$ref": "#/components/schemas/SpaceEvent" }, { - "name": "role", - "in": "query", - "description": "If defined, only members with this role will be returned.", - "schema": { - "$ref": "#/components/schemas/MemberRole" - } - } - ], - "responses": { - "200": { - "description": "Listing of users who can access the collections.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/UserContentPermission" - } - } - } - } - ] - } + "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)" } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["type", "revisionId", "commitId"] } - } - } - }, - "/collections/{collectionId}/publishing/auth": { - "get": { - "operationId": "getCollectionPublishingAuthById", - "summary": "Get the publishing authentication configuration for a collection.", - "tags": ["collections"], - "security": [ + ] + }, + "SpaceVisibilityUpdatedEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SpaceEvent" + }, { - "$ref": "#/components/parameters/collectionId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" - } + "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"] + } + ] + }, + "FetchRequest": { + "type": "object", + "properties": { + "method": { + "type": "string", + "enum": ["post", "get", "put", "delete"] }, - "400": { - "$ref": "#/components/responses/BadRequestError" + "url": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "headers": { + "type": "object", + "additionalProperties": { + "type": "string" + } } - } + }, + "required": ["method", "url", "headers"] }, - "post": { - "operationId": "updateCollectionPublishingAuthById", - "summary": "Update the publishing authentication configuration for a collection.", - "tags": ["collections"], - "security": [ + "FetchEvent": { + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/BaseEvent" + }, { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateContentPublishingAuth" + "type": "object", + "description": "Event representing an incoming HTTP request.", + "properties": { + "spaceId": { + "type": "string", + "description": "The space ID, if requests are specific to a single space" + }, + "siteId": { + "type": "string", + "description": "The site ID, if requests are specific to a single site" + }, + "installationId": { + "type": "string", + "description": "The installation ID, if requests are specific to a single installation" + }, + "auth": { + "type": "object", + "properties": { + "userId": { + "type": "string", + "description": "The user's ID." + } + }, + "required": ["userId"] + }, + "type": { + "type": "string", + "enum": ["fetch"] + }, + "request": { + "$ref": "#/components/schemas/FetchRequest" } - } + }, + "required": ["type", "request"] } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPublishingAuth" - } + ] + }, + "FetchPublishedScriptEvent": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/SpaceEvent" + }, + { + "$ref": "#/components/schemas/SiteEvent" } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/collections/{collectionId}/publishing/customization": { - "get": { - "operationId": "getCollectionPublishingCustomizationById", - "summary": "Get the publishing customization configuration for a collection.", - "tags": ["collections"], - "security": [ { - "user": [] + "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"] } - ], - "parameters": [ + ] + }, + "FetchVisitorAuthenticationEvent": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationCollectionSettings" - } + "oneOf": [ + { + "$ref": "#/components/schemas/SpaceEvent" + }, + { + "$ref": "#/components/schemas/SiteEvent" } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + { + "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"] } - } + ] }, - "put": { - "operationId": "updateCollectionPublishingCustomizationById", - "summary": "Update the publishing customization configuration for a collection.", - "tags": ["collections"], - "security": [ - { - "user": [] + "ContentKitContextBase": { + "type": "object", + "description": "Common properties for ContentKit context.", + "properties": { + "theme": { + "type": "string", + "enum": ["dark", "light"] } - ], - "parameters": [ + }, + "required": ["theme"] + }, + "ContentKitContextConfigurationAccount": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationCollectionSettings" + "$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"] } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomizationCollectionSettings" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequestError" + ] + }, + "ContentKitContextConfigurationSpace": { + "allOf": [ + { + "$ref": "#/components/schemas/ContentKitContextBase" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/collections/{collectionId}/share-links": { - "post": { - "operationId": "createCollectionShareLink", - "summary": "Creates a new collection share link", - "tags": ["collections"], - "security": [ { - "user": [] + "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"] } - ], - "parameters": [ + ] + }, + "ContentKitContextConfigurationSite": { + "allOf": [ { - "$ref": "#/components/parameters/collectionId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "$ref": "#/components/schemas/ShareLinkName" - } - }, - "required": ["name"] + "$ref": "#/components/schemas/ContentKitContextBase" + }, + { + "type": "object", + "description": "Context while rendering in a site-installation's configuration.", + "properties": { + "type": { + "type": "string", + "enum": ["configuration_site"] + }, + "siteId": { + "type": "string", + "description": "ID of the site the site-installation configuration is in." } - } + }, + "required": ["type", "siteId"] } - }, - "responses": { - "201": { - "description": "The collection share link has been created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShareLink" - } - } - } + ] + }, + "ContentKitContextDocument": { + "allOf": [ + { + "$ref": "#/components/schemas/ContentKitContextBase" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + { + "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"] } - } - } - }, - "/collections/{collectionId}/share-links/{shareLinkId}": { - "patch": { - "operationId": "updateCollectionShareLinkById", - "summary": "Update the details of a collection share link", - "tags": ["collections"], - "security": [ + ] + }, + "ContentKitContext": { + "description": "Object representing the context in which a ContentKit component is rendered.", + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitContextConfigurationAccount" + }, { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ContentKitContextConfigurationSpace" + }, { - "$ref": "#/components/parameters/collectionId" + "$ref": "#/components/schemas/ContentKitContextConfigurationSite" }, { - "$ref": "#/components/parameters/shareLinkId" + "$ref": "#/components/schemas/ContentKitContextDocument" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + ] + }, + "UIRenderEvent": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/SpaceEvent" + }, + { + "$ref": "#/components/schemas/SiteEvent" + }, + { + "$ref": "#/components/schemas/InstallationEvent" + } + ] + }, + { + "type": "object", + "description": "Event generated when rendering a UI", + "properties": { + "auth": { "type": "object", - "minProperties": 1, "properties": { - "active": { - "type": "boolean" - }, - "name": { - "$ref": "#/components/schemas/ShareLinkName" + "userId": { + "type": "string", + "description": "The user's ID." } - } - } - } - } - }, - "responses": { - "200": { - "description": "The collection share link has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShareLink" - } + }, + "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" } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["type", "componentId", "props", "context"] } - } + ] }, - "delete": { - "operationId": "deleteCollectionShareLinkById", - "summary": "Deletes a collection share link", - "tags": ["collections"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/collectionId" - }, + "Event": { + "description": "Any event that can be received from GitBook.", + "oneOf": [ { - "$ref": "#/components/parameters/shareLinkId" - } - ], - "responses": { - "205": { - "description": "Collection share link has been deleted" + "$ref": "#/components/schemas/InstallationSetupEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations": { - "get": { - "operationId": "listIntegrations", - "summary": "List all public integrations", - "tags": ["integrations"], - "parameters": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/SpaceInstallationSetupEvent" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/SpaceInstallationDeletedEvent" }, { - "$ref": "#/components/schemas/IntegrationSearchQuery" + "$ref": "#/components/schemas/SiteInstallationSetupEvent" }, { - "name": "category", - "in": "query", - "description": "Filter the integrations by category", - "schema": { - "$ref": "#/components/schemas/IntegrationCategory" - } + "$ref": "#/components/schemas/SiteInstallationDeletedEvent" }, { - "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": "Paginated list of integrations", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Integration" - } - } - } - } - ] - } - } - } + "$ref": "#/components/schemas/SpaceViewEvent" }, - "default": { - "$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" + "$ref": "#/components/schemas/SiteViewEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "publishIntegration", - "summary": "Publish an integration", - "tags": ["integrations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/integrationName" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Integration" - } - } - } - }, - "404": { - "description": "Organization could not be found for the given hostname", - "$ref": "#/components/responses/NotFoundError" + "$ref": "#/components/schemas/SpaceContentUpdatedEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestPublishIntegration" - } - } - } - } - }, - "delete": { - "operationId": "unpublishIntegration", - "summary": "Unpublish an integration", - "tags": ["integrations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SpaceGitSyncCompletedEvent" + }, { - "$ref": "#/components/parameters/integrationName" - } - ], - "responses": { - "204": { - "description": "Integration has been deleted" + "$ref": "#/components/schemas/SpaceGitSyncStartedEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/installations": { - "get": { - "operationId": "listIntegrationInstallations", - "summary": "Fetch a list of installations of an integration", - "tags": ["integrations"], - "security": [ { - "integration": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SpaceVisibilityUpdatedEvent" + }, { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/schemas/FetchEvent" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/FetchPublishedScriptEvent" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/FetchVisitorAuthenticationEvent" }, { - "name": "externalId", - "in": "query", - "description": "External Id to filter by", - "schema": { - "type": "string" - } + "$ref": "#/components/schemas/UIRenderEvent" } ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationInstallation" - } - } - } - } - ] - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } + "discriminator": { + "propertyName": "type" } }, - "post": { - "operationId": "installIntegration", - "summary": "Install integration on a target organization", - "tags": ["integrations"], - "security": [ - { - "user": [] + "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"] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + }, + "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"] } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationTarget" - } + } + }, + "IntegrationEventTrace": { + "type": "object", + "required": ["logs"], + "properties": { + "logs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationEventLog" } } - }, - "responses": { - "201": { - "headers": { - "Location": { - "description": "URL for the installed integration", - "schema": { - "type": "string" - } + } + }, + "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" } }, - "description": "Integration installed successfully", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" - } - } - } + "required": ["location", "publicEndpoint"] + } + }, + "required": [ + "integration", + "installation", + "space", + "status", + "configuration", + "externalIds", + "urls" + ] + }, + "ContentKitIcon": { + "type": "string", + "enum": [ + "close", + "edit", + "github", + "gitlab", + "maximize", + "email", + "settings", + "search", + "delete", + "star", + "warning", + "link", + "link-external", + "eye", + "lock" + ] + }, + "ContentKitConfirm": { + "type": "object", + "description": "A confirm object that defines an optional confirmation dialog after the input is clicked.", + "properties": { + "title": { + "type": "string", + "description": "A text value that defines the dialog's title.", + "maxLength": 100 + }, + "text": { + "type": "string", + "description": "A text value that defines the explanatory text that appears in the confirm dialog.", + "maxLength": 300 + }, + "confirm": { + "type": "string", + "description": "A text value to define the text of the button that confirms the action.", + "maxLength": 30 + }, + "style": { + "type": "string", + "enum": ["primary", "danger"] + } + }, + "required": ["title", "text", "confirm"] + }, + "ContentKitButton": { + "type": "object", + "description": "Pressable button triggering an action.", + "properties": { + "type": { + "type": "string", + "enum": ["button"] }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "style": { + "type": "string", + "enum": ["primary", "secondary", "danger"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/events": { - "get": { - "operationId": "listIntegrationEvents", - "summary": "List all integration events", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "onPress": { + "$ref": "#/components/schemas/ContentKitAction" }, - { - "$ref": "#/components/parameters/listPage" + "icon": { + "$ref": "#/components/schemas/ContentKitIcon" }, - { - "$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" - } - } - } - } - ] - } - } - } + "trailingIcon": { + "$ref": "#/components/schemas/ContentKitIcon" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/events/{eventId}": { - "get": { - "operationId": "getIntegrationEvent", - "summary": "Get a specific integration event by its id", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "label": { + "type": "string" }, - { - "name": "eventId", - "in": "path", - "required": true, - "description": "ID of the integration event", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Integration event", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["event"], - "properties": { - "event": { - "$ref": "#/components/schemas/IntegrationEvent" - }, - "trace": { - "$ref": "#/components/schemas/IntegrationEventTrace" - } - } - } - } - } + "tooltip": { + "type": "string" }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "confirm": { + "$ref": "#/components/schemas/ContentKitConfirm" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/spaces": { - "get": { - "operationId": "listIntegrationSpaceInstallations", - "summary": "Fetch a list of space installations of an integration", - "tags": ["integrations"], - "security": [ - { - "integration": [] + "disabled": { + "type": "boolean" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + }, + "required": ["type", "onPress"] + }, + "ContentKitTextInput": { + "type": "object", + "description": "Text input to prompt the user.", + "properties": { + "type": { + "type": "string", + "enum": ["textinput"] }, - { - "$ref": "#/components/parameters/listPage" + "disabled": { + "type": "boolean" }, - { - "$ref": "#/components/parameters/listLimit" + "state": { + "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "type": "string" }, - { - "name": "externalId", - "in": "query", - "description": "External Id to filter by", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" - } - } - } - } - ] - } - } - } + "initialValue": { + "description": "Text value to initialize the input with.", + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/spaces/{spaceId}/dev": { - "put": { - "operationId": "updateIntegrationDevSpace", - "summary": "Update the development space for an integration", - "tags": ["integrations"], - "security": [ - { - "user": [] + "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" } - ], - "parameters": [ + }, + "required": ["type", "state"] + }, + "ContentKitDescendantElement": { + "description": "Any element that can be used as children.", + "oneOf": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/schemas/ContentKitButton" }, { - "$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": { - "204": { - "description": "Updated development space successfully" + "$ref": "#/components/schemas/ContentKitTextInput" + }, + { + "$ref": "#/components/schemas/ContentKitHStack" }, - "404": { - "$ref": "#/components/responses/NotFoundError" + { + "$ref": "#/components/schemas/ContentKitVStack" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "delete": { - "operationId": "removeIntegrationDevSpace", - "summary": "Remove the development space for an integration", - "tags": ["integrations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ContentKitBox" + }, { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/schemas/ContentKitDivider" }, { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "204": { - "description": "Removed development space successfully" + "$ref": "#/components/schemas/ContentKitWebFrame" }, - "404": { - "description": "No matching integration dev space found", - "$ref": "#/components/responses/NotFoundError" + { + "$ref": "#/components/schemas/ContentKitCodeBlock" }, - "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/integrationName" + "$ref": "#/components/schemas/ContentKitMarkdown" }, { - "name": "request", - "in": "query", - "required": true, - "description": "LZ-string compressed JSON request", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "ContentKit element to render", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentKitRenderOutput" - } - } - }, - "headers": { - "Cache-Control": { - "schema": { - "type": "string" - } - } - } + "$ref": "#/components/schemas/ContentKitCard" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "renderIntegrationUIWithPost", - "summary": "Render an integration UI in the context of an installation.", - "parameters": [ { - "$ref": "#/components/parameters/integrationName" - } - ], - "responses": { - "200": { - "description": "ContentKit element to render", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentKitRenderOutput" - } - } - }, - "headers": { - "Cache-Control": { - "schema": { - "type": "string" - } - } - } + "$ref": "#/components/schemas/ContentKitImage" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestRenderIntegrationUI" - } - } - } - } - } - }, - "/integrations/{integrationName}/tasks": { - "post": { - "operationId": "queueIntegrationTask", - "summary": "Queue a task for an integration to be executed later", - "tags": ["integrations"], - "security": [ { - "integration": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ContentKitInput" + }, { - "$ref": "#/components/parameters/integrationName" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "task": { - "type": "object", - "description": "Payload for the integration task" - }, - "schedule": { - "type": "number", - "description": "Number of seconds to wait before executing the task, defaults to 0", - "minimum": 0, - "maximum": 86400 - } - }, - "required": ["task"] - } - } - } - }, - "responses": { - "204": { - "description": "Integration task created successfully" + "$ref": "#/components/schemas/ContentKitSelect" }, - "404": { - "$ref": "#/components/responses/NotFoundError" + { + "$ref": "#/components/schemas/ContentKitSwitch" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/installations/{installationId}": { - "get": { - "operationId": "getIntegrationInstallationById", - "summary": "Get a specific integration's installation by its ID", - "tags": ["integrations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ContentKitCheckbox" + }, { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/schemas/ContentKitRadio" }, { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/schemas/ContentKitText" + }, + { + "$ref": "#/components/schemas/ContentKitHint" + }, + { + "$ref": "#/components/schemas/ContentKitLink" } ], - "responses": { - "200": { - "description": "Integration installation", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" - } - } + "discriminator": { + "propertyName": "type" + } + }, + "ContentKitHStack": { + "type": "object", + "description": "Horizontal stack of boxes.", + "properties": { + "type": { + "type": "string", + "enum": ["hstack"] + }, + "align": { + "type": "string", + "default": "start", + "enum": ["start", "center", "end"] + }, + "children": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitDescendantElement" + } + } + }, + "required": ["type", "children"] + }, + "ContentKitVStack": { + "type": "object", + "description": "Vertical stack of boxes.", + "properties": { + "type": { + "type": "string", + "enum": ["vstack"] + }, + "align": { + "type": "string", + "default": "start", + "enum": ["start", "center", "end"] + }, + "children": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitDescendantElement" } + } + }, + "required": ["type", "children"] + }, + "ContentKitBox": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["box"] }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "grow": { + "description": "specifies how much of the remaining space in the container should be assigned to the element", + "type": "number" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "children": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitDescendantElement" + } } - } + }, + "required": ["type", "children"] }, - "patch": { - "operationId": "updateIntegrationInstallation", - "summary": "Update external IDs and configurations of an integration's installation", - "tags": ["integrations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "ContentKitDivider": { + "type": "object", + "description": "Divider between 2 boxes in a stack.", + "properties": { + "type": { + "type": "string", + "enum": ["divider"] }, - { - "$ref": "#/components/parameters/installationId" + "size": { + "type": "string", + "enum": ["small", "medium", "large"] } - ], - "responses": { - "200": { - "description": "The installation has been updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationInstallation" - } - } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + }, + "required": ["type"] + }, + "ContentKitDynamicBinding": { + "type": "object", + "description": "Binding between a property and a state value.", + "properties": { + "$state": { + "type": "string", + "description": "Key in the state" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateIntegrationInstallation" + "required": ["$state"] + }, + "ContentKitWebFrame": { + "type": "object", + "description": "Frame for a webpage", + "properties": { + "type": { + "type": "string", + "enum": ["webframe"] + }, + "aspectRatio": { + "type": "number", + "description": "Ratio between width and height. Used to size the webframe." + }, + "source": { + "type": "object", + "description": "Content to load in the frame.", + "properties": { + "url": { + "type": "string" } + }, + "required": ["url"] + }, + "buttons": { + "type": "array", + "description": "Controls button shown as an overlay in a corner of the frame.", + "items": { + "$ref": "#/components/schemas/ContentKitButton" } - } - } - }, - "delete": { - "operationId": "uninstallIntegration", - "summary": "Uninstall the integration from a target organization", - "tags": ["integrations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" }, - { - "$ref": "#/components/parameters/installationId" + "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" + } + ] + } } - ], - "responses": { - "204": { - "description": "Integration uninstalled successfully" + }, + "required": ["type", "source"] + }, + "ContentKitCodeBlock": { + "type": "object", + "description": "Code block with syntax highlighting", + "properties": { + "type": { + "type": "string", + "enum": ["codeblock"] }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "content": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitDynamicBinding" + }, + { + "type": "string", + "description": "Code content to display" + } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/installations/{installationId}/tokens": { - "post": { - "operationId": "createIntegrationInstallationToken", - "summary": "Create an integration installation API token", - "description": "Creates a temporary API token of an integration's installation that has access to the installation and it's scopes. You must be authenticated as the integration to obtain this token.\n", - "tags": ["integrations"], - "security": [ - { - "integration": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "syntax": { + "description": "Syntax to use for highlighting (ex: javascript, python)", + "type": "string" }, - { - "$ref": "#/components/parameters/installationId" - } - ], - "responses": { - "200": { - "description": "The API token for the installation", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/APITemporaryToken" - } + "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" } }, - "404": { - "description": "Installation could not be found", - "$ref": "#/components/responses/NotFoundError" + "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" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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" + } } - } - } - }, - "/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" + }, + "required": ["type", "content"] + }, + "ContentKitMarkdown": { + "type": "object", + "description": "Block with rich text formatting of a markdown content.", + "properties": { + "type": { + "type": "string", + "enum": ["markdown"] }, - { - "$ref": "#/components/parameters/installationId" + "content": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitDynamicBinding" + }, + { + "type": "string", + "description": "Markdown content to display" + } + ] + } + }, + "required": ["type", "content"] + }, + "ContentKitText": { + "type": "object", + "description": "Low level text element.", + "properties": { + "type": { + "type": "string", + "enum": ["text"] }, - { - "$ref": "#/components/parameters/listPage" + "style": { + "type": "string", + "enum": ["bold", "italic", "code", "strikethrough"] }, - { - "$ref": "#/components/parameters/listLimit" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ + "children": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "oneOf": [ { - "$ref": "#/components/schemas/List" + "type": "string" }, { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" - } - } - } + "$ref": "#/components/schemas/ContentKitText" + }, + { + "$ref": "#/components/schemas/ContentKitLink" } ] } } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + ] } - } + }, + "required": ["type", "children"] }, - "post": { - "operationId": "installIntegrationOnSpace", - "summary": "Install integration on a space using an existing installation", - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "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" }, - { - "$ref": "#/components/parameters/installationId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["space"], - "properties": { - "space": { - "type": "string", - "description": "ID of the space to install the integration on" - } + "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" } - } + ] } } }, - "responses": { - "201": { - "headers": { - "Location": { - "description": "URL for the installed integration", - "schema": { - "type": "string" - } + "required": ["host", "pathname"] + }, + "ContentKitLink": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["link"] + }, + "target": { + "type": "object", + "properties": { + "url": { + "oneOf": [ + { + "type": "string" + }, + { + "$ref": "#/components/schemas/ContentKitURL" + } + ] } }, - "description": "Integration installed successfully on space", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" - } - } - } - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}": { - "get": { - "operationId": "getIntegrationSpaceInstallation", - "summary": "Get a specific integration's space installation", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" + "required": ["url"] }, - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "Integration space installation", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" + "children": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "array", + "items": { + "type": "string" } } - } - }, - "404": { - "$ref": "#/components/responses/NotFoundError" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + ] } - } + }, + "required": ["type", "target", "children"] }, - "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/installationId" + "ContentKitImage": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["image"] }, - { - "$ref": "#/components/parameters/spaceId" - } - ], - "responses": { - "200": { - "description": "The space installation has been updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSpaceInstallation" - } + "source": { + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri" } - } + }, + "required": ["url"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "aspectRatio": { + "type": "number" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateIntegrationSpaceInstallation" - } - } - } - } + "required": ["type", "source", "aspectRatio"] }, - "delete": { - "operationId": "uninstallIntegrationFromSpace", - "summary": "Uninstall the integration from a space", - "parameters": [ + "ContentKitInlineElement": { + "description": "Any element that is inline.", + "oneOf": [ { - "$ref": "#/components/parameters/integrationName" + "$ref": "#/components/schemas/ContentKitText" }, { - "$ref": "#/components/parameters/installationId" + "$ref": "#/components/schemas/ContentKitImage" }, { - "$ref": "#/components/parameters/spaceId" + "$ref": "#/components/schemas/ContentKitLink" } ], - "responses": { - "204": { - "description": "The space installation has been deleted." - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } + "discriminator": { + "propertyName": "type" } - } - }, - "/integrations/{integrationName}/installations/{installationId}/sites": { - "get": { - "operationId": "listIntegrationInstallationSites", - "summary": "List installations on sites for an integration in an organization", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" - }, - { - "$ref": "#/components/parameters/installationId" + }, + "ContentKitCard": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["card"] }, - { - "$ref": "#/components/parameters/listPage" + "title": { + "type": "string" }, - { - "$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/IntegrationSiteInstallation" - } - } - } - } - ] + "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" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "buttons": { + "type": "array", + "description": "Buttons displayed in the top right corner of the card.", + "items": { + "$ref": "#/components/schemas/ContentKitButton" + } } - } + }, + "required": ["type"] }, - "post": { - "operationId": "installIntegrationOnSite", - "summary": "Install integration on a site using an existing installation", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "ContentKitSelectOption": { + "type": "object", + "description": "An individual option in a select element", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/parameters/installationId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["siteId"], - "properties": { - "siteId": { - "type": "string", - "description": "ID of the site to install the integration on" - } - } + "label": { + "type": "string" + }, + "icon": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitIcon" + }, + { + "$ref": "#/components/schemas/ContentKitImage" } - } + ] } }, - "responses": { - "201": { - "headers": { - "Location": { - "description": "URL for the installed integration on the site", - "schema": { + "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" } } - }, - "description": "Integration installed successfully on site", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSiteInstallation" - } - } - } + ] }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "onValueChange": { + "$ref": "#/components/schemas/ContentKitAction" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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"] + } + ] } - } - } - }, - "/integrations/{integrationName}/installations/{installationId}/sites/{siteId}": { - "get": { - "operationId": "getIntegrationSiteInstallation", - "summary": "Get a specific integration's site installation", - "tags": ["integrations"], - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + }, + "required": ["type", "state", "options"] + }, + "ContentKitSwitch": { + "type": "object", + "description": "Renders a boolean input.", + "properties": { + "type": { + "type": "string", + "enum": ["switch"] }, - { - "$ref": "#/components/parameters/installationId" + "disabled": { + "type": "boolean" }, - { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "200": { - "description": "Integration site installation", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSiteInstallation" - } - } - } + "state": { + "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "type": "string" }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "initialValue": { + "description": "Value to initialize the switch with.", + "type": "boolean" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "onValueChange": { + "$ref": "#/components/schemas/ContentKitAction" + }, + "confirm": { + "$ref": "#/components/schemas/ContentKitConfirm" } - } + }, + "required": ["type", "state"] }, - "patch": { - "operationId": "updateIntegrationSiteInstallation", - "summary": "Update external IDs and configurations of an integration's installation for a site", - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "ContentKitRadio": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["radio"] }, - { - "$ref": "#/components/parameters/installationId" + "disabled": { + "type": "boolean" }, - { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "200": { - "description": "The site installation has been updated.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IntegrationSiteInstallation" - } + "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" } - } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "confirm": { + "$ref": "#/components/schemas/ContentKitConfirm" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpdateIntegrationSiteInstallation" + "required": ["type", "state", "value"] + }, + "ContentKitCheckbox": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["checkbox"] + }, + "state": { + "description": "State binding. The value of the input will be stored as a property in the state named after this ID.", + "type": "string" + }, + "value": { + "description": "Value to store in a state array when the checkbox is selected.", + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" } - } + ] + }, + "confirm": { + "$ref": "#/components/schemas/ContentKitConfirm" } - } + }, + "required": ["type", "state", "value"] }, - "delete": { - "operationId": "uninstallIntegrationFromSite", - "summary": "Uninstall the integration from a site", - "parameters": [ - { - "$ref": "#/components/parameters/integrationName" + "ContentKitInput": { + "type": "object", + "description": "Field for an input.", + "properties": { + "type": { + "type": "string", + "enum": ["input"] }, - { - "$ref": "#/components/parameters/installationId" + "label": { + "type": "string", + "description": "Text label displayed next to the input." }, - { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "204": { - "description": "The site installation has been deleted." + "hint": { + "oneOf": [ + { + "type": "string" + }, + { + "$ref": "#/components/schemas/ContentKitInlineElement" + } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs": { - "get": { - "operationId": "listOrganizationsForAuthenticatedUser", - "summary": "Get the list of organizations for the currently authenticated user", - "tags": ["organizations"], - "security": [ - { - "user": [] + "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" + } + ] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/listPage" + }, + "required": ["type", "label", "element"] + }, + "ContentKitHint": { + "type": "object", + "description": "Element used to contextualize other elements or info.", + "properties": { + "type": { + "type": "string", + "enum": ["hint"] }, - { - "$ref": "#/components/parameters/listLimit" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Organization" - } - } - }, - "required": ["items"] - } - ] - } - } + "children": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitInlineElement" } + } + }, + "required": ["type", "children"] + }, + "ContentKitBlockControl": { + "type": "object", + "description": "Control menu item displayed for the block.", + "properties": { + "icon": { + "$ref": "#/components/schemas/ContentKitIcon" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "label": { + "type": "string" + }, + "onPress": { + "$ref": "#/components/schemas/ContentKitAction" + }, + "confirm": { + "$ref": "#/components/schemas/ContentKitConfirm" } - } + }, + "required": ["label", "onPress"] }, - "post": { - "operationId": "createOrganization", - "summary": "Create an organization", - "tags": ["organizations"], - "security": [ - { - "user-internal": [] - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestCreateOrganization" - } + "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" } - } - }, - "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" + }, + "controls": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/ContentKitBlockControl" + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitBlockControl" + } } - } + ] } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } - } - } - }, - "/orgs/{organizationId}": { - "get": { - "operationId": "getOrganizationById", - "summary": "Get an organization by its ID", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Organization" - } - } + }, + "required": ["type", "children"] + }, + "ContentKitModal": { + "type": "object", + "description": "Overlay modal.", + "properties": { + "type": { + "type": "string", + "enum": ["modal"] + }, + "title": { + "type": "string" + }, + "subtitle": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentKitInlineElement" } }, - "404": { - "description": "No matching organization found for given id", - "$ref": "#/components/responses/NotFoundError" + "size": { + "type": "string", + "enum": ["medium", "xlarge", "fullscreen"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "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"] }, - "delete": { - "operationId": "deleteOrganizationById", - "summary": "Delete an organization by its ID", - "tags": ["organizations"], - "security": [ + "ContentKitRootElement": { + "description": "Element used as root", + "oneOf": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ContentKitBlock" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/ContentKitModal" } ], - "responses": { - "205": { - "description": "The organization has been successfully deleted" + "discriminator": { + "propertyName": "type" + } + }, + "ContentKitRenderOutput": { + "type": "object", + "description": "Output of the integration when rendering an UI.", + "properties": { + "element": { + "$ref": "#/components/schemas/ContentKitRootElement" }, - "404": { - "description": "No matching organization found for given id", - "$ref": "#/components/responses/NotFoundError" + "state": { + "type": "object" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "props": { + "type": "object" } - } + }, + "required": ["element", "state", "props"] }, - "patch": { - "operationId": "updateOrganizationById", - "summary": "Update an organization by its ID", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "$ref": "#/components/schemas/OrganizationTitle" - }, - "emailDomains": { - "$ref": "#/components/schemas/OrganizationEmailDomains" - }, - "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" - } - } - } - } + "RenderIntegrationUI": { + "type": "object", + "properties": { + "componentId": { + "type": "string", + "description": "ID of the component to render in the integration." + }, + "props": { + "type": "object", + "description": "Current properties of the UI." + }, + "state": { + "type": "object", + "description": "Current local state of the UI." + }, + "context": { + "$ref": "#/components/schemas/ContentKitContext" + }, + "action": { + "$ref": "#/components/schemas/ContentKitAction" } }, - "responses": { - "200": { - "description": "The organization has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Organization" - } - } - } + "required": ["componentId", "props", "context"] + }, + "UpdateIntegrationInstallation": { + "type": "object", + "properties": { + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, - "400": { - "description": "Invalid default content space or collection provided", - "$ref": "#/components/responses/BadRequestError" + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "space_selection": { + "$ref": "#/components/schemas/IntegrationInstallationSpaceSelection" + }, + "site_selection": { + "$ref": "#/components/schemas/IntegrationInstallationSiteSelection" } } - } - }, - "/orgs/{organizationId}/members": { - "get": { - "operationId": "listMembersInOrganizationById", - "summary": "List organization members", - "description": "Lists members for the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "APITemporaryToken": { + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "Temporary access token to authenticate with the API" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["token"] + }, + "UpdateIntegrationSpaceInstallation": { + "type": "object", + "properties": { + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, - { - "$ref": "#/components/parameters/listPage" + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" + } + } + }, + "IntegrationSiteInstallation": { + "type": "object", + "description": "Installation of an integration at a site level", + "properties": { + "integration": { + "description": "Unique name identifier of the integration", + "type": "string" }, - { - "$ref": "#/components/parameters/listLimit" + "installation": { + "description": "ID of the integration installation", + "type": "string" }, - { - "name": "role", - "description": "The Role to filter the member list by", - "in": "query", - "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/MemberRole" - }, - { - "type": "string", - "enum": ["guest"] - } - ] - } + "site": { + "description": "ID of the site the integration is installed on.", + "type": "string" }, - { - "name": "search", - "in": "query", - "description": "A query to filter the member list (displayName and email)", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationMember" - } - } - } - } - ] - } + "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" + ] + }, + "UpdateIntegrationSiteInstallation": { + "type": "object", + "properties": { + "externalIds": { + "$ref": "#/components/schemas/IntegrationInstallationExternalIds" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "configuration": { + "$ref": "#/components/schemas/IntegrationInstallationConfiguration" } } - } - }, - "/orgs/{organizationId}/members/{userId}": { - "get": { - "operationId": "getMemberInOrganizationById", - "summary": "Get specified organization member", - "description": "Gets a specific member in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "CreateOrganization": { + "type": "object", + "properties": { + "title": { + "$ref": "#/components/schemas/OrganizationTitle" + }, + "emailDomains": { + "$ref": "#/components/schemas/OrganizationEmailDomains" + }, + "type": { + "$ref": "#/components/schemas/OrganizationType" + }, + "useCase": { + "$ref": "#/components/schemas/OrganizationUseCase" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["title"] + }, + "OrganizationMember": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"member\"", + "enum": ["member"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the user." + }, + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "user": { + "$ref": "#/components/schemas/User" + }, + "disabled": { + "type": "boolean", + "description": "Whatever the membership of this user is disabled and prevent them from accessing content." + }, + "joinedAt": { + "description": "Date at which the user joined the organization.", + "$ref": "#/components/schemas/Timestamp" + }, + "lastSeenAt": { + "description": "Date at which the user was last seen active in the organization.", + "$ref": "#/components/schemas/Timestamp" + }, + "sso": { + "type": "boolean", + "description": "Whether the user can login with SSO." + }, + "spaces": { + "type": "number" + }, + "teams": { + "type": "number" + } + }, + "required": [ + "object", + "id", + "role", + "user", + "disabled", + "joinedAt", + "sso", + "spaces", + "teams" + ] + }, + "MemberContentPermission": { + "type": "object", + "description": "Permission of a member in a content.", + "properties": { + "permission": { + "$ref": "#/components/schemas/MemberRole" }, - { - "$ref": "#/components/parameters/userId" + "space": { + "$ref": "#/components/schemas/Space" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationMember" - } - } - } + }, + "required": ["permission", "space"] + }, + "OrganizationTeamTitle": { + "type": "string", + "description": "Title of the team", + "minLength": 1, + "maxLength": 64 + }, + "OrganizationTeam": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"team\"", + "enum": ["team"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "id": { + "type": "string", + "description": "Unique identifier for the team." + }, + "title": { + "$ref": "#/components/schemas/OrganizationTeamTitle" + }, + "members": { + "type": "integer", + "description": "Count of members in this team." + }, + "spaces": { + "type": "number", + "description": "Count of spaces this team has access to." + }, + "createdAt": { + "description": "Date at which the team was created.", + "$ref": "#/components/schemas/Timestamp" } - } + }, + "required": ["object", "id", "title", "members", "spaces", "createdAt"] }, - "patch": { - "operationId": "updateMemberInOrganizationById", - "summary": "Update specified organization member", - "description": "Updates a specific member in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] + "TeamMemberRole": { + "type": "string", + "description": "\"The role of a team member.\n\"owner\": Can manage team members.\n\"member\": Is a member of the team.\n", + "enum": ["owner", "member"] + }, + "TeamMember": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/TeamMemberRole" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["role"] + }, + "OrganizationTeamMember": { + "type": "object", + "description": "A member of a team in an organization, including its relationship to it", + "properties": { + "organization": { + "$ref": "#/components/schemas/OrganizationMember" }, - { - "$ref": "#/components/parameters/userId" + "team": { + "$ref": "#/components/schemas/TeamMember" } - ], - "responses": { - "200": { - "description": "The member has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationMember" - } - } + }, + "required": ["organization", "team"] + }, + "UpdateMembersInOrganizationTeam": { + "type": "object", + "properties": { + "add": { + "type": "array", + "items": { + "type": "string", + "description": "A user to add. It can either be a user ID or an email." } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "role": { - "$ref": "#/components/schemas/MemberRoleOrGuest" - } - } - } + "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." } } } }, - "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" + "InviteUsersToOrganization": { + "type": "object", + "properties": { + "emails": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "string", + "description": "The email address of the user to invite as a member" + }, + { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address of the user to invite as a member" + }, + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + } + }, + "required": ["email", "role"] + } + ] + } }, - { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "204": { - "description": "The member was deleted from the organization." + "role": { + "description": "Default role to set on newly invited members.", + "$ref": "#/components/schemas/MemberRoleOrGuest" }, - "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", - "tags": ["organizations"], - "security": [ - { - "user": [] + "sso": { + "description": "If true, invites the user as an SSO user of the organization. Defaults to false.", + "type": "boolean" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["emails"] + }, + "CreateInviteToOrganization": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The role of the member in the organization" } - ], - "responses": { - "204": { - "description": "Organization member has been updated." + }, + "required": ["role"] + }, + "CreateInviteToSpace": { + "type": "object", + "properties": { + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The level of the member in the target space" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "space": { + "type": "string", + "description": "The ID of space the member has been invited to" } - } - } - }, - "/orgs/{organizationId}/members/{userId}/sso": { - "post": { - "operationId": "setUserAsSSOMemberForOrganization", - "summary": "Set a user as an SSO member of an organization", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "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" } - ], - "parameters": [ + }, + "required": ["level", "collection"] + }, + "CreateOrganizationInvite": { + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/CreateInviteToOrganization" }, { - "$ref": "#/components/parameters/userId" - } - ], - "responses": { - "200": { - "description": "The user has been added as an SSO member of the organization.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationMember" - } - } - } + "$ref": "#/components/schemas/CreateInviteToSpace" }, - "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"], - "security": [ { - "user": [] + "$ref": "#/components/schemas/CreateInviteToCollection" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + ] + }, + "InviteToOrganization": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The role of the member in the organization" + } + }, + "required": ["role"] + }, + "InviteToSpace": { + "type": "object", + "properties": { + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest", + "description": "The level of the member in the target space" }, - { - "$ref": "#/components/parameters/userId" + "space": { + "$ref": "#/components/schemas/Space", + "description": "The space the member has been invited to" + } + }, + "required": ["level", "space"] + }, + "InviteToCollection": { + "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"] + }, + "OrganizationInvite": { + "allOf": [ { - "$ref": "#/components/parameters/listPage" + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"invite\"", + "enum": ["invite"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the organization invite" + } + }, + "required": ["object", "id"] }, { - "$ref": "#/components/parameters/listLimit" + "oneOf": [ + { + "$ref": "#/components/schemas/InviteToOrganization" + }, + { + "$ref": "#/components/schemas/InviteToSpace" + }, + { + "$ref": "#/components/schemas/InviteToCollection" + } + ] } - ], - "responses": { - "200": { - "description": "Listing of spaces that can be accessed by the user in the organization.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MemberContentPermission" - } - } - } - } - ] + ] + }, + "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_2024", + "plus_2024", + "pro_2024", + "enterprise_2024", + "free", + "plus", + "pro", + "team", + "business", + "legacy", + "startup", + "enterprise" + ] + }, + "BillingInterval": { + "type": "string", + "description": "Interval for a billing subscription", + "enum": ["monthly", "yearly"] + }, + "UpgradeOrganizationBilling": { + "type": "object", + "properties": { + "product": { + "$ref": "#/components/schemas/BillingProduct" + }, + "interval": { + "$ref": "#/components/schemas/BillingInterval" + }, + "exclude": { + "type": "object", + "description": "Members to remove or sites to unpublish before upgrading", + "minProperties": 1, + "properties": { + "members": { + "type": "array", + "items": { + "type": "string", + "description": "A list of member identifiers to be removed" + } + }, + "premiumSites": { + "type": "array", + "items": { + "type": "string", + "description": "A list of premium site identifiers to be unpublished" + } + }, + "audienceSites": { + "type": "array", + "items": { + "type": "string", + "description": "A list of audience site identifiers to be unpublished" } } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "reason": { + "type": "string", + "description": "Reason that triggered the billing upgrade" + }, + "mode": { + "type": "string", + "description": "Mode to use for the upgrade (default value is `commit`): - `auto`: user is redirect to checkout if possible, other a preview of the auto-upgrade is returned. - `commit`: a checkout session is returned or an auto-upgrade is done - `preview`: a preview invoice is always returned\n", + "enum": ["auto", "commit", "preview"] } - } - } - }, - "/orgs/{organizationId}/members/{userId}/teams": { - "get": { - "operationId": "listTeamsForOrganizationMember", - "summary": "List all teams an organization member is part of", - "tags": ["teams"], - "security": [ - { - "user": [] + }, + "required": ["product", "interval"] + }, + "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"] + } } - ], - "parameters": [ + }, + "required": [ + "amount", + "amountDueToday", + "customerBalance", + "remainingCustomerBalance", + "lines" + ] + }, + "BillingUpgrade": { + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": ["checkout"] + }, + "sessionId": { + "type": "string", + "description": "Stripe payment session ID" + } + }, + "required": ["result", "sessionId"] }, { - "$ref": "#/components/parameters/userId" + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": ["preview"] + }, + "invoice": { + "$ref": "#/components/schemas/BillingInvoicePreview" + } + }, + "required": ["result", "invoice"] }, { - "$ref": "#/components/parameters/listPage" + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": ["upgraded"] + } + }, + "required": ["result"] }, { - "$ref": "#/components/parameters/listLimit" + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": ["downgraded"] + } + }, + "required": ["result"] }, { - "in": "query", - "name": "title", - "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "type": "object", - "required": ["team", "member"], - "properties": { - "team": { - "$ref": "#/components/schemas/OrganizationTeam" - }, - "member": { - "$ref": "#/components/schemas/TeamMember" - } - } - } - } - } - } - ] - } + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": ["interval_changed"] } - } + }, + "required": ["result"] + } + ] + }, + "CreateSpace": { + "type": "object", + "properties": { + "title": { + "type": "string", + "maxLength": 50 }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "emoji": { + "$ref": "#/components/schemas/Emoji" + }, + "private": { + "description": "Private spaces are no longer supported by GitBook.", + "deprecated": true, + "type": "boolean" + }, + "parent": { + "type": "string", + "description": "ID of a parent collection" } } - } - }, - "/orgs/{organizationId}/teams": { - "get": { - "operationId": "listTeamsInOrganizationById", - "summary": "List organization teams", - "description": "Lists teams for the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "SpaceWithGitSync": { + "type": "object", + "properties": { + "space": { + "$ref": "#/components/schemas/Space" }, - { - "$ref": "#/components/parameters/listPage" + "gitSync": { + "deprecated": true, + "$ref": "#/components/schemas/GitSyncState" + } + }, + "required": ["space"] + }, + "OrganizationExperimentalFeature": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/parameters/listLimit" + "title": { + "type": "string" }, - { - "in": "query", - "name": "owner", - "description": "The unique identifier of a member of the organization. Only teams they can manage will be returned.", - "schema": { - "type": "string" - } + "description": { + "type": "string" }, - { - "in": "query", - "name": "title", - "description": "If provided, only teams whose name contains the given parameter will be returned. Case insensitive.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationTeam" - } - } - } - } - ] - } - } - } + "enabled": { + "type": "boolean" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "stage": { + "type": "string", + "enum": ["alpha", "beta"] } - } + }, + "required": ["id", "title", "description", "enabled", "stage"] }, - "put": { - "operationId": "createOrganizationTeam", - "summary": "Create organization team", - "description": "Creates a team in the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "201": { - "description": "Team has been created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationTeam" - } + "SAMLProviderLabel": { + "type": "string", + "minLength": 1, + "maxLength": 30 + }, + "SAMLProviderEntityID": { + "type": "string", + "maxLength": 1024 + }, + "SAMLProviderCertificate": { + "type": "string", + "maxLength": 10000 + }, + "OrganizationSAMLProvider": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"saml-provider\"", + "enum": ["saml-provider"] + }, + "id": { + "type": "string", + "description": "Unique identifier for the provider." + }, + "label": { + "$ref": "#/components/schemas/SAMLProviderLabel" + }, + "ssoURL": { + "$ref": "#/components/schemas/URL" + }, + "entityID": { + "$ref": "#/components/schemas/SAMLProviderEntityID" + }, + "certificate": { + "$ref": "#/components/schemas/SAMLProviderCertificate" + }, + "defaultTeam": { + "$ref": "#/components/schemas/OrganizationTeam" + }, + "defaultRole": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "createdAt": { + "description": "Date at which the provider was created.", + "$ref": "#/components/schemas/Timestamp" + }, + "service": { + "description": "Metadata about the service provider.", + "properties": { + "acsURL": { + "type": "string", + "description": "Assertion Consumer Service (ACS) URL", + "format": "uri" + }, + "startURL": { + "type": "string", + "description": "Start URL for the Identity Provider", + "format": "uri" + }, + "entityID": { + "$ref": "#/components/schemas/SAMLProviderEntityID" } - } + }, + "required": ["acsURL", "startURL", "entityID"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the SAML Provider in the API", + "format": "uri" + } + }, + "required": ["location"] } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "$ref": "#/components/schemas/OrganizationTeamTitle" - }, - "members": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["title"] - } - } + "required": [ + "object", + "id", + "label", + "ssoURL", + "entityID", + "certificate", + "defaultRole", + "createdAt", + "service", + "urls" + ] + }, + "OrganizationUsageSpaces": { + "type": "object", + "description": "Spaces usage metrics of an organization", + "properties": { + "total": { + "description": "Count of all spaces", + "type": "number" } - } - } - }, - "/orgs/{organizationId}/teams/{teamId}": { - "get": { - "operationId": "getTeamInOrganizationById", - "summary": "Get specified organization team", - "description": "Gets a specific team in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["total"] + }, + "OrganizationUsageCollections": { + "type": "object", + "description": "Collections usage metrics of an organization", + "properties": { + "total": { + "description": "Count of all collections", + "type": "number" } - ], - "parameters": [ + }, + "required": ["total"] + }, + "OrganizationUsageSites": { + "type": "object", + "description": "Sites usage metrics of an organization", + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "properties": { + "total": { + "description": "Count of all sites", + "type": "number" + }, + "legacyBasic": { + "description": "Count of all legacy basic sites", + "type": "number" + }, + "legacyPremium": { + "description": "Count of all legacy premium sites", + "type": "number" + } + }, + "required": ["total", "legacyBasic", "legacyPremium"] }, { - "$ref": "#/components/parameters/teamId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationTeam" - } + "properties": { + "total": { + "description": "Count of all sites", + "type": "number" + }, + "basic": { + "description": "Count of all basic sites", + "type": "number" + }, + "premium": { + "description": "Count of all premium sites", + "type": "number" + }, + "audience": { + "description": "Count of all audience sites", + "type": "number" } - } + }, + "required": ["total", "basic", "premium", "audience"] + } + ] + }, + "OrganizationUsageTeams": { + "type": "object", + "description": "Team members usage metrics of an organization", + "properties": { + "total": { + "description": "Count of all teams", + "type": "number" + } + }, + "required": ["total"] + }, + "OrganizationUsageMembers": { + "type": "object", + "description": "Members usage metrics of an organization", + "properties": { + "total": { + "description": "Count of all members", + "type": "number" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "seats": { + "description": "Count of all paid seats", + "type": "number" + }, + "admin": { + "description": "Count of all admins", + "type": "number" + }, + "create": { + "description": "Count of all creators", + "type": "number" + }, + "edit": { + "description": "Count of all editors", + "type": "number" + }, + "review": { + "description": "Count of all reviewers", + "type": "number" + }, + "comment": { + "description": "Count of all commenters", + "type": "number" + }, + "read": { + "description": "Count of all readers", + "type": "number" + }, + "guest": { + "description": "Count of all guests", + "type": "number" } - } + }, + "required": [ + "total", + "seats", + "admin", + "create", + "edit", + "review", + "comment", + "read", + "guest" + ] }, - "patch": { - "operationId": "updateTeamInOrganizationById", - "summary": "Update specified organization team", - "description": "Updates a specific team in an organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] + "OrganizationUsageTeamMembers": { + "type": "object", + "description": "Team members usage metrics of an organization", + "properties": { + "total": { + "description": "Count of all organization members in a team", + "type": "number" + }, + "owner": { + "description": "Count of all team owners", + "type": "number" + }, + "member": { + "description": "Count of all team members", + "type": "number" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["total", "owner", "member"] + }, + "OrganizationUsage": { + "type": "object", + "description": "All usage metrics of an organization", + "properties": { + "spaces": { + "$ref": "#/components/schemas/OrganizationUsageSpaces" + }, + "collections": { + "$ref": "#/components/schemas/OrganizationUsageCollections" + }, + "sites": { + "$ref": "#/components/schemas/OrganizationUsageSites" + }, + "teams": { + "$ref": "#/components/schemas/OrganizationUsageTeams" + }, + "members": { + "$ref": "#/components/schemas/OrganizationUsageMembers" }, + "teamMembers": { + "$ref": "#/components/schemas/OrganizationUsageTeamMembers" + } + }, + "required": ["spaces", "collections", "sites", "teams", "members", "teamMembers"] + }, + "CaptureTitle": { + "type": "string", + "description": "Optional title describing the capture", + "maxLength": 100 + }, + "CaptureContext": { + "oneOf": [ { - "$ref": "#/components/parameters/teamId" + "type": "string", + "enum": ["thread", "walkthrough", "document"] } - ], - "responses": { - "200": { - "description": "The team has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationTeam" + ] + }, + "Capture": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the capture" + }, + "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 source from which the capture originated" + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "stoppedAt": { + "type": "string", + "format": "date-time" + }, + "editedAt": { + "type": "string", + "format": "date-time" + }, + "events": { + "description": "Count of events recorded.", + "properties": { + "terminal.command": { + "type": "integer" + }, + "speech": { + "type": "integer" + }, + "thread.message": { + "type": "integer" + } + } + }, + "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", + "minItems": 1, + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/Integration" + }, + { + "$ref": "#/components/schemas/User" } - } + ] } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "$ref": "#/components/schemas/OrganizationTeamTitle" - } - }, - "required": ["title"] + "output": { + "description": "Output document for the capture. Is not set when capture is not finished.", + "$ref": "#/components/schemas/Document" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the capture in the API", + "format": "uri" + }, + "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" + ] }, - "delete": { - "operationId": "removeTeamFromOrganizationById", - "summary": "Delete a team in an organization", - "description": "Deletes a specific team in an organization\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "BaseCaptureEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of event" }, - { - "$ref": "#/components/parameters/teamId" - } - ], - "responses": { - "204": { - "description": "The team was deleted from the organization." + "timestamp": { + "type": "string", + "format": "date-time", + "description": "When the event happened" }, - "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", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "source": { + "type": "string", + "description": "Optionally, provide the source of the event. GitBook may use this to improve the generated content.", + "maxLength": 50 }, - { - "$ref": "#/components/parameters/teamId" - } - ], - "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." - } - } - } + "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"] } }, - "responses": { - "204": { - "description": "Members have been updated" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } + "required": ["type", "timestamp"] }, - "get": { - "operationId": "listTeamMembersInOrganizationById", - "summary": "List team members", - "description": "Lists members, and their roles, for the specified organization team.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/teamId" - }, + "CaptureTerminalCommandEvent": { + "allOf": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/BaseCaptureEvent" }, { - "$ref": "#/components/parameters/listLimit" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationTeamMember" - } - } - } - } - ] - } + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["terminal.command"] + }, + "command": { + "type": "string" + }, + "stdout": { + "type": "string" } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/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", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["type", "command", "stdout"] } - ], - "parameters": [ + ] + }, + "CaptureSpeechEvent": { + "allOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/BaseCaptureEvent" }, { - "$ref": "#/components/parameters/teamId" + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["speech"] + } + }, + "required": ["type"] }, - { - "$ref": "#/components/parameters/userId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { + { + "oneOf": [ + { "type": "object", "properties": { - "role": { - "$ref": "#/components/schemas/TeamMemberRole" + "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"] } - } - } - }, - "responses": { - "204": { - "description": "Member has been added to the team" - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + ] } - } + ] }, - "delete": { - "operationId": "deleteMemberFromOrganizationTeamById", - "summary": "Delete members from a team", - "description": "Deletes member from the specified organization team.\n", - "tags": ["organizations"], - "security": [ + "CaptureThreadMessageEvent": { + "allOf": [ { - "user": [] + "$ref": "#/components/schemas/BaseCaptureEvent" + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["thread.message"] + }, + "isFirst": { + "type": "boolean" + }, + "text": { + "type": "string" + } + }, + "required": ["type", "text"] } - ], - "parameters": [ + ] + }, + "CaptureFileAddedEvent": { + "allOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/BaseCaptureEvent" }, { - "$ref": "#/components/parameters/teamId" + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file.added"] + }, + "filename": { + "type": "string" + }, + "fileSnapshot": { + "type": "string" + } + }, + "required": ["type", "filename", "fileSnapshot"] + } + ] + }, + "CaptureFileChangedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, { - "$ref": "#/components/parameters/userId" + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file.changed"] + }, + "filename": { + "type": "string" + }, + "fileDiff": { + "type": "string" + } + }, + "required": ["type", "filename", "fileDiff"] } - ], - "responses": { - "204": { - "description": "Member has been deleted from the team" + ] + }, + "CaptureFileRemovedEvent": { + "allOf": [ + { + "$ref": "#/components/schemas/BaseCaptureEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/invites": { - "post": { - "operationId": "inviteUsersToOrganization", - "summary": "Invite users to a given organization based on a list of emails", - "tags": ["organizations"], - "security": [ { - "user": [] + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["file.removed"] + }, + "filename": { + "type": "string" + }, + "fileSnapshot": { + "type": "string" + } + }, + "required": ["type", "filename", "fileSnapshot"] } - ], - "parameters": [ + ] + }, + "CaptureEvent": { + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "users": { - "type": "array", - "items": { - "type": "string", - "description": "The unique identifiers of the users who were added to the organization" - } - }, - "invited": { - "type": "number", - "description": "The number of users who were added to the organization" - }, - "failedSSOEmails": { - "type": "array", - "items": { - "type": "string", - "description": "A list of emails who were invited to the organization, but who were not added as SSO users as they are members of another org" - } - } - }, - "required": ["users", "invited"] - } - } - } + "$ref": "#/components/schemas/CaptureTerminalCommandEvent" }, - "400": { - "$ref": "#/components/responses/BadRequestError" + { + "$ref": "#/components/schemas/CaptureSpeechEvent" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestInviteUsersToOrganization" - } - } - } - } - } - }, - "/orgs/{organizationId}/invites/{inviteId}": { - "post": { - "operationId": "joinOrganizationWithInvite", - "summary": "Use an invite to join an organization.", - "tags": ["organizations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/CaptureThreadMessageEvent" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/CaptureFileAddedEvent" }, { - "$ref": "#/components/parameters/inviteId" + "$ref": "#/components/schemas/CaptureFileChangedEvent" + }, + { + "$ref": "#/components/schemas/CaptureFileRemovedEvent" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } + ] + }, + "UpdateSnippetSchema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "A new title for the snippet." + } + } + }, + "SiteType": { + "type": "string", + "description": "The type of the site", + "enum": ["basic", "premium", "audience", "legacy-basic", "legacy-premium"] + }, + "SiteTitle": { + "type": "string", + "description": "Title of the site", + "minLength": 2, + "maxLength": 128 + }, + "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]$" + }, + "SiteBasename": { + "type": "string", + "description": "Basename for the site. For e.g. api", + "minLength": 1, + "maxLength": 100 + }, + "SiteVisibility": { + "type": "string", + "description": "The visibility setting of the site determines the audience of the site.\n* `public`: Anyone can access the site, and the site is indexed by search engines.\n* `unlisted`: Anyone can access the site, and the site is not indexed by search engines\n* `share-link`: Anyone with a secret token in the url can access the site.\n* `visitor-auth`: Anyone authenticated through a JWT token can access the site.\n", + "enum": ["public", "unlisted", "share-link", "visitor-auth"] + }, + "SiteAdsTopic": { + "type": "string", + "description": "Topic of the content", + "enum": ["webdev", "crypto"] + }, + "SiteAds": { + "oneOf": [ + { + "type": "object", + "required": ["status", "submittable"], + "properties": { + "status": { + "type": "string", + "enum": ["pending"] + }, + "submittable": { + "type": "boolean", + "description": "True if the user can submit the site for review." } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/link-invites": { - "post": { - "operationId": "createOrganizationInvite", - "summary": "Create a new organization invite", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateOrganizationInvite" - } - } - } - }, - "responses": { - "201": { - "description": "The organization invite has been created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationInvite" - } + "type": "object", + "required": ["status", "topic", "accountEmail"], + "properties": { + "status": { + "type": "string", + "enum": ["in-review"] + }, + "topic": { + "$ref": "#/components/schemas/SiteAdsTopic" } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/link-invites/{inviteId}": { - "patch": { - "operationId": "updateOrganizationInviteById", - "summary": "Update an organization invite.", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "type": "object", + "required": ["status"], + "properties": { + "status": { + "type": "string", + "enum": ["rejected"] + } + } }, { - "$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"] - } - ] + "type": "object", + "required": ["status", "topic", "zoneId"], + "properties": { + "status": { + "type": "string", + "enum": ["live", "disabled"] + }, + "topic": { + "$ref": "#/components/schemas/SiteAdsTopic" + }, + "zoneId": { + "type": "string", + "description": "The ad network zone ID" } } } - }, - "responses": { - "200": { - "description": "The organization invite has been updated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrganizationInvite" - } - } - } + ] + }, + "Site": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["site"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "id": { + "type": "string", + "description": "Unique identifier of the site" + }, + "type": { + "$ref": "#/components/schemas/SiteType" + }, + "title": { + "$ref": "#/components/schemas/SiteTitle" + }, + "hostname": { + "$ref": "#/components/schemas/SiteHostname" + }, + "basename": { + "$ref": "#/components/schemas/SiteBasename" + }, + "visibility": { + "$ref": "#/components/schemas/SiteVisibility" + }, + "published": { + "type": "boolean", + "description": "Whether the site is live or not. If true, the site is accessible to the audience defined by the visibility setting." + }, + "siteSpaces": { + "type": "number" + }, + "createdAt": { + "type": "string", + "format": "date-time" + }, + "ads": { + "$ref": "#/components/schemas/SiteAds" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the site in the API", + "format": "uri" + }, + "app": { + "type": "string", + "description": "URL of the site in the application", + "format": "uri" + }, + "published": { + "type": "string", + "description": "URL of the published version of the site. Only defined when site is published.", + "format": "uri" + } + }, + "required": ["app", "location"] } - } + }, + "required": [ + "object", + "id", + "type", + "title", + "visibility", + "published", + "createdAt", + "siteSpaces", + "defaultSpace", + "urls" + ] }, - "delete": { - "operationId": "deleteOrganizationInviteById", - "summary": "Deletes an organization invite.", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ + "BillingOperationPreviewResponse": { + "description": "A response to a request to preview a paid operation or action. A user might preview an operation before executing it to see which billing steps would be required (if any). This schema defines the response of that preview request.\n", + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "type": "object", + "properties": { + "type": { + "description": "User can go ahead with the operation without any additional steps. Their subscription will be updated to reflect the new changes.", + "type": "string", + "enum": ["go-ahead"] + } + }, + "required": ["type"] }, { - "$ref": "#/components/parameters/inviteId" - } - ], - "responses": { - "205": { - "description": "The organization invite has been deleted" + "type": "object", + "properties": { + "type": { + "description": "By going ahead with this operation, the user will be starting a trial in GitBook.", + "type": "string", + "enum": ["trial-available"] + } + }, + "required": ["type"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/billing": { - "post": { - "operationId": "upgradeOrganizationPlan", - "summary": "Upgrade an organization's billing plan", - "tags": ["organizations"], - "security": [ { - "user-internal": [] - } - ], - "parameters": [ + "type": "object", + "properties": { + "type": { + "description": "User must checkout to complete the operation.", + "type": "string", + "enum": ["checkout"] + }, + "invoice": { + "$ref": "#/components/schemas/BillingInvoicePreview" + } + }, + "required": ["type"] + }, { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BillingUpgrade" - } + "type": "object", + "properties": { + "type": { + "description": "User cannot proceed with the operation due to lack of permissions.", + "type": "string", + "enum": ["no-permissions"] } - } + }, + "required": ["type"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestUpgradeOrganizationBilling" + { + "type": "object", + "properties": { + "type": { + "description": "User needs to go through the legacy upgrade flow.", + "type": "string", + "enum": ["legacy-upgrade"] + }, + "plan": { + "description": "The plan the user must upgrade to.", + "$ref": "#/components/schemas/BillingProduct" + }, + "invoice": { + "$ref": "#/components/schemas/BillingInvoicePreview" } - } + }, + "required": ["type", "plan"] } - } + ] }, - "get": { - "operationId": "getOrganizationBillingPortal", - "summary": "Get the billing portal for an organization", - "tags": ["organizations"], - "security": [ - { - "user-internal": [] - } - ], - "parameters": [ + "SitePublishingAuth": { + "allOf": [ { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BillingPortal" - } + "oneOf": [ + { + "$ref": "#/components/schemas/VisitorAuthCustomBackend" + }, + { + "$ref": "#/components/schemas/VisitorAuthIntegrationBackend" } - } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/request_upgrade": { - "post": { - "operationId": "requestOrganizationUpgrade", - "summary": "Send a request to ask the organization's admin to upgrade it.", - "tags": ["organizations"], - "security": [ { - "user-internal": [] + "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." + }, + "integration": { + "type": "string", + "description": "Name of the Visitor Authentication integration installed on the site (if any).\nIt is also the one being used as VA backend when the published auth settings are configured to use \"integration\" as backend.\n" + } + }, + "required": ["object", "privateKey"] } - ], - "parameters": [ + ] + }, + "SitePublishingAuthUpdate": { + "allOf": [ { - "$ref": "#/components/parameters/organizationId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } + "oneOf": [ + { + "$ref": "#/components/schemas/VisitorAuthCustomBackend" + }, + { + "$ref": "#/components/schemas/VisitorAuthIntegrationBackend" } - } + ] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/transfer": { - "post": { - "operationId": "transferOrganization", - "summary": "Transfer one organization (source) into another organization (target).", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "type": "object", + "properties": { + "fallbackURL": { + "type": "string", + "format": "uri", + "description": "A fallback URL that will be used if authentication fails." + } + } } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { + ] + }, + "CustomizationIconsStyle": { + "type": "string", + "enum": ["regular", "solid", "duotone", "light", "thin"] + }, + "SiteCustomizationSettings": { + "type": "object", + "properties": { + "title": { + "description": "Title to use for the published site. If not defined, it'll fallback to the default content title.", + "$ref": "#/components/schemas/SiteTitle" + }, + "styling": { + "type": "object", + "properties": { + "primaryColor": { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + "corners": { + "$ref": "#/components/schemas/CustomizationCorners" + }, + "font": { + "$ref": "#/components/schemas/CustomizationFont" + }, + "background": { + "$ref": "#/components/schemas/CustomizationBackground" + }, + "icons": { + "$ref": "#/components/schemas/CustomizationIconsStyle" + } + }, + "required": ["primaryColor", "corners", "font", "background", "icons"] + }, + "internationalization": { + "type": "object", + "properties": { + "locale": { + "$ref": "#/components/schemas/CustomizationLocale" + } + }, + "required": ["locale"] + }, + "favicon": { + "oneOf": [ + { "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"] - } - ] + "icon": { + "$ref": "#/components/schemas/CustomizationThemedURL" } - } - } - } - } - }, - "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." - } + }, + "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" } } - } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/search": { - "get": { - "operationId": "searchOrganizationContent", - "summary": "Search content in an organization", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + }, + "required": ["preset", "links"] }, - { - "$ref": "#/components/parameters/organizationId" + "footer": { + "type": "object", + "properties": { + "logo": { + "$ref": "#/components/schemas/CustomizationThemedURL" + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomizationFooterGroup" + } + }, + "copyright": { + "type": "string", + "maxLength": 300 + } + }, + "required": ["groups"] }, - { - "$ref": "#/components/parameters/listPage" + "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"] }, - { - "$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" - } - } - } - } - ] - } + "pdf": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, PDF export is enabled for the published site." } - } + }, + "required": ["enabled"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/spaces": { - "get": { - "operationId": "listSpacesInOrganizationById", - "summary": "List organization spaces", - "description": "Lists spaces for the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "feedback": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, feedback gathering is enabled" + } + }, + "required": ["enabled"] }, - { - "$ref": "#/components/parameters/listPage" + "aiSearch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, AI search is enabled" + } + }, + "required": ["enabled"] }, - { - "$ref": "#/components/parameters/listLimit" + "advancedCustomization": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, Advanced customization is enabled" + } + }, + "required": ["enabled"] }, - { - "name": "visibility", - "in": "query", - "description": "If defined, only content with this visibility will be returned.", - "schema": { - "$ref": "#/components/schemas/ContentVisibility" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Space" - } - } - } - } - ] - } + "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"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "createSpace", - "summary": "Create an organization space", - "tags": ["spaces"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RequestCreateSpace" + "pagination": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the pagination navigation should be displayed on pages." } - } - } - }, - "responses": { - "201": { - "description": "Space created", - "headers": { - "Location": { - "description": "API URL for the newly created space", - "schema": { - "type": "string" - } + }, + "required": ["enabled"] + }, + "trademark": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Space" - } + "required": ["enabled"] + }, + "privacyPolicy": { + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "socialPreview": { + "type": "object", + "properties": { + "url": { + "$ref": "#/components/schemas/URL" + } + } } - } - } - }, - "/orgs/{organizationId}/spaces/gitsync": { - "get": { - "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": [ - { - "user": [] + }, + "required": [ + "styling", + "internationalization", + "favicon", + "header", + "footer", + "themes", + "pdf", + "feedback", + "aiSearch", + "advancedCustomization", + "trademark", + "pagination", + "git", + "privacyPolicy", + "socialPreview" + ] + }, + "SiteIntegrationScript": { + "type": "object", + "properties": { + "script": { + "description": "Script URL to load.", + "$ref": "#/components/schemas/URL" + }, + "contentSecurityPolicy": { + "description": "Content Security Policy to secure the loading of this script.", + "type": "string" + }, + "cookies": { + "type": "boolean", + "description": "If true, the script will potentially load use cookies and visitors should be aware." } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["script", "cookies"] + }, + "SiteSpacePath": { + "type": "string", + "description": "Path to the space on the site", + "minLength": 1, + "maxLength": 100 + }, + "SiteSpace": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "The object type, which is always \"site-space\"", + "enum": ["site-space"] }, - { - "$ref": "#/components/parameters/listPage" + "id": { + "type": "string", + "description": "Unique identifier of the site-space" }, - { - "$ref": "#/components/parameters/listLimit" + "path": { + "$ref": "#/components/schemas/SiteSpacePath" }, - { - "name": "status", - "in": "query", - "description": "If defined, only spaces with matching Git sync status are returned", - "schema": { - "$ref": "#/components/schemas/GitSyncOperationState" - } - } - ], - "responses": { - "200": { - "description": "OK", - "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": { - "deprecated": true, - "$ref": "#/components/schemas/GitSyncState" - } - }, - "required": ["space"] - } - } - } - } - ] - } - } - } + "space": { + "$ref": "#/components/schemas/Space" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/collections": { - "get": { - "operationId": "listCollectionsInOrganizationById", - "summary": "List organization collections", - "description": "Lists collections for the specified organization.\n", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "title": { + "type": "string" }, - { - "$ref": "#/components/parameters/listPage" + "default": { + "type": "boolean", + "description": "Whether this is the default space for the site" }, - { - "$ref": "#/components/parameters/listLimit" + "hasAdvancedCustomizationFeature": { + "type": "boolean", + "description": "Whether the space has advanced customization feature enabled" }, - { - "name": "nested", - "in": "query", - "description": "If true, all nested collections will be listed", - "schema": { - "type": "boolean", - "default": true - } + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "published": { + "type": "string", + "description": "URL of the published version of the site-space. Only defined when site is published.", + "format": "uri" + } + }, + "required": ["location"] } - ], - "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" - } - } - } - } - ] - } + }, + "required": ["id", "space", "title", "path", "urls"] + }, + "SiteSpaceCustomizationOverrides": { + "type": "object", + "properties": { + "title": { + "description": "Title to use for the published site variant. If not defined, it'll fallback to the content title.", + "$ref": "#/components/schemas/SiteTitle" + }, + "styling": { + "type": "object", + "properties": { + "primaryColor": { + "description": "The primary color used for links and UI text. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "corners": { + "description": "The style of the corners to use. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationCorners" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "font": { + "description": "The font family to use for the content. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationFont" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "icons": { + "description": "The icons style to use for the content. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationIconsStyle" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "background": { + "description": "The style of background to use. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationBackground" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "createCollection", - "summary": "Create an organization collection", - "tags": ["collections"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { + "internationalization": { + "type": "object", + "properties": { + "locale": { + "description": "The locale to use for the non-custom elements of the UI. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationLocale" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + } + }, + "required": ["locale"] + }, + "favicon": { + "description": "The favicon to use. Set to null to reset the override.", + "oneOf": [ + { "type": "object", "properties": { - "title": { + "icon": { + "$ref": "#/components/schemas/CustomizationThemedURL" + } + }, + "required": ["icon"] + }, + { + "type": "object", + "properties": { + "emoji": { + "$ref": "#/components/schemas/Emoji" + } + }, + "required": ["emoji"] + }, + { + "type": "object", + "nullable": true, + "properties": {}, + "additionalProperties": false + } + ] + }, + "header": { + "type": "object", + "properties": { + "preset": { + "description": "The theme preset to use. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationHeaderPreset" + }, + { "type": "string", - "maxLength": 50 + "nullable": true, + "enum": [null] + } + ] + }, + "logo": { + "description": "The header logo to use. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemedURL" }, - "parent": { + { "type": "string", - "description": "ID of a parent collection" + "nullable": true, + "enum": [null] + } + ] + }, + "backgroundColor": { + "description": "The background color used in the header. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "linkColor": { + "description": "The color used by the links in the header. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemedColor" + }, + { + "type": "string", + "nullable": true, + "enum": [null] } + ] + }, + "links": { + "type": "array", + "description": "The links that are displayed in the header. Set to null to reset the override.", + "nullable": true, + "items": { + "$ref": "#/components/schemas/CustomizationHeaderLink" } } } - } - }, - "responses": { - "201": { - "description": "Collection created", - "headers": { - "Location": { - "description": "API URL for the newly created collection", - "schema": { - "type": "string" + }, + "footer": { + "type": "object", + "properties": { + "logo": { + "description": "The logo displayed in the footer. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemedURL" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "groups": { + "type": "array", + "description": "The links groups that are displayed in the footer. Set to null to reset the override.", + "nullable": true, + "items": { + "$ref": "#/components/schemas/CustomizationFooterGroup" } + }, + "copyright": { + "type": "string", + "description": "The copyright text that is displayed in the footer. Set to null to reset the override.", + "nullable": true, + "maxLength": 300 } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Collection" - } + } + }, + "themes": { + "type": "object", + "properties": { + "default": { + "description": "The theme mode default value. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/CustomizationThemeMode" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + }, + "toggeable": { + "description": "Should the reader be able to switch between dark and light mode. Set to null to reset the override.", + "type": "boolean", + "nullable": true } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/custom-fields": { - "get": { - "operationId": "listOrganizationCustomFields", - "summary": "Get the custom fields for spaces in an organization", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "pdf": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, PDF export is enabled for the published site. Set to null to reset the override.", + "nullable": true + } + }, + "required": ["enabled"] }, - { - "$ref": "#/components/parameters/listPage" + "feedback": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, feedback gathering is enabled. Set to null to reset the override.", + "nullable": true + } + }, + "required": ["enabled"] }, - { - "$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/CustomField" - } - } - } - } - ] - } + "aiSearch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, AI search is enabled. Set to null to reset the override.", + "nullable": true + } + }, + "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. Set to null to reset the override.", + "nullable": true + } + }, + "required": ["showEditLink"] + }, + "pagination": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the pagination navigation should be displayed on pages. Set to null to reset the override.", + "nullable": true + } + }, + "required": ["enabled"] + }, + "trademark": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the GitBook trademark (\"Powered by GitBook\") should be visible. Set to null to reset the override.", + "nullable": true + } + }, + "required": ["enabled"] + }, + "privacyPolicy": { + "type": "object", + "properties": { + "url": { + "description": "The custom link to the privacy policy. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/URL" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] } } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "socialPreview": { + "type": "object", + "properties": { + "url": { + "description": "The URL for the social preview image. Set to null to reset the override.", + "oneOf": [ + { + "$ref": "#/components/schemas/URL" + }, + { + "type": "string", + "nullable": true, + "enum": [null] + } + ] + } + } } } }, - "post": { - "operationId": "createOrganizationCustomField", - "summary": "Create a new custom field in an orgamization", - "tags": ["organizations"], - "security": [ - { - "user": [] + "SiteSpacePointer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["site-space"] + }, + "siteSpace": { + "type": "string", + "description": "Unique identifier for the site space" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["type", "siteSpace"] + }, + "SiteSpaceMovePosition": { + "type": "object", + "description": "Position at which to move the site space to.", + "properties": { + "before": { + "$ref": "#/components/schemas/SiteSpacePointer" + }, + "after": { + "$ref": "#/components/schemas/SiteSpacePointer" } - ], - "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"] + } + }, + "OrganizationPointer": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["organization"] + }, + "organization": { + "type": "string", + "description": "Unique identifier for the organization" + } + }, + "required": ["type", "organization"] + }, + "UserSitePermission": { + "type": "object", + "description": "Permission of a user in a site.", + "properties": { + "permission": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "user": { + "$ref": "#/components/schemas/User" + }, + "origin": { + "description": "The content or organization that enforced this permission level.", + "oneOf": [ + { + "$ref": "#/components/schemas/SpacePointer" + }, + { + "$ref": "#/components/schemas/OrganizationPointer" } - } + ] } }, - "responses": { - "201": { - "description": "Custom field created", - "headers": { - "Location": { - "description": "API URL for the newly created custom field", - "schema": { + "required": ["permission", "user", "origin"] + }, + "SiteTrackPageView": { + "type": "object", + "properties": { + "pageId": { + "type": "string", + "description": "Unique identifier of the page." + }, + "spaceId": { + "type": "string", + "description": "Unique identifier of the space." + }, + "visitor": { + "type": "object", + "description": "Analytics info on the GitBook's content visitor.", + "properties": { + "anonymousId": { + "type": "string", + "description": "GitBook's unique identifier of the visitor." + }, + "cookies": { + "type": "object", + "description": "The visitors cookies.", + "additionalProperties": { "type": "string" } + }, + "ip": { + "type": "string", + "description": "IP address of the visitor.\nIf undefined, it'll default to the IP executing the request.\n" + }, + "userAgent": { + "type": "string", + "description": "User-agent of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent\n" + }, + "language": { + "type": "string", + "description": "Language of the visitor.\nhttps://developer.mozilla.org/en-US/docs/Web/API/Navigator/language\n" } }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomField" - } - } - } + "required": ["anonymousId", "cookies", "userAgent"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/custom-fields/{fieldName}": { - "get": { - "operationId": "getOrganizationCustomFieldByName", - "summary": "Get a custom field by its name", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "url": { + "type": "string", + "description": "The GitBook content's URL visited (including URL params)." }, - { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { - "type": "string" - } + "referrer": { + "type": "string", + "description": "The URL of referrer that linked to the page." } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomField" - } - } - } + }, + "required": ["visitor", "url", "referrer", "spaceId"] + }, + "SiteAdsStats": { + "type": "object", + "required": ["impressions", "clicks", "revenue", "account"], + "properties": { + "impressions": { + "type": "number" }, - "404": { - "description": "No matching custom field found", - "$ref": "#/components/responses/NotFoundError" + "clicks": { + "type": "number" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "revenue": { + "type": "string" + }, + "account": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Email address on the Ads platform." + }, + "url": { + "type": "string", + "description": "URL to configure payout." + } + }, + "required": ["email", "url"] } } }, - "patch": { - "operationId": "updateOrganizationCustomField", - "summary": "Update a custom field in an organization", - "tags": ["organizations"], - "security": [ + "CustomHostnameDnsStatus": { + "type": "string", + "enum": [ + "dns_passed", + "dns_wrong_cname", + "dns_no_cname", + "dns_cloudflare_proxied", + "dns_wrong_caa" + ] + }, + "CustomHostnameSslStatus": { + "type": "string", + "enum": ["live", "ssl_unknown", "ssl_pending", "ssl_failed", "ssl_retry_expired"] + }, + "CustomHostnameErrorStatus": { + "type": "string", + "enum": ["invalid_domain", "internal_error"] + }, + "CustomHostnameStatus": { + "type": "string", + "oneOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/CustomHostnameDnsStatus" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/CustomHostnameSslStatus" }, { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { - "type": "string" - } + "$ref": "#/components/schemas/CustomHostnameErrorStatus" } - ], - "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" - } - } + ] + }, + "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" + }, + { + "$ref": "#/components/schemas/SitePointer" } - } + ] + }, + "isActive": { + "type": "boolean" + }, + "status": { + "$ref": "#/components/schemas/CustomHostnameStatus" + }, + "urls": { + "type": "object", + "description": "URLs associated with the object", + "properties": { + "location": { + "type": "string", + "description": "URL of the custom hostname in the API", + "format": "uri" + } + }, + "required": ["location"] } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomField" - } + "required": ["object", "hostname", "target", "isActive", "urls"] + }, + "UnsplashImage": { + "type": "object", + "required": ["kind", "id", "description", "downloadLocation", "urls", "author"], + "properties": { + "kind": { + "type": "string", + "enum": ["unsplash_image"] + }, + "id": { + "type": "string" + }, + "description": { + "type": "string" + }, + "downloadLocation": { + "type": "string" + }, + "urls": { + "type": "object", + "properties": { + "full": { + "type": "string" + }, + "small": { + "type": "string" } - } + }, + "required": ["full", "small"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "author": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": ["name", "url"] } } }, - "delete": { - "operationId": "deleteOrganizationCustomField", - "summary": "Delete a custom field in an organization", - "tags": ["organizations"], - "security": [ - { - "user": [] + "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" + } } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["contents"] + }, + "PurgeCDNCacheContextType": { + "type": "string", + "description": "The type of purge, e.g by tags or hosts", + "enum": ["tags", "hosts"] + }, + "PurgeCDNCacheContext": { + "type": "object", + "description": "The context to send when purging the CDN Cache", + "properties": { + "type": { + "$ref": "#/components/schemas/PurgeCDNCacheContextType" }, - { - "name": "fieldName", - "in": "path", - "required": true, - "description": "The name of the custom field", - "schema": { + "values": { + "type": "array", + "description": "The list of tags or hosts to purge", + "items": { "type": "string" } } - ], - "responses": { - "204": { - "description": "Custom field has been deleted" + }, + "required": ["type", "values"] + }, + "CloudflareHostnameStatus": { + "type": "string", + "description": "The Cloudflare Hostname status", + "enum": ["pending", "active", "blocked", "moved", "deleted"] + }, + "CloudflareHostnameTLSStatus": { + "type": "string", + "description": "The Cloudflare Hostname TLS status", + "enum": [ + "initializing", + "pending_validation", + "pending_issuance", + "pending_deployment", + "active", + "pending_deletion", + "pending_cleanup", + "deleted" + ] + }, + "CloudflareHostnameTLSValidationMethod": { + "type": "string", + "description": "The Cloudflare Hostname TLS validation method", + "enum": ["http", "txt", "email"] + }, + "CloudflareHostnameTLSCertificate": { + "type": "object", + "description": "The Cloudflare Hostname TLS certificate", + "properties": { + "issuer": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "expiresOn": { + "type": "string" + }, + "issuedOn": { + "type": "string" } } - } - }, - "/orgs/{organizationId}/integrations": { - "get": { - "operationId": "listOrganizationIntegrations", - "summary": "List integrations owned by an organization", - "tags": ["spaces"], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - }, - { - "$ref": "#/components/parameters/listPage" + }, + "CloudflareHostnameTLSValidationError": { + "type": "object", + "description": "The Cloudflare Hostname TLS validation error", + "properties": { + "message": { + "type": "string" + } + }, + "required": ["message"] + }, + "CloudflareHostnameTLSInfo": { + "type": "object", + "description": "The Cloudflare Hostname TLS information", + "properties": { + "status": { + "$ref": "#/components/schemas/CloudflareHostnameTLSStatus" }, - { - "$ref": "#/components/parameters/listLimit" + "method": { + "$ref": "#/components/schemas/CloudflareHostnameTLSValidationMethod" }, - { - "$ref": "#/components/schemas/IntegrationSearchQuery" - } - ], - "responses": { - "200": { - "description": "List of integrations.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Integration" - } - } - } - } - ] - } - } + "certificateAuthority": { + "type": "string" + }, + "certificates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CloudflareHostnameTLSCertificate" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "validationErrors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CloudflareHostnameTLSValidationError" + } } - } - } - }, - "/orgs/{organizationId}/integrations/{integrationName}/installation_status": { - "get": { - "operationId": "getOrganizationIntegrationStatus", - "summary": "Get the status of an integration installation in an organization", - "tags": ["integrations"], - "security": [ - { - "user": [] + }, + "required": ["status", "method", "certificates", "validationErrors"] + }, + "CustomDomainInfo": { + "type": "object", + "description": "Cloudflare Custom Domain's information", + "properties": { + "hostname": { + "type": "string" + }, + "status": { + "$ref": "#/components/schemas/CloudflareHostnameStatus" + }, + "createdAt": { + "type": "string" + }, + "ssl": { + "$ref": "#/components/schemas/CloudflareHostnameTLSInfo" + }, + "verificationErrors": { + "type": "array", + "items": { + "type": "string" + } } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["hostname", "status", "createdAt", "verificationErrors"] + }, + "StaffUserInfo": { + "type": "object", + "description": "The GitBook Staff User info.", + "properties": { + "id": { + "type": "string" }, - { - "$ref": "#/components/parameters/integrationName" + "searchKey": { + "type": "string" } - ], - "responses": { - "200": { - "description": "Integration installation status", - "content": { - "application/json": { - "schema": { - "properties": { - "status": { - "$ref": "#/components/schemas/IntegrationInstallationStatus" - } - }, - "required": ["status"] - } - } - } + }, + "required": ["id", "searchKey"] + }, + "FirebaseUserInfo": { + "type": "object", + "description": "The User Firebase Auth Info.", + "properties": { + "uid": { + "type": "string" }, - "404": { - "$ref": "#/components/responses/NotFoundError" + "displayName": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/installations": { - "get": { - "operationId": "listOrganizationInstallations", - "summary": "List installations of integrations in an organization.", - "tags": ["spaces"], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "email": { + "type": "string" }, - { - "$ref": "#/components/parameters/listPage" + "phoneNumber": { + "type": "string" }, - { - "$ref": "#/components/parameters/listLimit" + "photoUrl": { + "type": "string" }, - { - "$ref": "#/components/schemas/IntegrationSearchQuery" + "providerId": { + "type": "string" } - ], - "responses": { - "200": { - "description": "List of integrations with the associated installations.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "installation": { - "$ref": "#/components/schemas/IntegrationInstallation" - }, - "integration": { - "$ref": "#/components/schemas/Integration" - } - }, - "required": ["integration", "installation"] - } - } - } - } - ] - } - } + }, + "required": ["uid"] + }, + "UserBackOfficeInfo": { + "type": "object", + "description": "The GitBook User info shown in the BackOffice.", + "properties": { + "id": { + "type": "string" + }, + "authProviders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FirebaseUserInfo" } }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/experiments": { - "get": { - "operationId": "listOrgExperimentalFeatures", - "summary": "List experiemental features for the given organization.", - "tags": ["organizations"], - "security": [ - { - "user": [] + "createdAt": { + "type": "string" + }, + "lastSignInAt": { + "type": "string" + }, + "disabled": { + "type": "boolean" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["id", "authProviders", "createdAt", "lastSignInAt", "disabled"] + }, + "BlockContext": { + "type": "object", + "description": "The context to send when blocking/unblocking", + "properties": { + "block": { + "type": "boolean" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationExperimentalFeature" - } - } - } - } + }, + "required": ["block"] + }, + "UserImpersonationInfo": { + "type": "object", + "description": "The GitBook User impersonation info.", + "properties": { + "authURL": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "impersonatorId": { + "type": "string" } - } + }, + "required": ["authURL", "impersonatorId"] }, - "post": { - "operationId": "updateOrgExperimentalFeatures", - "summary": "Toggle on or off experimental features.", - "tags": ["organizations"], - "security": [ + "UserImpersonation": { + "type": "object", + "description": "The info returned when impersonating a GitBook User.", + "allOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/UserBackOfficeInfo" + }, { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": { - "type": "boolean" - } + "type": "object", + "properties": { + "impersonation": { + "$ref": "#/components/schemas/UserImpersonationInfo" } - } + }, + "required": ["impersonation"] + } + ] + }, + "UserOrganizationsTeamsPermissions": { + "type": "object", + "description": "The teams permissions of a user", + "properties": { + "role": { + "$ref": "#/components/schemas/TeamMemberRole" } }, - "responses": { - "204": { - "description": "OK" + "required": ["role"] + }, + "UserOrganizationsPermissions": { + "type": "object", + "description": "The organizations permissions of a user", + "properties": { + "role": { + "$ref": "#/components/schemas/MemberRoleOrGuest" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "teams": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/UserOrganizationsTeamsPermissions" + }, + "required": ["role"] + }, + "disabled": { + "type": "boolean" } - } - } - }, - "/orgs/{organizationId}/schemas": { - "get": { - "operationId": "listEntitySchemas", - "summary": "List the entity schemas in an organization.", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["role", "teams"] + }, + "UserCollectionsPermissions": { + "type": "object", + "description": "The collections permissions of a user", + "properties": { + "organization": { + "type": "string" + }, + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "collection": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["organization", "level"] + }, + "UserSpacesPermissions": { + "type": "object", + "description": "The spaces permissions of a user", + "properties": { + "organization": { + "type": "string" + }, + "level": { + "$ref": "#/components/schemas/MemberRoleOrGuest" + }, + "collection": { + "type": "string" + } + }, + "required": ["organization", "level"] + }, + "_index": { + "type": "object", + "description": "All the permissions of a user", + "properties": { + "updatedAt": { + "$ref": "#/components/schemas/Timestamp" + }, + "searchKey": { + "type": "string" + }, + "organizations": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/UserOrganizationsPermissions" + } + }, + "collections": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/UserCollectionsPermissions" + } }, + "spaces": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/UserSpacesPermissions" + } + } + }, + "required": ["updatedAt", "searchKey", "organizations", "collections", "spaces"] + }, + "SpaceBlockReason": { + "type": "string", + "description": "Reason for a space to be blocked", + "enum": [ + "DMCA", + "THREAT_TYPE_UNSPECIFIED", + "MALWARE", + "SOCIAL_ENGINEERING", + "UNWANTED_SOFTWARE" + ] + }, + "BackOfficeSite": { + "allOf": [ { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/Site" }, { - "$ref": "#/components/parameters/listLimit" + "type": "object", + "properties": { + "organization": { + "type": "string", + "description": "ID of the organization owning this site" + } + }, + "required": ["organization"] } - ], - "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/EntitySchema" - } - } - } - } - ] - } + ] + }, + "PublishedSiteContentLookup": { + "oneOf": [ + { + "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"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/schemas/{entityType}": { - "get": { - "operationId": "getEntitySchema", - "summary": "Get an entity schema by its type.", - "tags": ["organizations"], - "security": [ { - "user": [] + "type": "object", + "title": "Content", + "properties": { + "site": { + "type": "string", + "description": "ID of the site matching." + }, + "siteSpace": { + "type": "string", + "description": "ID of the site-space matching." + }, + "space": { + "type": "string", + "description": "ID of the space matching." + }, + "changeRequest": { + "type": "string", + "description": "Identifier of the change request being previewed in this URL." + }, + "revision": { + "type": "string", + "description": "Identifier of the revision being previewed in this URL." + }, + "pathname": { + "type": "string", + "description": "Path of the content relative to the 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." + }, + "organization": { + "type": "string", + "description": "ID of the organization." + }, + "shareKey": { + "type": "string", + "description": "Share link key of the site in case the site was published with share-links." + } + }, + "required": [ + "site", + "siteSpace", + "space", + "pathname", + "basePath", + "apiToken", + "organization" + ] + } + ] + }, + "UpdateContentPublishingAuth": { + "type": "object", + "properties": { + "fallbackURL": { + "type": "string", + "format": "uri", + "description": "A fallback URL that will be used if authentication fails." } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + } + }, + "TriggerContentIndexingContext": { + "type": "object", + "description": "The context to send when triggering a content indexing.", + "properties": { + "spaceId": { + "type": "string", + "description": "The unique identifier of the Space to index." }, - { - "$ref": "#/components/parameters/entityType" + "force": { + "type": "boolean", + "description": "Whether to force a complete re-indexing of the Space." } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EntitySchema" - } - } - } + }, + "required": ["spaceId", "force"] + }, + "ContentPublishingAuth": { + "type": "object", + "properties": { + "object": { + "type": "string", + "description": "Type of Object, always equals to \"publishing-auth\"", + "enum": ["publishing-auth"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "id": { + "type": "string", + "description": "Unique identifier for the content." + }, + "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", "id", "privateKey"] }, - "put": { - "operationId": "setEntitySchema", - "summary": "Create or update an entity schema.", - "tags": ["organizations"], - "security": [ + "DocumentBlock": { + "oneOf": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockParagraph" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockHeading" }, { - "$ref": "#/components/parameters/entityType" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EntityRawSchema" - } - } - } - }, - "responses": { - "204": { - "description": "OK" + "$ref": "#/components/schemas/DocumentBlockListOrdered" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "delete": { - "operationId": "deleteEntitySchema", - "summary": "Delete an entity schema.", - "tags": ["organizations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockListUnordered" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockListTasks" }, { - "$ref": "#/components/parameters/entityType" - } - ], - "responses": { - "204": { - "description": "OK" + "$ref": "#/components/schemas/DocumentBlockListItem" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/schemas/{entityType}/entities": { - "get": { - "operationId": "listSchemaEntities", - "summary": "List entities in an organization for a given type.", - "tags": ["organizations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockDivider" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockQuote" }, { - "$ref": "#/components/parameters/entityType" + "$ref": "#/components/schemas/DocumentBlockHint" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/DocumentBlockImages" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/DocumentBlockImage" }, { - "name": "query", - "in": "query", - "description": "Query to filter entities with, ex: a == 'something' && b >= 10", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Entity" - } - } - } - } - ] - } - } - } + "$ref": "#/components/schemas/DocumentBlockFile" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "put": { - "operationId": "upsertSchemaEntities", - "summary": "Update/Create/Delete entities in a schema.", - "tags": ["organizations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockDrawing" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockEmbed" }, { - "$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" - } - } - ] - }, - "entities": { - "type": "array", - "description": "Array of entities to create/update.", - "items": { - "$ref": "#/components/schemas/UpsertEntity" - } - } - } - } - } - } - }, - "responses": { - "204": { - "description": "OK" + "$ref": "#/components/schemas/DocumentBlockCode" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/schemas/{entityType}/entities/{entityId}": { - "get": { - "operationId": "getEntity", - "summary": "Get an entity using its ID.", - "tags": ["organizations"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockCodeLine" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockMath" }, { - "$ref": "#/components/parameters/entityType" + "$ref": "#/components/schemas/DocumentBlockExpandable" }, { - "$ref": "#/components/parameters/entityId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Entity" - } - } - } + "$ref": "#/components/schemas/DocumentBlockTabs" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/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": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/DocumentBlockTabsItem" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/DocumentBlockTable" }, { - "$ref": "#/components/parameters/pageFormat" + "$ref": "#/components/schemas/DocumentBlockSwagger" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/DocumentBlockContentRef" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/DocumentBlockIntegration" }, { - "name": "context", - "in": "query", - "description": "The context in which the item was captured", - "schema": { - "type": "string", - "enum": ["walkthrough", "thread"] - } + "$ref": "#/components/schemas/DocumentBlockSyncedBlock" } - ], - "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/Capture" - } - } - } - } - ] - } - } - } + ] + }, + "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" + ] + }, + "OrganizationTransferResponse": { + "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." }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "newSourceHostname": { + "type": "string", + "description": "The new hostname if the source organization needed to change hostname." } } }, - "post": { - "operationId": "startCapture", - "summary": "Start a capture", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$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": { - "201": { - "description": "Capture started", - "headers": { - "Location": { - "description": "API URL for the newly created capture", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Capture" - } - } - } + "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 }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/captures/{captureId}": { - "get": { - "operationId": "getCapture", - "deprecated": true, - "summary": "Get a capture by its ID. Deprecated, use getSnippet instead.", - "tags": ["organizations"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "integration": { + "$ref": "#/components/schemas/Integration" }, - { - "$ref": "#/components/parameters/captureId" + "installation": { + "$ref": "#/components/schemas/IntegrationInstallation" }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Capture" - } + "spaceInstallation": { + "$ref": "#/components/schemas/IntegrationSpaceInstallation" + }, + "siteInstallation": { + "$ref": "#/components/schemas/IntegrationSiteInstallation" + }, + "secrets": { + "$ref": "#/components/schemas/IntegrationSecrets" + }, + "signingSecret": { + "type": "string", + "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the integration.", + "deprecated": true + }, + "signingSecrets": { + "type": "object", + "properties": { + "integration": { + "type": "string", + "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the integration." + }, + "installation": { + "type": "string", + "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the installation." + }, + "spaceInstallation": { + "type": "string", + "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the space installation." + }, + "siteInstallation": { + "type": "string", + "description": "Secret that can be used to verify the authenticity of incoming HTTP requests to the site installation." } - } + }, + "required": ["integration"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/captures/{captureId}/events": { - "post": { - "operationId": "addEventsToCapture", - "summary": "Add events to a running capture", - "tags": ["organizations"], - "security": [ - { - "user": [] + "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"] } - ], - "parameters": [ + }, + "required": ["apiEndpoint", "apiTokens", "integration", "signingSecrets", "secrets"] + }, + "BillingTrialStatus": { + "type": "string", + "enum": ["notapplicable", "none", "active", "ended", "expired"] + }, + "APIIntegrationScope": { + "type": "string", + "enum": [ + "integration:read", + "integration:update", + "integration:installation:read", + "integration:installation:update" + ] + }, + "APIScope": { + "anyOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/IntegrationScope" }, { - "$ref": "#/components/parameters/captureId" + "$ref": "#/components/schemas/APIIntegrationScope" } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "events": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CaptureEvent" - } - } - }, - "required": ["events"] - } - } + ] + }, + "ContentAPIBaseToken": { + "type": "object", + "description": "Common properties for all Content API tokens.", + "properties": { + "organization": { + "type": "string", + "description": "ID of the organization that owns the content. A content token is always scoped to spaces from the same organization." + }, + "spaces": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of spaces that the token is allowed to access." + }, + "rateLimitMultiplier": { + "type": "number", + "description": "Multiplier for the rate limit applied to the token." } }, - "responses": { - "204": { - "description": "Events added" + "required": ["organization", "spaces"] + }, + "SpaceAPIToken": { + "allOf": [ + { + "$ref": "#/components/schemas/ContentAPIBaseToken" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/captures/{captureId}/stop": { - "post": { - "operationId": "stopCapture", - "summary": "Stop a capture", - "tags": ["organizations"], - "security": [ { - "user": [] + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["space"] + }, + "space": { + "type": "string", + "description": "ID of the space that the token is allowed to access." + } + }, + "required": ["kind", "space"] } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - }, + ] + }, + "CollectionAPIToken": { + "allOf": [ { - "$ref": "#/components/parameters/captureId" + "$ref": "#/components/schemas/ContentAPIBaseToken" }, { - "$ref": "#/components/parameters/pageFormat" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["collection"] + }, + "collection": { + "type": "string", + "description": "ID of the collection that the token is allowed to access." } - } + }, + "required": ["kind", "collection"] } - }, - "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"] - } - } - } + ] + }, + "SiteAPIToken": { + "allOf": [ + { + "$ref": "#/components/schemas/ContentAPIBaseToken" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/snippets": { - "get": { - "operationId": "listSnippets", - "summary": "Lists snippets.", - "description": "List snippets in an organization, newest first.\n", - "tags": ["organizations"], - "security": [ { - "user": [] + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["site"] + }, + "site": { + "type": "string", + "description": "ID of the site that the token is allowed to access." + }, + "siteSpace": { + "type": "string", + "description": "ID of the site-space to be used when using this token for rendering published content." + }, + "space": { + "type": "string", + "description": "ID of the space to be used when using this token for rendering published content." + } + }, + "required": ["kind", "site", "siteSpace", "space"] } - ], - "parameters": [ + ] + }, + "ContentAPITokenPayload": { + "description": "Content properties stored in a Content API token.", + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/SpaceAPIToken" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/CollectionAPIToken" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/SiteAPIToken" + } + ] + }, + "SpaceInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space"] }, - { - "name": "source", - "in": "query", - "description": "If specified, only snippets from the specified source will be returned.", - "schema": { - "type": "string" - } + "space": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Snippet" - } - } - } - } - ] - } - } - } + }, + "required": ["channel", "space"] + }, + "SpaceGitInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-git-info"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "space": { + "type": "string" } - } + }, + "required": ["channel", "space"] }, - "post": { - "operationId": "createSnippet", - "summary": "Create a new snippet", - "tags": ["organizations"], - "security": [ - { - "user": [] + "SpacePublishingAuthChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-publishing-auth"] + }, + "space": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "space"] + }, + "SpacePublishingCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-publishing-customization"] + }, + "space": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "SpaceCustomFieldsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-customfields"] + }, + "space": { + "type": "string" } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object" - } - } + }, + "required": ["channel", "space"] + }, + "SpaceBrokenLinksChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-broken-links"] + }, + "space": { + "type": "string" } }, - "responses": { - "201": { - "description": "Snippet created", - "headers": { - "Location": { - "description": "API URL for the newly created snippet", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Snippet" - } - } - } + "required": ["channel", "space"] + }, + "BackofficeUserInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["backoffice-user-info"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "user": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/snippets/{snippetId}": { - "get": { - "operationId": "getSnippet", - "summary": "Get a snippet by its ID", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["channel", "user"] + }, + "SpaceIntegrationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-integrations"] + }, + "space": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "space"] + }, + "OrganizationCustomFieldsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-customfields"] }, - { - "$ref": "#/components/parameters/snippetId" + "organization": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Snippet" - } - } - } + }, + "required": ["channel", "organization"] + }, + "UserAPITokensChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-api-tokens"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "user": { + "type": "string" } - } + }, + "required": ["channel", "user"] }, - "delete": { - "operationId": "deleteSnippet", - "summary": "Delete a snippet by its ID.", - "tags": ["organizations"], - "security": [ - { - "user": [] + "UserOrganizationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-organizations"] + }, + "user": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "user"] + }, + "UserProfileChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["user-profile"] }, - { - "$ref": "#/components/parameters/snippetId" + "user": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK" + }, + "required": ["channel", "user"] + }, + "ChangeRequestChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" } - } + }, + "required": ["channel", "space", "changeRequest"] }, - "put": { - "operationId": "updateSnippet", - "summary": "Update an existing snippet.", - "tags": ["organizations"], - "security": [ - { - "user": [] + "ChangeRequestsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-requests"] + }, + "space": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "space"] + }, + "ChangeRequestReviewsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request-reviews"] }, - { - "$ref": "#/components/parameters/snippetId" + "space": { + "type": "string" }, - { - "$ref": "#/components/parameters/ifUnmodifiedSince" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpdateSnippetSchema" - } - } + "changeRequest": { + "type": "string" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Snippet" - } - } - } + "required": ["channel", "space", "changeRequest"] + }, + "ChangeRequestBrokenLinksChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-change-request-broken-links"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/snippets/{snippetId}/move": { - "post": { - "operationId": "moveSnippet", - "summary": "Move a snippet into a destination. The snippet will be archived in the process.", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["channel", "space", "changeRequest"] + }, + "CollectionChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["collection"] + }, + "collection": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "collection"] + }, + "CollectionPublishingCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["collection-publishing-customization"] }, - { - "$ref": "#/components/parameters/snippetId" + "collection": { + "type": "string" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["target"], - "properties": { - "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"] - } - } - } - } + }, + "required": ["channel", "collection"] + }, + "OrganizationInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization"] + }, + "organization": { + "type": "string" } }, - "responses": { - "200": { - "description": "The snippet was successfully moved.", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["page"], - "properties": { - "page": { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - "changeRequest": { - "$ref": "#/components/schemas/ChangeRequest" - } - } - } - } - } + "required": ["channel", "organization"] + }, + "OrganizationMembersChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-members"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "organization": { + "type": "string" } - } + }, + "required": ["channel", "organization"] }, - "get": { - "operationId": "getSnippetSuggestedLocations", - "summary": "Return possible snippet locations in an organization based on the current user.", - "tags": ["organizations"], - "security": [ - { - "user": [] + "OrganizationMemberChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-member"] + }, + "organization": { + "type": "string" + }, + "user": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "organization", "user"] + }, + "OrganizationSAMLChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-saml"] }, - { - "$ref": "#/components/parameters/snippetId" + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationTeamsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-teams"] }, - { - "$ref": "#/components/parameters/listPage" + "organization": { + "type": "string" + } + }, + "required": ["channel", "organization"] + }, + "OrganizationTeamChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team"] }, - { - "$ref": "#/components/parameters/listLimit" + "organization": { + "type": "string" }, - { - "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" - } + "team": { + "type": "string" + } + }, + "required": ["channel", "organization", "team"] + }, + "OrganizationTeamMembersChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team-members"] }, - { - "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" - } + "organization": { + "type": "string" }, - { - "name": "search", - "in": "query", - "description": "If specified, only locations matching the search query will be returned.", - "schema": { - "type": "string" - } + "team": { + "type": "string" } - ], - "responses": { - "200": { - "description": "A paginated list of suggested snippet locations.", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "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" - } - ] - } - } - } - } - } - } - ] - } - } - } + }, + "required": ["channel", "organization", "team"] + }, + "OrganizationTeamMemberChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-team-member"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "organization": { + "type": "string" + }, + "team": { + "type": "string" + }, + "member": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/synced-blocks": { - "post": { - "operationId": "createSyncedBlock", - "summary": "Create a new synced block", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "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" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "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" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["document"], - "properties": { - "title": { - "type": "string", - "description": "Title of synced block" - }, - "document": { - "$ref": "#/components/schemas/Document" - } - } - } - } + }, + "required": ["channel", "organization"] + }, + "OrganizationCapturesChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-captures"] + }, + "organization": { + "type": "string" } }, - "responses": { - "201": { - "description": "Synced block created", - "headers": { - "Location": { - "description": "API URL for the newly created synced block", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SyncedBlock" - } - } - } + "required": ["channel", "organization"] + }, + "OrganizationIntegrationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-integrations"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "organization": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/synced-blocks/{syncedBlockId}": { - "get": { - "operationId": "getSyncedBlock", - "summary": "Get a synced block by its ID", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["channel", "organization"] + }, + "OrganizationInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-installations"] + }, + "organization": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "organization"] + }, + "OrganizationSitesChannel": { + "type": "object", + "description": "Subscription channel for changes in sites in an organization.", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-sites"] }, - { - "$ref": "#/components/parameters/syncedBlockId" + "organization": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SyncedBlock" - } - } - } + }, + "required": ["channel", "organization"] + }, + "OrganizationExperimentalFeaturesChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-experimental-features"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "organization": { + "type": "string" } - } + }, + "required": ["channel", "organization"] }, - "put": { - "operationId": "updateSyncedBlock", - "summary": "Update an existing synced block.", - "tags": ["organizations"], - "security": [ - { - "user": [] + "OrganizationSyncedBlocksChannel": { + "type": "object", + "description": "Subscription channel for changes in synced blocks in an organization.", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-synced-blocks"] + }, + "organization": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "organization"] + }, + "OrganizationSyncedBlockChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["organization-synced-block"] }, - { - "$ref": "#/components/parameters/syncedBlockId" + "organization": { + "type": "string" + }, + "syncedBlock": { + "type": "string" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "A new title for the Synced Block." - } - } - } - } + }, + "required": ["channel", "organization", "syncedBlock"] + }, + "CommentsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comments"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + } + }, + "required": ["channel", "space"] + }, + "CommentInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment"] + }, + "space": { + "type": "string" + }, + "changeRequest": { + "type": "string" + }, + "comment": { + "type": "string" } }, - "responses": { - "200": { - "description": "OK" + "required": ["channel", "space", "comment"] + }, + "CommentReplyInfoChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment-reply"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/ask": { - "post": { - "operationId": "askInOrganization", - "summary": "Ask a question.", - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + "space": { + "type": "string" }, - { - "$ref": "#/components/parameters/pageFormat" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchAIQuery" - } - } + "changeRequest": { + "type": "string" + }, + "comment": { + "type": "string" + }, + "commentReply": { + "type": "string" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "answer": { - "$ref": "#/components/schemas/SearchAIAnswer" - } - } - } - } - } + "required": ["channel", "space", "comment", "commentReply"] + }, + "CommentRepliesChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["space-comment-replies"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/ask/questions": { - "get": { - "operationId": "getRecommendedQuestionsInOrganization", - "summary": "Get a list of questions recommended to be asked in an organization.", - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" - } - ], - "security": [ - { - "user": [] - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestions" - } - } - } + "space": { + "type": "string" }, - "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/organizationId" - } - ], - "security": [ - { - "user": [] - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "text/event-stream": { - "schema": { - "$ref": "#/components/schemas/SearchAIRecommendedQuestionStream" - } - } - } + "changeRequest": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "comment": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/ask/stream": { - "get": { - "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": [] + }, + "required": ["channel", "space", "comment"] + }, + "IntegrationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration"] + }, + "integration": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "integration"] + }, + "IntegrationInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-installation"] }, - { - "name": "query", - "in": "query", - "required": true, - "schema": { - "type": "string" - } + "integration": { + "type": "string" }, - { - "$ref": "#/components/parameters/pageFormat" + "installation": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "text/event-stream": { - "schema": { - "$ref": "#/components/schemas/SearchAIAnswerStream" - } - } - } + }, + "required": ["channel", "integration", "installation"] + }, + "IntegrationSpaceInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-space-installation"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "integration": { + "type": "string" + }, + "installation": { + "type": "string" + }, + "space": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/insights/audit-relations": { - "get": { - "operationId": "listContentAuditRelations", - "summary": "List the content relations for in a given organization.", - "tags": ["ai", "spaces"], - "security": [ - { - "user": [] + }, + "required": ["channel", "integration", "installation", "space"] + }, + "IntegrationSpaceInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-space-installations"] + }, + "integration": { + "type": "string" + }, + "installation": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "integration", "installation"] + }, + "IntegrationSiteInstallationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-site-installation"] }, - { - "$ref": "#/components/parameters/listPage" + "integration": { + "type": "string" }, - { - "$ref": "#/components/parameters/listLimit" + "installation": { + "type": "string" }, - { - "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"] - } - ] - } + "site": { + "type": "string" + } + }, + "required": ["channel", "integration", "installation", "site"] + }, + "IntegrationSiteInstallationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["integration-site-installations"] }, - { - "name": "space", - "in": "query", - "required": false, - "description": "Space concerned by the relation", - "schema": { - "type": "string" - } + "integration": { + "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"] - } - ] - } + "installation": { + "type": "string" } - ], - "responses": { - "200": { - "description": "Content audit relations", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentAuditRelation" - } - } - } - } - ] - } - } - } + }, + "required": ["channel", "integration", "installation"] + }, + "SiteChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "site": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/insights/audit-relations/{relationId}": { - "get": { - "operationId": "getContentAuditRelationById", - "summary": "Get an audit relation by ID", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["channel", "site"] + }, + "SiteCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-customization"] + }, + "site": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "required": ["channel", "site"] + }, + "SiteIntegrationsChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-integrations"] }, - { - "$ref": "#/components/parameters/relationId" + "site": { + "type": "string" } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentAuditRelation" - } - } - } + }, + "required": ["channel", "site"] + }, + "SiteSpaceChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-space"] }, - "404": { - "description": "No matching content relation found for given ID", - "$ref": "#/components/responses/NotFoundError" + "site": { + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "siteSpace": { + "type": "string" } - } + }, + "required": ["channel", "site", "siteSpace"] }, - "patch": { - "operationId": "updateContentAuditRelationStatusById", - "summary": "Update an audit relation status", - "tags": ["organizations"], - "security": [ - { - "user": [] + "SiteSpaceCustomizationChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-space-customization"] + }, + "site": { + "type": "string" + }, + "siteSpace": { + "type": "string" } - ], - "parameters": [ - { - "$ref": "#/components/parameters/organizationId" + }, + "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"] }, - { - "$ref": "#/components/parameters/relationId" + "site": { + "type": "string" } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentAuditRelationStatusUpdate" - } - } + }, + "required": ["channel", "site"] + }, + "SitePublishingAuthChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-publishing-auth"] + }, + "site": { + "type": "string" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentAuditRelation" - } - } - } + "required": ["channel", "site"] + }, + "SiteShareLinksChannel": { + "type": "object", + "description": "Subscription channel for changes in share links in a site", + "properties": { + "channel": { + "type": "string", + "enum": ["site-share-links"] }, - "404": { - "description": "No matching content relation found for given ID", - "$ref": "#/components/responses/NotFoundError" + "site": { + "type": "string" + } + }, + "required": ["channel", "site"] + }, + "SiteShareLinkChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["site-share-link"] }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "site": { + "type": "string" + }, + "siteShareLink": { + "type": "string" } - } - } - }, - "/orgs/{organizationId}/insights/audit-sources/{sourceId}/content": { - "get": { - "operationId": "getContentAuditSourceContentById", - "summary": "Get the content of an audit source", - "tags": ["organizations"], - "security": [ - { - "user": [] + }, + "required": ["channel", "site", "siteShareLink"] + }, + "CustomHostnameChannel": { + "type": "object", + "properties": { + "channel": { + "type": "string", + "enum": ["custom-hostname"] + }, + "customHostname": { + "type": "string" } - ], - "parameters": [ + }, + "required": ["channel", "customHostname"] + }, + "SubscriptionChannel": { + "description": "Channel to subscribe to for API updates.", + "oneOf": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/SpaceInfoChannel" }, { - "name": "sourceId", - "in": "path", - "required": true, - "description": "The id of the content audit source", - "schema": { - "type": "string" - } + "$ref": "#/components/schemas/SpaceGitInfoChannel" }, { - "$ref": "#/components/parameters/pageFormat" - } - ], - "responses": { - "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" + "$ref": "#/components/schemas/SpacePublishingAuthChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/sites": { - "get": { - "operationId": "listSites", - "summary": "List all the sites created in an organization", - "tags": ["sites"], - "security": [ - { - "user": [] - } - ], - "parameters": [ { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/SpacePublishingCustomizationChannel" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/SpaceCustomFieldsChannel" }, { - "$ref": "#/components/parameters/listLimit" + "$ref": "#/components/schemas/SpaceBrokenLinksChannel" }, { - "name": "space", - "in": "query", - "description": "Identifier of the space to filter the sites by", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/List" - }, - { - "type": "object", - "required": ["items"], - "properties": { - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Site" - } - } - } - } - ] - } - } - } + "$ref": "#/components/schemas/BackofficeUserInfoChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "post": { - "operationId": "createSite", - "summary": "Create a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SpaceIntegrationsChannel" + }, { - "$ref": "#/components/parameters/organizationId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "$ref": "#/components/schemas/SiteTitle" - }, - "visibility": { - "$ref": "#/components/schemas/SiteVisibility" - }, - "spaces": { - "type": "array", - "description": "ID of spaces to be added to the site", - "items": { - "type": "string" - } - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Site created", - "headers": { - "Location": { - "description": "API URL for the newly created site", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Site" - } - } - } + "$ref": "#/components/schemas/OrganizationCustomFieldsChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/sites/{siteId}": { - "get": { - "operationId": "getSiteById", - "summary": "Get an organization site by its ID", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/UserAPITokensChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/UserOrganizationsChannel" }, { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Site" - } - } - } + "$ref": "#/components/schemas/UserProfileChannel" }, - "404": { - "description": "No matching site found", - "$ref": "#/components/responses/NotFoundError" + { + "$ref": "#/components/schemas/ChangeRequestChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "patch": { - "operationId": "updateSiteById", - "summary": "Update a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/ChangeRequestsChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/ChangeRequestReviewsChannel" }, { - "$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/Site" - } - } - } + "$ref": "#/components/schemas/ChangeRequestBrokenLinksChannel" + }, + { + "$ref": "#/components/schemas/CollectionChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "delete": { - "operationId": "deleteSiteById", - "summary": "Delete a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/CollectionPublishingCustomizationChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/OrganizationInfoChannel" }, { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "205": { - "description": "Site has been deleted" + "$ref": "#/components/schemas/OrganizationMembersChannel" }, - "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": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/OrganizationMemberChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/OrganizationSAMLChannel" }, { - "$ref": "#/components/parameters/siteId" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SitePublishingAuth" - } - } - } + "$ref": "#/components/schemas/OrganizationTeamsChannel" }, - "400": { - "$ref": "#/components/responses/BadRequestError" + { + "$ref": "#/components/schemas/OrganizationTeamChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/sites/{siteId}/spaces": { - "post": { - "operationId": "addSpaceToSite", - "summary": "Add a space to a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/OrganizationTeamMembersChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/OrganizationTeamMemberChannel" }, { - "$ref": "#/components/parameters/siteId" - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "spaceId": { - "type": "string", - "description": "ID of the space" - } - }, - "required": ["spaceId"] - } - } - } - }, - "responses": { - "201": { - "description": "Space added to the site", - "headers": { - "Location": { - "description": "API URL for the newly created site-space relationship", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SiteSpace" - } - } - } + "$ref": "#/components/schemas/OrganizationSpacesChannel" }, - "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/schemas/OrganizationCollectionsChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/OrganizationCapturesChannel" }, { - "$ref": "#/components/parameters/siteId" + "$ref": "#/components/schemas/OrganizationIntegrationsChannel" }, { - "$ref": "#/components/parameters/listPage" + "$ref": "#/components/schemas/OrganizationInstallationsChannel" }, { - "$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" - } - } - } - } - ] - } - } - } + "$ref": "#/components/schemas/OrganizationSitesChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/orgs/{organizationId}/sites/{siteId}/spaces/{siteSpaceId}": { - "patch": { - "operationId": "updateSiteSpaceById", - "summary": "Update a space on a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/OrganizationExperimentalFeaturesChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/OrganizationSyncedBlocksChannel" }, { - "$ref": "#/components/parameters/siteId" + "$ref": "#/components/schemas/OrganizationSyncedBlockChannel" }, { - "$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/SiteSpace" - } - } - } + "$ref": "#/components/schemas/CommentsChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "delete": { - "operationId": "deleteSiteSpaceById", - "summary": "Delete a space on a site in an organization", - "tags": ["sites"], - "security": [ { - "user": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/CommentInfoChannel" + }, { - "$ref": "#/components/parameters/organizationId" + "$ref": "#/components/schemas/CommentReplyInfoChannel" }, { - "$ref": "#/components/parameters/siteId" + "$ref": "#/components/schemas/CommentRepliesChannel" }, { - "$ref": "#/components/parameters/siteSpaceId" - } - ], - "responses": { - "205": { - "description": "Site space has been deleted" + "$ref": "#/components/schemas/IntegrationChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/custom-hostnames/{hostname}": { - "get": { - "operationId": "getCustomHostname", - "summary": "Get the details about a custom hostname.", - "tags": ["custom-hostnames"], - "security": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/IntegrationInstallationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSpaceInstallationChannel" + }, + { + "$ref": "#/components/schemas/IntegrationSpaceInstallationsChannel" + }, { - "$ref": "#/components/parameters/hostname" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomHostname" - } - } - } + "$ref": "#/components/schemas/IntegrationSiteInstallationChannel" }, - "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": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/IntegrationSiteInstallationsChannel" + }, { - "$ref": "#/components/parameters/hostname" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "target": { - "oneOf": [ - { - "$ref": "#/components/schemas/OrganizationPointer" - }, - { - "$ref": "#/components/schemas/SpacePointer" - }, - { - "$ref": "#/components/schemas/CollectionPointer" - } - ] - } - }, - "required": ["target"] - } - } - } - }, - "responses": { - "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" - } - } - } + "$ref": "#/components/schemas/SiteChannel" }, - "409": { - "description": "Custom hostname is already in use on the target", - "$ref": "#/components/responses/ConflictError" + { + "$ref": "#/components/schemas/SiteCustomizationChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - }, - "patch": { - "operationId": "dnsRevalidateCustomHostname", - "summary": "Revalidate a custom hostname's DNS records and status.", - "tags": ["custom-hostnames"], - "security": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SiteIntegrationsChannel" + }, { - "$ref": "#/components/parameters/hostname" - } - ], - "responses": { - "204": { - "description": "DNS validation has been retriggered" + "$ref": "#/components/schemas/SiteSpaceChannel" }, - "400": { - "description": "The current custom hostname is inactive and cannot be revalidated", - "$ref": "#/components/responses/ConflictError" + { + "$ref": "#/components/schemas/SiteSpaceCustomizationChannel" }, - "409": { - "description": "The current custom hostname status does not allow DNS revalidation", - "$ref": "#/components/responses/ConflictError" + { + "$ref": "#/components/schemas/SiteSpacesChannel" }, - "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": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SitePublishingAuthChannel" + }, { - "$ref": "#/components/parameters/hostname" - } - ], - "responses": { - "205": { - "description": "Custom hostname has been removed" + "$ref": "#/components/schemas/SiteShareLinksChannel" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" - } - } - } - }, - "/custom-hostnames/{hostname}/test": { - "post": { - "operationId": "testCustomHostname", - "summary": "Test if a custom hostname can be used for a content or organization.", - "tags": ["custom-hostnames"], - "security": [ { - "user-internal": [] - } - ], - "parameters": [ + "$ref": "#/components/schemas/SiteShareLinkChannel" + }, { - "$ref": "#/components/parameters/hostname" + "$ref": "#/components/schemas/CustomHostnameChannel" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "target": { - "oneOf": [ - { - "$ref": "#/components/schemas/OrganizationPointer" - }, - { - "$ref": "#/components/schemas/SpacePointer" - }, - { - "$ref": "#/components/schemas/CollectionPointer" - } - ] - } - }, - "required": ["target"] - } - } - } - }, - "responses": { - "204": { - "description": "The custom hostname is available and valid." + "discriminator": { + "propertyName": "channel" + } + }, + "SiteAdsStatus": { + "type": "string", + "description": "The status of ads on the site", + "enum": ["pending", "in-review", "live", "rejected", "disabled"] + }, + "Seat": { + "type": "object", + "properties": { + "object": { + "type": "string", + "enum": ["seat"] }, - "400": { - "description": "The custom hostname is invalid.", - "$ref": "#/components/responses/BadRequestError" + "organization": { + "description": "The unique ID of the organization", + "type": "string" }, - "409": { - "description": "The custom hostname is already configured for this target or a different one.", - "$ref": "#/components/responses/ConflictError" + "member": { + "description": "The unique ID of the organization member", + "type": "string" }, - "default": { - "$ref": "#/components/responses/UnexpectedError" + "createdAt": { + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "format": "date-time" } - } + }, + "required": ["object", "organization", "member", "createdAt", "updatedAt"] + }, + "RequestSpaceTrackPageView": { + "$ref": "#/components/schemas/SpaceTrackPageView" + }, + "RequestSiteTrackPageView": { + "$ref": "#/components/schemas/SiteTrackPageView" + }, + "RequestPublishIntegration": { + "$ref": "#/components/schemas/PublishIntegration" + }, + "RequestUpdateIntegrationInstallation": { + "$ref": "#/components/schemas/UpdateIntegrationInstallation" + }, + "RequestUpdateIntegrationSpaceInstallation": { + "$ref": "#/components/schemas/UpdateIntegrationSpaceInstallation" + }, + "RequestUpdateIntegrationSiteInstallation": { + "$ref": "#/components/schemas/UpdateIntegrationSiteInstallation" + }, + "RequestUpgradeOrganizationBilling": { + "$ref": "#/components/schemas/UpgradeOrganizationBilling" + }, + "RequestInviteUsersToOrganization": { + "$ref": "#/components/schemas/InviteUsersToOrganization" + }, + "RequestImportGitRepository": { + "$ref": "#/components/schemas/ImportGitRepository" + }, + "RequestSyncGitRepository": { + "$ref": "#/components/schemas/SyncGitRepository" + }, + "RequestExportToGitRepository": { + "$ref": "#/components/schemas/ExportToGitRepository" + }, + "RequestImportContent": { + "$ref": "#/components/schemas/ImportContent" + }, + "RequestCreateSpace": { + "$ref": "#/components/schemas/CreateSpace" + }, + "RequestCreateChangeRequest": { + "$ref": "#/components/schemas/CreateChangeRequest" + }, + "RequestRenderIntegrationUI": { + "$ref": "#/components/schemas/RenderIntegrationUI" + }, + "RequestUpdateContentPublishingAuth": { + "$ref": "#/components/schemas/UpdateContentPublishingAuth" + }, + "RequestCreateOrganization": { + "$ref": "#/components/schemas/CreateOrganization" + }, + "RequestUpdateSpaceGitInfo": { + "$ref": "#/components/schemas/UpdateSpaceGitInfo" + }, + "RequestPurgeCDNCacheContext": { + "$ref": "#/components/schemas/PurgeCDNCacheContext" + }, + "SpaceVisitorAuth": { + "$ref": "#/components/schemas/VisitorAuth" + }, + "SpaceVisitorAuthCustomBackend": { + "$ref": "#/components/schemas/VisitorAuthCustomBackend" + }, + "SpaceVisitorAuthIntegrationBackend": { + "$ref": "#/components/schemas/VisitorAuthIntegrationBackend" + }, + "UserPermissions": { + "$ref": "#/components/schemas/_index" } }, - "/internal/hive/token": { - "post": { - "operationId": "generateHiveAccessToken", - "summary": "Returns a token to authenticate with Hive.", - "tags": ["hive"], - "security": [ - { - "user-internal": [] + "responses": { + "UnexpectedError": { + "description": "Unexpected Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } } - ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "spaces": { - "type": "array", - "items": { - "description": "ID of a space, potentially not directly listed in user permissions", + } + }, + "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" } - } - } - } - } - } - }, - "responses": { - "200": { - "description": "The JWT to access user's specific content in Hive.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/HiveAccessToken" + }, + "required": ["code", "message"] } } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/urls/content": { - "get": { - "operationId": "getContentByUrl", - "summary": "Resolve a URL to a content (space, collection, page)", - "tags": ["urls"], - "security": [ - { - "user": [] - } - ], - "parameters": [ - { - "name": "url", - "in": "query", - "required": true, - "description": "URL to resolve", + }, + "NotFoundError": { + "description": "Not Found", + "content": { + "application/json": { "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "oneOf": [ - { - "type": "object", - "description": "URL resolved to a collection", - "properties": { - "collection": { - "$ref": "#/components/schemas/Collection" - } - }, - "required": ["collection"] + "type": "object", + "required": ["error"], + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "enum": [404] }, - { - "type": "object", - "description": "URL resolved to the content of a space", - "properties": { - "space": { - "$ref": "#/components/schemas/Space" - }, - "changeRequest": { - "$ref": "#/components/schemas/ChangeRequest" - }, - "page": { - "oneOf": [ - { - "$ref": "#/components/schemas/RevisionPageDocument" - }, - { - "$ref": "#/components/schemas/RevisionPageGroup" - } - ] - } - }, - "required": ["space"] + "message": { + "type": "string" } - ] + }, + "required": ["code", "message"] } } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/urls/embed": { - "get": { - "operationId": "getEmbedByUrl", - "summary": "Resolve a URL to an embed", - "tags": ["urls"], - "parameters": [ - { - "name": "url", - "in": "query", - "required": true, - "description": "URL to resolve", + }, + "ConflictError": { + "description": "Conflict", + "content": { + "application/json": { "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Embed" + "type": "object", + "required": ["error"], + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "enum": [409] + }, + "message": { + "type": "string" + } + }, + "required": ["code", "message"] } } } - }, - "default": { - "$ref": "#/components/responses/UnexpectedError" } } - } - }, - "/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", + }, + "PreconditionFailedError": { + "description": "PreconditionFailed", + "content": { + "application/json": { "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublishedContentLookup" + "type": "object", + "required": ["error"], + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "enum": [412] + }, + "message": { + "type": "string" + } + }, + "required": ["code", "message"] } } } - }, - "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 361289e..6b5cecf 100644 --- a/tests/gitbook.test.ts +++ b/tests/gitbook.test.ts @@ -1,29 +1,6 @@ import { expect, test } from 'bun:test'; import { validateRequest, ValidationError } from './gitbook.validate'; -test('POST /spaces/1234/hive/token', () => { - const result = validateRequest({ - path: '/spaces/1234/hive/token', - method: 'post', - headers: { - 'content-type': 'application/json', - }, - query: {}, - }); - expect(result).toMatchObject({ - headers: { - 'content-type': 'application/json', - }, - method: 'post', - operationId: 'generateSpaceHiveReadAccessToken', - params: { - spaceId: '1234', - }, - path: '/spaces/1234/hive/token', - query: {}, - }); -}); - test('POST orgs/appleId/custom-fields', () => { const result = validateRequest({ path: '/orgs/appleId/custom-fields', @@ -114,70 +91,6 @@ test('POST orgs/appleId/custom-fields', () => { }); }); -test('PUT orgs/apple/schemas/newType', () => { - const result = validateRequest({ - path: '/orgs/apple/schemas/newType', - method: 'put', - headers: { - 'content-type': 'application/json', - }, - query: {}, - body: { - type: 'newType', - title: { - singular: 'New type', - plural: 'New types', - }, - properties: [ - { - name: 'title', - type: 'text', - title: 'Title', - }, - ], - }, - }); - expect(result).toMatchObject({ - operationId: 'setEntitySchema', - params: { - organizationId: 'apple', - entityType: 'newType', - }, - }); -}); - -test('PUT orgs/apple/schemas/newType/entities', () => { - const result = validateRequest({ - path: '/orgs/apple/schemas/newType/entities', - method: 'put', - headers: { - 'content-type': 'application/json', - }, - query: {}, - body: { - entities: [ - { - entityId: 'something', - properties: { - title: 'Updated lambda', - description: 'the description', - url: 'https://example.com', - public_traffic: false, - created_on: '2020-01-01T00:00:00.000Z', - }, - }, - ], - }, - }); - expect(result).toMatchObject({ - operationId: 'upsertSchemaEntities', - params: { - organizationId: 'apple', - entityType: 'newType', - }, - }); -}); - test('POST orgs/apple/members/jony (invalid)', () => { const result = validateRequest({ path: '/orgs/apple/members/jony', @@ -319,7 +232,7 @@ test('GET spaces/space_iphone-doc/revisions/somerevision/files?metadata=true', ( }); }); -test('GET spaces/space_iphone-doc/revisions/somerevision/files?limit=1000 (invalid, number above maximum)', () => { +test('GET spaces/space_iphone-doc/revisions/somerevision/files?limit=1001 (invalid, number above maximum)', () => { const result = validateRequest({ path: '/spaces/space_iphone-doc/revisions/somerevision/files', method: 'get', @@ -327,7 +240,7 @@ test('GET spaces/space_iphone-doc/revisions/somerevision/files?limit=1000 (inval 'content-type': 'application/json', }, query: { - limit: '1000', + limit: '1001', }, }); expect(result instanceof ValidationError ? result.path : null).toEqual(['query', 'limit']); @@ -346,3 +259,31 @@ test('GET spaces/space_iphone-doc/revisions/somerevision/files?limit=-1 (invalid }); expect(result instanceof ValidationError ? result.path : null).toEqual(['query', 'limit']); }); + +test('/orgs/xxx/synced-blocks?ids=foo coerce string parameter as array if array is expected', () => { + const result = validateRequest({ + path: '/orgs/xxx/synced-blocks', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: { + ids: 'foo', + }, + }); + expect(result.query).toEqual({ ids: ['foo'] }); +}); + +test('/orgs/xxx/synced-blocks?ids[]=foo allow string parameter as array too', () => { + const result = validateRequest({ + path: '/orgs/xxx/synced-blocks', + method: 'get', + headers: { + 'content-type': 'application/json', + }, + query: { + ids: ['foo'], + }, + }); + expect(result.query).toEqual({ ids: ['foo'] }); +});