From 3554dc72377f890ffc9ecfb3b0803415c2acd651 Mon Sep 17 00:00:00 2001 From: Hans Pagel Date: Mon, 29 Jan 2024 16:51:56 +0100 Subject: [PATCH] refactor: move all commands to separate files --- packages/cli/openapi.json | 8490 ++++++++--------- .../cli/src/commands/format/FormatCommand.ts | 46 + packages/cli/src/commands/index.ts | 6 + packages/cli/src/commands/init/InitCommand.ts | 83 + packages/cli/src/commands/mock/MockCommand.ts | 134 + .../commands/reference/ReferenceCommand.ts | 99 + .../cli/src/commands/share/ShareCommand.ts | 69 + .../src/commands/validate/ValidateCommand.ts | 61 + packages/cli/src/index.ts | 458 +- 9 files changed, 4746 insertions(+), 4700 deletions(-) create mode 100644 packages/cli/src/commands/format/FormatCommand.ts create mode 100644 packages/cli/src/commands/index.ts create mode 100644 packages/cli/src/commands/init/InitCommand.ts create mode 100644 packages/cli/src/commands/mock/MockCommand.ts create mode 100644 packages/cli/src/commands/reference/ReferenceCommand.ts create mode 100644 packages/cli/src/commands/share/ShareCommand.ts create mode 100644 packages/cli/src/commands/validate/ValidateCommand.ts diff --git a/packages/cli/openapi.json b/packages/cli/openapi.json index e962b85e..1203472e 100644 --- a/packages/cli/openapi.json +++ b/packages/cli/openapi.json @@ -1,4578 +1,4554 @@ { - "openapi": "3.0.0", - "info": { - "title": "Outline API", - "description": "# Introduction\n\nThe Outline API is structured in an RPC style. It enables you to\nprogramatically interact with all aspects of Outline’s data – in fact, the\nmain application is built on exactly the same API.\n\nThe API structure is available as an\n[openapi specification](https://github.com/outline/openapi) if that’s your\njam – it can be used to generate clients for most programming languages.\n\n# Making requests\n\nOutline’s API follows simple RPC style conventions where each API endpoint is\na method on `https://app.getoutline.com/api/method`. Both `GET` and `POST`\nmethods are supported but it’s recommended that you make all call using POST.\nOnly HTTPS is supported and all response payloads are JSON.\n\nWhen making `POST` requests, request parameters are parsed depending on\nContent-Type header. To make a call using JSON payload, you must pass\nContent-Type: application/json header, here’s an example using CURL:\n\n```\ncurl https://app.getoutline.com/api/documents.info \\\n-X 'POST' \\\n-H 'authorization: Bearer MY_API_KEY' \\\n-H 'content-type: application/json' \\\n-H 'accept: application/json' \\\n-d '{\"id\": \"outline-api-NTpezNwhUP\"}'\n```\n\nOr, with JavaScript:\n\n```javascript\nconst response = await fetch(\"https://app.getoutline.com/api/documents.info\", {\n method: \"POST\",\n headers: {\n Accept: \"application/json\",\n \"Content-Type\": \"application/json\",\n Authorization: \"Bearer MY_API_KEY\"\n }\n})\n\nconst body = await response.json();\nconst document = body.data;\n```\n\n# Authentication\n\nTo access API endpoints, you must provide a valid API key. You can create new\nAPI keys in your [account settings](https://app.getoutline.com/settings). Be\ncareful when handling your keys as they give access to all of your documents,\nyou should treat them like passwords and they should never be committed to\nsource control.\n\nTo authenticate with API, you can supply the API key as a header\n(`Authorization: Bearer YOUR_API_KEY`) or as part of the payload using `token`\nparameter. Header based authentication is highly recommended so that your keys\ndon’t accidentally leak into logs.\n\nSome API endpoints allow unauthenticated requests for public resources and\nthey can be called without an API key.\n\n# Errors\n\nAll successful API requests will be returned with a 200 or 201 status code\nand `ok: true` in the response payload. If there’s an error while making the\nrequest, the appropriate status code is returned with the error message:\n\n```\n{\n \"ok\": false,\n \"error\": \"Not Found\"\n}\n```\n\n# Pagination\n\nMost top-level API resources have support for \"list\" API methods. For instance,\nyou can list users, documents, and collections. These list methods share\ncommon parameters, taking both `limit` and `offset`.\n\nResponses will echo these parameters in the root `pagination` key, and also\ninclude a `nextPath` key which can be used as a handy shortcut to fetch the\nnext page of results. For example:\n\n```\n{\n ok: true,\n status: 200,\n data: […],\n pagination: {\n limit: 25,\n offset: 0,\n nextPath: \"/api/documents.list?limit=25&offset=25\"\n }\n}\n```\n\n# Policies\n\nMany API resources have associated \"policies\", these objects describe the\ncurrent API keys authorized actions related to an individual resource. It\nshould be noted that the policy \"id\" is identical to the resource it is\nrelated to, policies themselves do not have unique identifiers.\n\nFor most usecases of the API, policies can be safely ignored. Calling\nunauthorized methods will result in the appropriate response code – these are\nused in the main Outline UI to adjust which elements are visible.\n", - "version": "0.1.0", - "contact": { "email": "hello@getoutline.com" } + "openapi": "3.0.0", + "info": { + "title": "Outline API", + "description": "# Introduction\n\nThe Outline API is structured in an RPC style. It enables you to\nprogramatically interact with all aspects of Outline’s data – in fact, the\nmain application is built on exactly the same API.\n\nThe API structure is available as an\n[openapi specification](https://github.com/outline/openapi) if that’s your\njam – it can be used to generate clients for most programming languages.\n\n# Making requests\n\nOutline’s API follows simple RPC style conventions where each API endpoint is\na method on `https://app.getoutline.com/api/method`. Both `GET` and `POST`\nmethods are supported but it’s recommended that you make all call using POST.\nOnly HTTPS is supported and all response payloads are JSON.\n\nWhen making `POST` requests, request parameters are parsed depending on\nContent-Type header. To make a call using JSON payload, you must pass\nContent-Type: application/json header, here’s an example using CURL:\n\n```\ncurl https://app.getoutline.com/api/documents.info \\\n-X 'POST' \\\n-H 'authorization: Bearer MY_API_KEY' \\\n-H 'content-type: application/json' \\\n-H 'accept: application/json' \\\n-d '{\"id\": \"outline-api-NTpezNwhUP\"}'\n```\n\nOr, with JavaScript:\n\n```javascript\nconst response = await fetch(\"https://app.getoutline.com/api/documents.info\", {\n method: \"POST\",\n headers: {\n Accept: \"application/json\",\n \"Content-Type\": \"application/json\",\n Authorization: \"Bearer MY_API_KEY\"\n }\n})\n\nconst body = await response.json();\nconst document = body.data;\n```\n\n# Authentication\n\nTo access API endpoints, you must provide a valid API key. You can create new\nAPI keys in your [account settings](https://app.getoutline.com/settings). Be\ncareful when handling your keys as they give access to all of your documents,\nyou should treat them like passwords and they should never be committed to\nsource control.\n\nTo authenticate with API, you can supply the API key as a header\n(`Authorization: Bearer YOUR_API_KEY`) or as part of the payload using `token`\nparameter. Header based authentication is highly recommended so that your keys\ndon’t accidentally leak into logs.\n\nSome API endpoints allow unauthenticated requests for public resources and\nthey can be called without an API key.\n\n# Errors\n\nAll successful API requests will be returned with a 200 or 201 status code\nand `ok: true` in the response payload. If there’s an error while making the\nrequest, the appropriate status code is returned with the error message:\n\n```\n{\n \"ok\": false,\n \"error\": \"Not Found\"\n}\n```\n\n# Pagination\n\nMost top-level API resources have support for \"list\" API methods. For instance,\nyou can list users, documents, and collections. These list methods share\ncommon parameters, taking both `limit` and `offset`.\n\nResponses will echo these parameters in the root `pagination` key, and also\ninclude a `nextPath` key which can be used as a handy shortcut to fetch the\nnext page of results. For example:\n\n```\n{\n ok: true,\n status: 200,\n data: […],\n pagination: {\n limit: 25,\n offset: 0,\n nextPath: \"/api/documents.list?limit=25&offset=25\"\n }\n}\n```\n\n# Policies\n\nMany API resources have associated \"policies\", these objects describe the\ncurrent API keys authorized actions related to an individual resource. It\nshould be noted that the policy \"id\" is identical to the resource it is\nrelated to, policies themselves do not have unique identifiers.\n\nFor most usecases of the API, policies can be safely ignored. Calling\nunauthorized methods will result in the appropriate response code – these are\nused in the main Outline UI to adjust which elements are visible.\n", + "version": "0.1.0", + "contact": { "email": "hello@getoutline.com" } + }, + "servers": [ + { "url": "https://app.getoutline.com/api", "description": "Production" } + ], + "security": [{ "http": [] }], + "tags": [ + { + "name": "Attachments", + "description": "`Attachments` represent a file uploaded to cloud storage. They are created\nbefore the upload happens from the client and store all the meta information\nsuch as file type, size, and location.\n" }, - "servers": [ - { "url": "https://app.getoutline.com/api", "description": "Production" } - ], - "security": [{ "http": [] }], - "tags": [ - { - "name": "Attachments", - "description": "`Attachments` represent a file uploaded to cloud storage. They are created\nbefore the upload happens from the client and store all the meta information\nsuch as file type, size, and location.\n" - }, - { - "name": "Auth", - "description": "`Auth` represents the current API Keys authentication details. It can be\nused to check that a token is still valid and load the IDs for the current\nuser and team.\n" - }, - { - "name": "Collections", - "description": "`Collections` represent grouping of documents in the knowledge base, they\noffer a way to structure information in a nested hierarchy and a level\nat which read and write permissions can be granted to individual users or\ngroups of users.\n" - }, - { - "name": "Comments", - "description": "`Comments` represent a comment either on a selection of text in a document\nor on the document itself.\n" - }, - { - "name": "Documents", - "description": "`Documents` are what everything else revolves around. A document represents\na single page of information and always returns the latest version of the\ncontent. Documents are stored in [Markdown](https://spec.commonmark.org/)\nformatting.\n" - }, - { - "name": "Events", - "description": "`Events` represent an artifact of an action. Whether it is creating a user,\nediting a document, changing permissions, or any other action – an event\nis created that can be used as an audit trail or activity stream.\n" - }, - { - "name": "FileOperations", - "description": "`FileOperations` represent background jobs for importing or exporting files.\nYou can query the file operation to find the state of progress and any\nresulting output.\n" - }, - { - "name": "Groups", - "description": "`Groups` represent a list of users that logically belong together, for\nexample there might be groups for each department in your organization.\nGroups can be granted access to collections with read or write permissions.\n" - }, - { - "name": "Revisions", - "description": "`Revisions` represent a snapshop of a document at a point in time. They\nare used to keep tracking of editing and collaboration history – a document\ncan also be restored to a previous revision if neccessary.\n" - }, - { - "name": "Shares", - "description": "`Shares` represent authorization to view a document without being a member\nof the team. Shares are created in order to give access to documents publicly.\nEach user that shares a document will have a unique share object.\n" - }, - { - "name": "Users", - "description": "`Users` represent an individual with access to the knowledge base. Users\ncan be created automatically when signing in with SSO or when a user is\ninvited via email.\n" - }, - { - "name": "Views", - "description": "`Views` represent a compressed record of an individual users views of a\ndocument. Individual views are not recorded but a first, last and total\nis kept per user.\n" - } - ], - "paths": { - "/attachments.create": { - "post": { - "tags": ["Attachments"], - "summary": "Create an attachment", - "description": "Creating an attachment object creates a database record and returns the inputs needed to generate a signed url and upload the file from the client to cloud storage.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "image.png" - }, - "documentId": { - "type": "string", - "description": "Identifier for the associated document, if any.", - "format": "uuid" - }, - "contentType": { - "type": "string", - "example": "image/png" - }, - "size": { - "type": "number", - "description": "Size of the file attachment in bytes." - } - }, - "required": ["name", "contentType", "size"] - } - } - } + { + "name": "Auth", + "description": "`Auth` represents the current API Keys authentication details. It can be\nused to check that a token is still valid and load the IDs for the current\nuser and team.\n" + }, + { + "name": "Collections", + "description": "`Collections` represent grouping of documents in the knowledge base, they\noffer a way to structure information in a nested hierarchy and a level\nat which read and write permissions can be granted to individual users or\ngroups of users.\n" + }, + { + "name": "Comments", + "description": "`Comments` represent a comment either on a selection of text in a document\nor on the document itself.\n" + }, + { + "name": "Documents", + "description": "`Documents` are what everything else revolves around. A document represents\na single page of information and always returns the latest version of the\ncontent. Documents are stored in [Markdown](https://spec.commonmark.org/)\nformatting.\n" + }, + { + "name": "Events", + "description": "`Events` represent an artifact of an action. Whether it is creating a user,\nediting a document, changing permissions, or any other action – an event\nis created that can be used as an audit trail or activity stream.\n" + }, + { + "name": "FileOperations", + "description": "`FileOperations` represent background jobs for importing or exporting files.\nYou can query the file operation to find the state of progress and any\nresulting output.\n" + }, + { + "name": "Groups", + "description": "`Groups` represent a list of users that logically belong together, for\nexample there might be groups for each department in your organization.\nGroups can be granted access to collections with read or write permissions.\n" + }, + { + "name": "Revisions", + "description": "`Revisions` represent a snapshop of a document at a point in time. They\nare used to keep tracking of editing and collaboration history – a document\ncan also be restored to a previous revision if neccessary.\n" + }, + { + "name": "Shares", + "description": "`Shares` represent authorization to view a document without being a member\nof the team. Shares are created in order to give access to documents publicly.\nEach user that shares a document will have a unique share object.\n" + }, + { + "name": "Users", + "description": "`Users` represent an individual with access to the knowledge base. Users\ncan be created automatically when signing in with SSO or when a user is\ninvited via email.\n" + }, + { + "name": "Views", + "description": "`Views` represent a compressed record of an individual users views of a\ndocument. Individual views are not recorded but a first, last and total\nis kept per user.\n" + } + ], + "paths": { + "/attachments.create": { + "post": { + "tags": ["Attachments"], + "summary": "Create an attachment", + "description": "Creating an attachment object creates a database record and returns the inputs needed to generate a signed url and upload the file from the client to cloud storage.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "image.png" + }, + "documentId": { + "type": "string", + "description": "Identifier for the associated document, if any.", + "format": "uuid" + }, + "contentType": { + "type": "string", + "example": "image/png" + }, + "size": { + "type": "number", + "description": "Size of the file attachment in bytes." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "maxUploadSize": { - "type": "number" - }, - "uploadUrl": { - "type": "string", - "format": "uri" - }, - "form": { "type": "object" }, - "attachment": { - "$ref": "#/components/schemas/Attachment" - } - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["name", "contentType", "size"] + } } + } }, - "/attachments.redirect": { - "post": { - "tags": ["Attachments"], - "summary": "Retrieve an attachment", - "description": "Load an attachment from where it is stored based on the id. If the attachment is private then a temporary, signed url with embedded credentials is generated on demand.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the attachment.", - "format": "uuid" - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "maxUploadSize": { + "type": "number" + }, + "uploadUrl": { + "type": "string", + "format": "uri" + }, + "form": { "type": "object" }, + "attachment": { + "$ref": "#/components/schemas/Attachment" + } + } } - }, - "responses": { - "302": { "description": "The url for the attachment" } + } } + } } - }, - "/attachments.delete": { - "post": { - "tags": ["Attachments"], - "summary": "Delete an attachment", - "description": "Deleting an attachment is permanant. It will not delete references or links to the attachment that may exist in your documents.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid", - "description": "Unique identifier for the attachment." - } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/attachments.redirect": { + "post": { + "tags": ["Attachments"], + "summary": "Retrieve an attachment", + "description": "Load an attachment from where it is stored based on the id. If the attachment is private then a temporary, signed url with embedded credentials is generated on demand.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the attachment.", + "format": "uuid" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/auth.info": { - "post": { - "tags": ["Auth"], - "summary": "Retrieve auth", - "description": "Retrieve authentication details for the current API key", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Auth" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" } - } + "responses": { + "302": { "description": "The url for the attachment" } + } + } + }, + "/attachments.delete": { + "post": { + "tags": ["Attachments"], + "summary": "Delete an attachment", + "description": "Deleting an attachment is permanant. It will not delete references or links to the attachment that may exist in your documents.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for the attachment." + } + }, + "required": ["id"] + } } + } }, - "/auth.config": { - "post": { - "tags": ["Auth"], - "summary": "Retrieve auth config", - "description": "Retrieve authentication options", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "Acme Inc" - }, - "hostname": { - "type": "string", - "example": "acme-inc.getoutline.com" - }, - "services": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "slack" - }, - "name": { - "type": "string", - "example": "Slack" - }, - "authUrl": { - "type": "string", - "example": "https://acme-inc.getoutline.com/auth/slack" - } - } - } - } - } - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } + } } + } } - }, - "/collections.info": { - "post": { - "tags": ["Collections"], - "summary": "Retrieve a collection", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the collection.", - "format": "uuid" - } - }, - "required": ["id"] - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/auth.info": { + "post": { + "tags": ["Auth"], + "summary": "Retrieve auth", + "description": "Retrieve authentication details for the current API key", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Auth" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Collection" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/collections.documents": { - "post": { - "tags": ["Collections"], - "summary": "Retrieve a collections document structure", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the collection.", - "format": "uuid" - } - }, - "required": ["id"] + }, + "401": { "$ref": "#/components/responses/Unauthenticated" } + } + } + }, + "/auth.config": { + "post": { + "tags": ["Auth"], + "summary": "Retrieve auth config", + "description": "Retrieve authentication options", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Acme Inc" + }, + "hostname": { + "type": "string", + "example": "acme-inc.getoutline.com" + }, + "services": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "slack" + }, + "name": { + "type": "string", + "example": "Slack" + }, + "authUrl": { + "type": "string", + "example": "https://acme-inc.getoutline.com/auth/slack" + } } + } } + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NavigationNode" - }, - "example": [] - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/collections.list": { - "post": { - "tags": ["Collections"], - "summary": "List all collections", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pagination" - } - } - } + } + } + } + }, + "/collections.info": { + "post": { + "tags": ["Collections"], + "summary": "Retrieve a collection", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the collection.", + "format": "uuid" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Collection" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["id"] + } } + } }, - "/collections.create": { - "post": { - "tags": ["Collections"], - "summary": "Create a collection", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "Human Resources" - }, - "description": { - "type": "string", - "example": "" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - }, - "color": { - "type": "string", - "example": "#123123" - }, - "private": { - "type": "boolean", - "example": false - } - }, - "required": ["name"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Collection" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Collection" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/collections.update": { - "post": { - "tags": ["Collections"], - "summary": "Update a collection", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string", - "example": "Human Resources" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - }, - "description": { - "type": "string", - "example": "" - }, - "color": { - "type": "string", - "example": "#123123" - } - }, - "required": ["id"] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.documents": { + "post": { + "tags": ["Collections"], + "summary": "Retrieve a collections document structure", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the collection.", + "format": "uuid" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Collection" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/collections.add_user": { - "post": { - "tags": ["Collections"], - "summary": "Add a collection user", - "description": "This method allows you to add a user membership to the specified collection.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - } - }, - "required": ["id", "userId"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NavigationNode" + }, + "example": [] } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "users": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "memberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Membership" - } - } - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.list": { + "post": { + "tags": ["Collections"], + "summary": "List all collections", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pagination" + } } + } }, - "/collections.remove_user": { - "post": { - "tags": ["Collections"], - "summary": "Remove a collection user", - "description": "This method allows you to remove a user from the specified collection.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Identifier for the collection", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["id", "userId"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + } } + } } - }, - "/collections.memberships": { - "post": { - "tags": ["Collections"], - "summary": "List all collection memberships", - "description": "This method allows you to list a collections individual memberships. It's important to note that memberships returned from this endpoint do not include group memberships.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Identifier for the collection", - "format": "uuid" - }, - "query": { - "type": "string", - "description": "Filter memberships by user names", - "example": "jenny" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - } - }, - "required": ["id"] - } - ] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/collections.create": { + "post": { + "tags": ["Collections"], + "summary": "Create a collection", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Human Resources" + }, + "description": { + "type": "string", + "example": "" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + }, + "color": { + "type": "string", + "example": "#123123" + }, + "private": { + "type": "boolean", + "example": false + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "users": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "memberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Membership" - } - } - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["name"] + } } + } }, - "/collections.add_group": { - "post": { - "tags": ["Collections"], - "summary": "Add a group to a collection", - "description": "This method allows you to give all members in a group access to a collection.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "groupId": { - "type": "string", - "format": "uuid" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - } - }, - "required": ["id", "groupId"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "collectionGroupMemberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionGroupMembership" - } - } - } - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Collection" }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/collections.remove_group": { - "post": { - "tags": ["Collections"], - "summary": "Remove a collection group", - "description": "This method allows you to revoke all members in a group access to a collection. Note that members of the group may still retain access through other groups or individual memberships.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Identifier for the collection", - "format": "uuid" - }, - "groupId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["id", "groupId"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/collections.update": { + "post": { + "tags": ["Collections"], + "summary": "Update a collection", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "example": "Human Resources" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + }, + "description": { + "type": "string", + "example": "" + }, + "color": { + "type": "string", + "example": "#123123" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/collections.group_memberships": { - "post": { - "tags": ["Collections"], - "summary": "List all collection group members", - "description": "This method allows you to list a collections group memberships. This is the list of groups that have been given access to the collection.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Identifier for the collection", - "format": "uuid" - }, - "query": { - "type": "string", - "description": "Filter memberships by group names", - "example": "developers" - }, - "permission": { - "$ref": "#/components/schemas/Permission" - } - }, - "required": ["id"] - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Group" - } - }, - "collectionGroupMemberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CollectionGroupMembership" - } - } - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Collection" }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/collections.delete": { - "post": { - "tags": ["Collections"], - "summary": "Delete a collection", - "description": "Delete a collection and all of its documents. This action can’t be undone so please be careful.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.add_user": { + "post": { + "tags": ["Collections"], + "summary": "Add a collection user", + "description": "This method allows you to add a user membership to the specified collection.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "userId": { + "type": "string", + "format": "uuid" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id", "userId"] + } } + } }, - "/collections.export": { - "post": { - "tags": ["Collections"], - "summary": "Export a collection", - "description": "Triggers a bulk export of the collection in markdown format and their attachments. If documents are nested then they will be nested in folders inside the zip file. The endpoint returns a `FileOperation` that can be queried to track the progress of the export and get the url for the final file.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "format": { - "type": "string", - "enum": [ - "outline-markdown", - "json", - "html" - ] - }, - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "memberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Membership" + } + } + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "fileOperation": { - "$ref": "#/components/schemas/FileOperation" - } - } - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/collections.export_all": { - "post": { - "tags": ["Collections"], - "summary": "Export all collections", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "format": { - "type": "string", - "enum": [ - "outline-markdown", - "json", - "html" - ] - } - } - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.remove_user": { + "post": { + "tags": ["Collections"], + "summary": "Remove a collection user", + "description": "This method allows you to remove a user from the specified collection.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Identifier for the collection", + "format": "uuid" + }, + "userId": { + "type": "string", + "format": "uuid" + } }, - "description": "Triggers a bulk export of all documents in and their attachments. The endpoint returns a `FileOperation` that can be queried through the fileOperations endpoint to track the progress of the export and get the url for the final file.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "fileOperation": { - "$ref": "#/components/schemas/FileOperation" - } - } - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id", "userId"] + } } + } }, - "/comments.create": { - "post": { - "tags": ["Comments"], - "summary": "Create a comment", - "description": "Create a comment", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "documentId": { - "type": "string", - "format": "uuid" - }, - "parentCommentId": { - "type": "string", - "format": "uuid" - }, - "data": { "type": "object" } - }, - "required": ["documentId", "data"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Comment" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.memberships": { + "post": { + "tags": ["Collections"], + "summary": "List all collection memberships", + "description": "This method allows you to list a collections individual memberships. It's important to note that memberships returned from this endpoint do not include group memberships.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Identifier for the collection", + "format": "uuid" + }, + "query": { + "type": "string", + "description": "Filter memberships by user names", + "example": "jenny" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + } + }, + "required": ["id"] + } + ] + } } + } }, - "/comments.update": { - "post": { - "tags": ["Comments"], - "summary": "Update a comment", - "description": "Update a comment", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "data": { "type": "object" } - }, - "required": ["id", "data"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "memberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Membership" + } + } + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Comment" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/comments.delete": { - "post": { - "tags": ["Comments"], - "summary": "Delete a comment", - "description": "Delete a comment", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/collections.add_group": { + "post": { + "tags": ["Collections"], + "summary": "Add a group to a collection", + "description": "This method allows you to give all members in a group access to a collection.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "groupId": { + "type": "string", + "format": "uuid" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id", "groupId"] + } } + } }, - "/comments.list": { - "post": { - "tags": ["Comments"], - "summary": "List all comments", - "description": "This method will list all comments matching the given properties.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "documentId": { - "type": "string", - "format": "uuid", - "description": "Filter to a specific document" - }, - "collectionId": { - "type": "string", - "format": "uuid", - "description": "Filter to a specific collection" - } - } - } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "collectionGroupMemberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionGroupMembership" + } + } + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/documents.info": { - "post": { - "tags": ["Documents"], - "summary": "Retrieve a document", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - }, - "shareId": { - "type": "string", - "format": "uuid", - "description": "Unique identifier for a document share, a shareId may be used in place of a document UUID" - } - } - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.remove_group": { + "post": { + "tags": ["Collections"], + "summary": "Remove a collection group", + "description": "This method allows you to revoke all members in a group access to a collection. Note that members of the group may still retain access through other groups or individual memberships.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Identifier for the collection", + "format": "uuid" + }, + "groupId": { + "type": "string", + "format": "uuid" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id", "groupId"] + } } + } }, - "/documents.import": { - "post": { - "tags": ["Documents"], - "summary": "Import a file as a document", - "description": "This method allows you to create a new document by importing an existing file. By default a document is set to the collection root. If you want to create a nested/child document, you should pass parentDocumentId to set the parent document.", - "requestBody": { - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "file": { - "type": "object", - "description": "Only plain text, markdown, docx, and html format are supported." - }, - "collectionId": { - "type": "string", - "format": "uuid" - }, - "parentDocumentId": { - "type": "string", - "format": "uuid" - }, - "template": { "type": "boolean" }, - "publish": { "type": "boolean" } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.group_memberships": { + "post": { + "tags": ["Collections"], + "summary": "List all collection group members", + "description": "This method allows you to list a collections group memberships. This is the list of groups that have been given access to the collection.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Identifier for the collection", + "format": "uuid" + }, + "query": { + "type": "string", + "description": "Filter memberships by group names", + "example": "developers" + }, + "permission": { + "$ref": "#/components/schemas/Permission" + } + }, + "required": ["id"] + } + ] + } } + } }, - "/documents.export": { - "post": { - "tags": ["Documents"], - "summary": "Export a document as markdown", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Group" + } + }, + "collectionGroupMemberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionGroupMembership" + } + } + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "string", - "description": "The document content in Markdown formatting" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/documents.list": { - "post": { - "tags": ["Documents"], - "summary": "List all documents", - "description": "This method will list all published documents and draft documents belonging to the current user.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "collectionId": { - "type": "string", - "format": "uuid", - "description": "Optionally filter to a specific collection" - }, - "userId": { - "type": "string", - "format": "uuid" - }, - "backlinkDocumentId": { - "type": "string", - "format": "uuid" - }, - "parentDocumentId": { - "type": "string", - "format": "uuid" - }, - "template": { - "type": "boolean", - "description": "Optionally filter to only templates" - } - } - } - ] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/collections.delete": { + "post": { + "tags": ["Collections"], + "summary": "Delete a collection", + "description": "Delete a collection and all of its documents. This action can’t be undone so please be careful.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["id"] + } } + } }, - "/documents.drafts": { - "post": { - "tags": ["Documents"], - "summary": "List all draft documents", - "description": "This method will list all draft documents belonging to the current user.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "collectionId": { - "type": "string", - "description": "A collection to search within", - "format": "uuid" - }, - "dateFilter": { - "type": "string", - "description": "Any documents that have not been updated within the specified period will be filtered out", - "example": "month", - "enum": [ - "day", - "week", - "month", - "year" - ] - } - } - } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/documents.viewed": { - "post": { - "tags": ["Documents"], - "summary": "List all recently viewed documents", - "description": "This method will list all documents recently viewed by the current user.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" } - ] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.export": { + "post": { + "tags": ["Collections"], + "summary": "Export a collection", + "description": "Triggers a bulk export of the collection in markdown format and their attachments. If documents are nested then they will be nested in folders inside the zip file. The endpoint returns a `FileOperation` that can be queried to track the progress of the export and get the url for the final file.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "format": { + "type": "string", + "enum": ["outline-markdown", "json", "html"] + }, + "id": { "type": "string", "format": "uuid" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["id"] + } } + } }, - "/documents.search": { - "post": { - "tags": ["Documents"], - "summary": "Search all documents", - "description": "This methods allows you to search your teams documents with keywords. Note that search results will be restricted to those accessible by the current access token.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { - "type": "object", - "properties": { - "query": { - "type": "string", - "example": "hiring" - }, - "userId": { - "type": "string", - "description": "Any documents that have not been edited by the user identifier will be filtered out", - "format": "uuid" - }, - "collectionId": { - "type": "string", - "description": "A collection to search within", - "format": "uuid" - }, - "includeArchived": { - "type": "boolean" - }, - "includeDrafts": { - "type": "boolean" - }, - "dateFilter": { - "type": "string", - "description": "Any documents that have not been updated within the specified period will be filtered out", - "example": "month", - "enum": [ - "day", - "week", - "month", - "year" - ] - } - } - } - ] - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "fileOperation": { + "$ref": "#/components/schemas/FileOperation" } + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "context": { - "type": "string", - "description": "A short snippet of context from the document that includes the search query.", - "example": "At Acme Inc our hiring practices are inclusive" - }, - "ranking": { - "type": "number", - "description": "The ranking used to order search results based on relevance.", - "format": "float", - "example": 1.1844109 - }, - "document": { - "$ref": "#/components/schemas/Document" - } - } - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/documents.create": { - "post": { - "tags": ["Documents"], - "summary": "Create a document", - "description": "This method allows you to create or publish a new document. By default a document is set to the collection root. If you want to create a nested/child document, you should pass parentDocumentId to set the parent document.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "title": { - "type": "string", - "example": "Welcome to Acme Inc" - }, - "text": { - "type": "string", - "description": "The body of the document, may contain markdown formatting.", - "example": "…" - }, - "collectionId": { - "type": "string", - "format": "uuid" - }, - "parentDocumentId": { - "type": "string", - "format": "uuid" - }, - "templateId": { - "type": "string", - "format": "uuid" - }, - "template": { - "type": "boolean", - "description": "Whether this document should be considered to be a template." - }, - "publish": { - "type": "boolean", - "description": "Whether this document should be immediately published and made visible to other team members." - } - }, - "required": ["title", "collectionId"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/collections.export_all": { + "post": { + "tags": ["Collections"], + "summary": "Export all collections", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "format": { + "type": "string", + "enum": ["outline-markdown", "json", "html"] + } } + } } + } }, - "/documents.update": { - "post": { - "tags": ["Documents"], - "summary": "Update a document", - "description": "This method allows you to modify an already created document", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - }, - "title": { - "type": "string", - "description": "The title of the document." - }, - "text": { - "type": "string", - "description": "The body of the document, may contain markdown formatting.", - "example": "…" - }, - "append": { - "type": "boolean", - "description": "If true the text field will be appended to the end of the existing document, rather than the default behavior of replacing it. This is potentially useful for things like logging into a document." - }, - "publish": { - "type": "boolean", - "description": "Whether this document should be published and made visible to other team members, if a draft" - }, - "done": { - "type": "boolean", - "description": "Whether the editing session has finished, this will trigger any notifications. This property will soon be deprecated." - } - }, - "required": ["id"] - } + "description": "Triggers a bulk export of all documents in and their attachments. The endpoint returns a `FileOperation` that can be queried through the fileOperations endpoint to track the progress of the export and get the url for the final file.", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "fileOperation": { + "$ref": "#/components/schemas/FileOperation" } + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/documents.templatize": { - "post": { - "tags": ["Documents"], - "summary": "Create a template from a document", - "description": "This method allows you to createa new template using an existing document as the basis", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/comments.create": { + "post": { + "tags": ["Comments"], + "summary": "Create a comment", + "description": "Create a comment", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "documentId": { + "type": "string", + "format": "uuid" + }, + "parentCommentId": { + "type": "string", + "format": "uuid" + }, + "data": { "type": "object" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["documentId", "data"] + } } + } }, - "/documents.star": { - "post": { - "tags": ["Documents"], - "summary": "Star a document", - "description": "Starring a document gives it extra priority in the UI and makes it easier to find important information later.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Comment" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { "type": "boolean" } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/documents.unstar": { - "post": { - "tags": ["Documents"], - "summary": "Unstar a document", - "description": "Starring a document gives it extra priority in the UI and makes it easier to find important information later.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - } - }, - "required": ["id"] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/comments.update": { + "post": { + "tags": ["Comments"], + "summary": "Update a comment", + "description": "Update a comment", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "data": { "type": "object" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { "type": "boolean" } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id", "data"] + } } + } }, - "/documents.unpublish": { - "post": { - "tags": ["Documents"], - "summary": "Unpublish a document", - "description": "Unpublishing a document moves it back to a draft status and out of the collection.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Comment" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/documents.move": { - "post": { - "tags": ["Documents"], - "summary": "Move a document", - "description": "Move a document to a new location or collection. If no parent document is provided, the document will be moved to the collection root.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - }, - "collectionId": { - "type": "string", - "format": "uuid" - }, - "parentDocumentId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/comments.delete": { + "post": { + "tags": ["Comments"], + "summary": "Delete a comment", + "description": "Delete a comment", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "documents": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Document" - } - }, - "collections": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Collection" - } - } - } - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/documents.archive": { - "post": { - "tags": ["Documents"], - "summary": "Archive a document", - "description": "Archiving a document allows outdated information to be moved out of sight whilst retaining the ability to optionally search and restore it later.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/documents.restore": { - "post": { - "tags": ["Documents"], - "summary": "Restore a document", - "description": "If a document has been archived or deleted, it can be restored. Optionally a revision can be passed to restore the document to a previous point in time.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - }, - "revisionId": { - "type": "string", - "format": "uuid", - "description": "Identifier for the revision to restore to." - } - }, - "required": ["id"] - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/comments.list": { + "post": { + "tags": ["Comments"], + "summary": "List all comments", + "description": "This method will list all comments matching the given properties.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "documentId": { + "type": "string", + "format": "uuid", + "description": "Filter to a specific document" + }, + "collectionId": { + "type": "string", + "format": "uuid", + "description": "Filter to a specific collection" + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Document" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + } + ] + } } + } }, - "/documents.delete": { - "post": { - "tags": ["Documents"], - "summary": "Delete a document", - "description": "Deleting a document moves it to the trash. If not restored within 30 days it is permenantly deleted.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "hDYep1TPAM", - "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." - }, - "permanent": { - "type": "boolean", - "example": false, - "description": "If set to true the document will be destroyed with no way to recover rather than moved to the trash." - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/events.list": { - "post": { - "tags": ["Events"], - "summary": "List all events", - "description": "Events are an audit trail of important events that happen in the knowledge base.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Filter to a specific event, e.g. \"collections.create\". Event names are in the format \"objects.verb\"" - }, - "actorId": { - "type": "string", - "format": "uuid", - "description": "Filter to events performed by the selected user" - }, - "documentId": { - "type": "string", - "format": "uuid", - "description": "Filter to events performed in the selected document" - }, - "collectionId": { - "type": "string", - "format": "uuid", - "description": "Filter to events performed in the selected collection" - }, - "auditLog": { - "type": "boolean", - "description": "Whether to return detailed events suitable for an audit log. Without this flag less detailed event types will be returned." - } - } - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Event" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.info": { + "post": { + "tags": ["Documents"], + "summary": "Retrieve a document", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + }, + "shareId": { + "type": "string", + "format": "uuid", + "description": "Unique identifier for a document share, a shareId may be used in place of a document UUID" + } } + } } + } }, - "/fileOperations.info": { - "post": { - "tags": ["FileOperations"], - "summary": "Retrieve a file operation", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the file operation.", - "format": "uuid" - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/FileOperation" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/fileOperations.redirect": { - "post": { - "tags": ["FileOperations"], - "summary": "Retrieve the file", - "description": "Load the resulting file from where it is stored based on the id. A temporary, signed url with embedded credentials is generated on demand.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the file operation.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/octet-stream": { - "schema": { - "type": "string", - "format": "binary" - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.import": { + "post": { + "tags": ["Documents"], + "summary": "Import a file as a document", + "description": "This method allows you to create a new document by importing an existing file. By default a document is set to the collection root. If you want to create a nested/child document, you should pass parentDocumentId to set the parent document.", + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "object", + "description": "Only plain text, markdown, docx, and html format are supported." + }, + "collectionId": { + "type": "string", + "format": "uuid" + }, + "parentDocumentId": { + "type": "string", + "format": "uuid" + }, + "template": { "type": "boolean" }, + "publish": { "type": "boolean" } } + } } + } }, - "/fileOperations.list": { - "post": { - "tags": ["FileOperations"], - "summary": "List all file operations", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of fileOperation", - "example": "export", - "enum": ["export", "import"] - } - }, - "required": ["type"] - } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FileOperation" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/groups.info": { - "post": { - "tags": ["Groups"], - "summary": "Retrieve a group", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the group.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Group" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.export": { + "post": { + "tags": ["Documents"], + "summary": "Export a document as markdown", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + } } + } } + } }, - "/groups.list": { - "post": { - "tags": ["Groups"], - "summary": "List all groups", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "The document content in Markdown formatting" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Group" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/groups.create": { - "post": { - "tags": ["Groups"], - "summary": "Create a group", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "Designers" - } - }, - "required": ["name"] - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.list": { + "post": { + "tags": ["Documents"], + "summary": "List all documents", + "description": "This method will list all published documents and draft documents belonging to the current user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "collectionId": { + "type": "string", + "format": "uuid", + "description": "Optionally filter to a specific collection" + }, + "userId": { + "type": "string", + "format": "uuid" + }, + "backlinkDocumentId": { + "type": "string", + "format": "uuid" + }, + "parentDocumentId": { + "type": "string", + "format": "uuid" + }, + "template": { + "type": "boolean", + "description": "Optionally filter to only templates" + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Group" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + } + ] + } } + } }, - "/groups.update": { - "post": { - "tags": ["Groups"], - "summary": "Update a group", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string", - "example": "Designers" - } - }, - "required": ["id", "name"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Group" - }, - "policies": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Policy" - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/groups.delete": { - "post": { - "tags": ["Groups"], - "summary": "Delete a group", - "description": "Deleting a group will cause all of its members to lose access to any collections the group has previously been added to. This action can’t be undone so please be careful.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.drafts": { + "post": { + "tags": ["Documents"], + "summary": "List all draft documents", + "description": "This method will list all draft documents belonging to the current user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "collectionId": { + "type": "string", + "description": "A collection to search within", + "format": "uuid" + }, + "dateFilter": { + "type": "string", + "description": "Any documents that have not been updated within the specified period will be filtered out", + "example": "month", + "enum": ["day", "week", "month", "year"] + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + } + ] + } } + } }, - "/groups.memberships": { - "post": { - "tags": ["Groups"], - "summary": "List all group members", - "description": "List and filter all the members in a group.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Group id", - "example": "a32c2ee6-fbde-4654-841b-0eabdc71b812" - }, - "query": { - "type": "string", - "description": "Filter memberships by user names", - "example": "jenny" - } - }, - "required": ["id"] - } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "users": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "groupMemberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GroupMembership" - } - } - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/groups.add_user": { - "post": { - "tags": ["Groups"], - "summary": "Add a group member", - "description": "This method allows you to add a user to the specified group.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["id", "userId"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "users": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Group" - } - }, - "groupMemberships": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Membership" - } - } - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.viewed": { + "post": { + "tags": ["Documents"], + "summary": "List all recently viewed documents", + "description": "This method will list all documents recently viewed by the current user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" } + ] + } } + } }, - "/groups.remove_user": { - "post": { - "tags": ["Groups"], - "summary": "Remove a group member", - "description": "This method allows you to remove a user from the group.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Identifier for the collection", - "format": "uuid" - }, - "userId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["id", "userId"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "object", - "properties": { - "groups": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Group" - } - } - } - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/revisions.info": { - "post": { - "tags": ["Revisions"], - "summary": "Retrieve a revision", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the revision.", - "format": "uuid" - } - }, - "required": ["id"] - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.search": { + "post": { + "tags": ["Documents"], + "summary": "Search all documents", + "description": "This methods allows you to search your teams documents with keywords. Note that search results will be restricted to those accessible by the current access token.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { + "type": "object", + "properties": { + "query": { + "type": "string", + "example": "hiring" + }, + "userId": { + "type": "string", + "description": "Any documents that have not been edited by the user identifier will be filtered out", + "format": "uuid" + }, + "collectionId": { + "type": "string", + "description": "A collection to search within", + "format": "uuid" + }, + "includeArchived": { + "type": "boolean" + }, + "includeDrafts": { + "type": "boolean" + }, + "dateFilter": { + "type": "string", + "description": "Any documents that have not been updated within the specified period will be filtered out", + "example": "month", + "enum": ["day", "week", "month", "year"] + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Revision" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + } + ] + } } + } }, - "/revisions.list": { - "post": { - "tags": ["Revisions"], - "summary": "List all revisions", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" } - ] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "context": { + "type": "string", + "description": "A short snippet of context from the document that includes the search query.", + "example": "At Acme Inc our hiring practices are inclusive" + }, + "ranking": { + "type": "number", + "description": "The ranking used to order search results based on relevance.", + "format": "float", + "example": 1.1844109 + }, + "document": { + "$ref": "#/components/schemas/Document" + } + } + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Revision" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + } } + } } - }, - "/shares.info": { - "post": { - "tags": ["Shares"], - "summary": "Retrieve a share object", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the share.", - "format": "uuid" - }, - "documentId": { - "type": "string", - "description": "Unique identifier for a document. One of id or documentId must be provided.", - "format": "uuid" - } - } - } - } - } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.create": { + "post": { + "tags": ["Documents"], + "summary": "Create a document", + "description": "This method allows you to create or publish a new document. By default a document is set to the collection root. If you want to create a nested/child document, you should pass parentDocumentId to set the parent document.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "example": "Welcome to Acme Inc" + }, + "text": { + "type": "string", + "description": "The body of the document, may contain markdown formatting.", + "example": "…" + }, + "collectionId": { + "type": "string", + "format": "uuid" + }, + "parentDocumentId": { + "type": "string", + "format": "uuid" + }, + "templateId": { + "type": "string", + "format": "uuid" + }, + "template": { + "type": "boolean", + "description": "Whether this document should be considered to be a template." + }, + "publish": { + "type": "boolean", + "description": "Whether this document should be immediately published and made visible to other team members." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Share" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["title", "collectionId"] + } } + } }, - "/shares.list": { - "post": { - "tags": ["Shares"], - "summary": "List all shares", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Share" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/shares.create": { - "post": { - "tags": ["Shares"], - "summary": "Create a share", - "description": "Creates a new share link that can be used by to access a document. If you request multiple shares for the same document with the same API key, the same share object will be returned. By default all shares are unpublished.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documentId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["documentId"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.update": { + "post": { + "tags": ["Documents"], + "summary": "Update a document", + "description": "This method allows you to modify an already created document", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + }, + "title": { + "type": "string", + "description": "The title of the document." + }, + "text": { + "type": "string", + "description": "The body of the document, may contain markdown formatting.", + "example": "…" + }, + "append": { + "type": "boolean", + "description": "If true the text field will be appended to the end of the existing document, rather than the default behavior of replacing it. This is potentially useful for things like logging into a document." + }, + "publish": { + "type": "boolean", + "description": "Whether this document should be published and made visible to other team members, if a draft" + }, + "done": { + "type": "boolean", + "description": "Whether the editing session has finished, this will trigger any notifications. This property will soon be deprecated." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Share" - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["id"] + } } + } }, - "/shares.update": { - "post": { - "tags": ["Shares"], - "summary": "Update a share", - "description": "Allows changing an existing shares published status, which removes authentication and makes it available to anyone with the link.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "published": { "type": "boolean" } - }, - "required": ["id", "published"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Share" - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/shares.revoke": { - "post": { - "tags": ["Shares"], - "summary": "Revoke a share", - "description": "Makes the share link inactive so that it can no longer be used to access the document.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { "type": "string", "format": "uuid" } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.templatize": { + "post": { + "tags": ["Documents"], + "summary": "Create a template from a document", + "description": "This method allows you to createa new template using an existing document as the basis", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "400": { "$ref": "#/components/responses/Validation" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/users.invite": { - "post": { - "tags": ["Users"], - "summary": "Invite users", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "invites": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Invite" - } - } - }, - "required": ["invites"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "sent": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Invite" - } - }, - "users": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/users.info": { - "post": { - "tags": ["Users"], - "summary": "Retrieve a user", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/documents.star": { + "post": { + "tags": ["Documents"], + "summary": "Star a document", + "description": "Starring a document gives it extra priority in the UI and makes it easier to find important information later.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/users.list": { - "post": { - "tags": ["Users"], - "summary": "List all users", - "description": "List and filter all the users in the team", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/Pagination" - }, - { "$ref": "#/components/schemas/Sorting" }, - { - "type": "object", - "properties": { - "query": { - "type": "string", - "example": "jane" - }, - "emails": { - "type": "array", - "items": { - "type": "string", - "description": "Array of emails", - "example": [ - "jane.crandall@mail.com", - "prudence.crandall@mail.com" - ] - } - }, - "filter": { - "type": "string", - "example": "all", - "enum": [ - "invited", - "viewers", - "admins", - "active", - "all", - "suspended" - ] - } - } - } - ] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/User" - } - }, - "pagination": { - "$ref": "#/components/schemas/Pagination" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean" } + } } + } } - }, - "/users.update": { - "post": { - "tags": ["Users"], - "summary": "Update a user", - "description": "Update a users name or avatar. No `id` is required as it is only possible to update the current user at this time.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "avatarUrl": { - "type": "string", - "format": "uri" - } - } - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.unstar": { + "post": { + "tags": ["Documents"], + "summary": "Unstar a document", + "description": "Starring a document gives it extra priority in the UI and makes it easier to find important information later.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/users.promote": { - "post": { - "tags": ["Users"], - "summary": "Promote a user", - "description": "Promote a user to be a team admin. This endpoint is only available for admin users.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean" } + } } + } } - }, - "/users.demote": { - "post": { - "tags": ["Users"], - "summary": "Demote a user", - "description": "Demote a team admin to regular user permissions. This endpoint is only available for admin users.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - }, - "to": { - "type": "string", - "description": "Which role to demote to", - "enum": ["viewer", "member"] - } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.unpublish": { + "post": { + "tags": ["Documents"], + "summary": "Unpublish a document", + "description": "Unpublishing a document moves it back to a draft status and out of the collection.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/users.suspend": { - "post": { - "tags": ["Users"], - "summary": "Suspend a user", - "description": "Suspending a user prevents the user from signing in. Users that are suspended are also not counted against billing totals in the hosted version.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } - }, - "/users.activate": { - "post": { - "tags": ["Users"], - "summary": "Activate a user", - "description": "Activating a previously suspended user allows them to signin again. Users that are activated will cause billing totals to be re-calculated in the hosted version.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - } - }, - "required": ["id"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.move": { + "post": { + "tags": ["Documents"], + "summary": "Move a document", + "description": "Move a document to a new location or collection. If no parent document is provided, the document will be moved to the collection root.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + }, + "collectionId": { + "type": "string", + "format": "uuid" + }, + "parentDocumentId": { + "type": "string", + "format": "uuid" + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/User" - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } + "required": ["id"] + } } + } }, - "/users.delete": { - "post": { - "tags": ["Users"], - "summary": "Delete a user", - "description": "Deleting a user removes the object entirely. In almost every circumstance it is preferable to suspend a user, as a deleted user can be recreated by signing in with SSO again.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the user.", - "format": "uuid" - } - }, - "required": ["id"] - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "collections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + } + } + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean", - "example": true - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } + } } + } } - }, - "/views.list": { - "post": { - "tags": ["Views"], - "summary": "List all views", - "description": "List all users that have viewed a document and the overall view count.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documentId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["documentId"] - } - } - } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.archive": { + "post": { + "tags": ["Documents"], + "summary": "Archive a document", + "description": "Archiving a document allows outdated information to be moved out of sight whilst retaining the ability to optionally search and restore it later.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + } }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/View" - } - } - } - } - } - } - }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } - } + "required": ["id"] + } } + } }, - "/views.create": { - "post": { - "tags": ["Views"], - "summary": "Create a view", - "description": "Creates a new view for a document. This is documented in the interests of thoroughness however it is recommended that views are not created from outside of the Outline UI.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "documentId": { - "type": "string", - "format": "uuid" - } - }, - "required": ["documentId"] - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/View" - } - } - } - } - } + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" }, - "401": { "$ref": "#/components/responses/Unauthenticated" }, - "403": { "$ref": "#/components/responses/Unauthorized" } + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } } + } } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } } + } }, - "components": { - "schemas": { - "Permission": { "type": "string", "enum": ["read", "read_write"] }, - "Attachment": { + "/documents.restore": { + "post": { + "tags": ["Documents"], + "summary": "Restore a document", + "description": "If a document has been archived or deleted, it can be restored. Optionally a revision can be passed to restore the document to a previous point in time.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "contentType": { "type": "string", "example": "image/png" }, - "size": { "type": "number" }, - "name": { "type": "string" }, - "url": { "type": "string", "format": "uri" }, - "documentId": { - "type": "string", - "description": "Identifier for the associated document, if any.", - "format": "uuid" + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + }, + "revisionId": { + "type": "string", + "format": "uuid", + "description": "Identifier for the revision to restore to." + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Document" + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } } + } } - }, - "Pagination": { - "type": "object", - "properties": { - "offset": { "type": "number" }, - "limit": { "type": "number", "example": 25 } - } - }, - "Sorting": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/documents.delete": { + "post": { + "tags": ["Documents"], + "summary": "Delete a document", + "description": "Deleting a document moves it to the trash. If not restored within 30 days it is permenantly deleted.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "sort": { "type": "string", "example": "updatedAt" }, - "direction": { - "type": "string", - "example": "DESC", - "enum": ["ASC", "DESC"] + "id": { + "type": "string", + "example": "hDYep1TPAM", + "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." + }, + "permanent": { + "type": "boolean", + "example": false, + "description": "If set to true the document will be destroyed with no way to recover rather than moved to the trash." + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } + } } - }, - "NavigationNode": { - "type": "object", - "properties": { - "id": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/events.list": { + "post": { + "tags": ["Events"], + "summary": "List all events", + "description": "Events are an audit trail of important events that happen in the knowledge base.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "name": { "type": "string", - "description": "Unique identifier for the document.", - "format": "uuid" - }, - "title": { "type": "string" }, - "url": { "type": "string" }, - "children": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NavigationNode" - } + "description": "Filter to a specific event, e.g. \"collections.create\". Event names are in the format \"objects.verb\"" + }, + "actorId": { + "type": "string", + "format": "uuid", + "description": "Filter to events performed by the selected user" + }, + "documentId": { + "type": "string", + "format": "uuid", + "description": "Filter to events performed in the selected document" + }, + "collectionId": { + "type": "string", + "format": "uuid", + "description": "Filter to events performed in the selected collection" + }, + "auditLog": { + "type": "boolean", + "description": "Whether to return detailed events suitable for an audit log. Without this flag less detailed event types will be returned." + } } + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + } } - }, - "Auth": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/fileOperations.info": { + "post": { + "tags": ["FileOperations"], + "summary": "Retrieve a file operation", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "user": { "$ref": "#/components/schemas/User" }, - "team": { "$ref": "#/components/schemas/Team" } + "id": { + "type": "string", + "description": "Unique identifier for the file operation.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/FileOperation" + } + } } - }, - "Collection": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/fileOperations.redirect": { + "post": { + "tags": ["FileOperations"], + "summary": "Retrieve the file", + "description": "Load the resulting file from where it is stored based on the id. A temporary, signed url with embedded credentials is generated on demand.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "name": { - "type": "string", - "description": "The name of the collection.", - "example": "Human Resources" - }, - "description": { - "type": "string", - "description": "A description of the collection, may contain markdown formatting", - "example": "" - }, - "sort": { - "type": "object", - "description": "The sort of documents in the collection. Note that not all API responses respect this and it is left as a frontend concern to implement.", - "properties": { - "field": { "type": "string" }, - "direction": { - "type": "string", - "enum": ["asc", "desc"] - } - } - }, - "index": { - "type": "string", - "description": "The position of the collection in the sidebar", - "example": "P" - }, - "color": { - "type": "string", - "description": "A color representing the collection, this is used to help make collections more identifiable in the UI. It should be in HEX format including the #", - "example": "#123123" - }, - "icon": { - "type": "string", - "description": "A string that represents an icon in the outline-icons package" - }, - "permission": { "$ref": "#/components/schemas/Permission" }, - "createdAt": { + "id": { + "type": "string", + "description": "Unique identifier for the file operation.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/fileOperations.list": { + "post": { + "tags": ["FileOperations"], + "summary": "List all file operations", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "type": { "type": "string", - "description": "The date and time that this object was created", - "readOnly": true, - "format": "date-time" + "description": "The type of fileOperation", + "example": "export", + "enum": ["export", "import"] + } }, - "updatedAt": { - "type": "string", - "description": "The date and time that this object was last changed", - "readOnly": true, - "format": "date-time" + "required": ["type"] + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FileOperation" + } }, - "deletedAt": { - "type": "string", - "nullable": true, - "description": "The date and time that this object was deleted", - "readOnly": true, - "format": "date-time" + "pagination": { + "$ref": "#/components/schemas/Pagination" } + } } - }, - "Comment": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/groups.info": { + "post": { + "tags": ["Groups"], + "summary": "Retrieve a group", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, + "id": { + "type": "string", + "description": "Unique identifier for the group.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { "data": { - "type": "object", - "description": "The editor data representing this comment." - }, - "documentId": { - "type": "string", - "description": "Identifier for the document this is related to.", - "format": "uuid" - }, - "parentCommentId": { - "type": "string", - "description": "Identifier for the comment this is a child of, if any.", - "format": "uuid" - }, - "createdAt": { - "type": "string", - "description": "The date and time that this object was created", - "readOnly": true, - "format": "date-time" - }, - "createdBy": { "$ref": "#/components/schemas/User" }, - "updatedAt": { - "type": "string", - "description": "The date and time that this object was last changed", - "readOnly": true, - "format": "date-time" + "$ref": "#/components/schemas/Group" + } + } + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/groups.list": { + "post": { + "tags": ["Groups"], + "summary": "List all groups", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Group" + } }, - "updatedBy": { "$ref": "#/components/schemas/User" } + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + } } - }, - "Document": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/groups.create": { + "post": { + "tags": ["Groups"], + "summary": "Create a group", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "collectionId": { - "type": "string", - "description": "Identifier for the associated collection.", - "format": "uuid" - }, - "parentDocumentId": { - "type": "string", - "description": "Identifier for the document this is a child of, if any.", - "format": "uuid" - }, - "title": { - "type": "string", - "description": "The title of the document.", - "example": "🎉 Welcome to Acme Inc" - }, - "fullWidth": { - "type": "boolean", - "description": "Whether this document should be displayed in a full-width view." - }, - "emoji": { - "type": "string", - "description": "An emoji associated with the document.", - "example": "🎉" - }, - "text": { - "type": "string", - "description": "The text content of the document, contains markdown formatting", - "example": "…" - }, - "urlId": { - "type": "string", - "description": "A short unique ID that can be used to identify the document as an alternative to the UUID", - "example": "hDYep1TPAM" - }, - "collaborators": { - "type": "array", - "items": { "$ref": "#/components/schemas/User" } - }, - "pinned": { - "type": "boolean", - "description": "Whether this document is pinned in the collection" - }, - "template": { - "type": "boolean", - "description": "Whether this document is a template" - }, - "templateId": { - "type": "string", - "description": "Unique identifier for the template this document was created from, if any", - "format": "uuid" - }, - "revision": { - "type": "number", - "description": "A number that is auto incrementing with every revision of the document that is saved", - "readOnly": true - }, - "createdAt": { - "type": "string", - "description": "The date and time that this object was created", - "readOnly": true, - "format": "date-time" - }, - "createdBy": { "$ref": "#/components/schemas/User" }, - "updatedAt": { - "type": "string", - "description": "The date and time that this object was last changed", - "readOnly": true, - "format": "date-time" - }, - "updatedBy": { "$ref": "#/components/schemas/User" }, - "publishedAt": { - "type": "string", - "nullable": true, - "description": "The date and time that this object was published", - "readOnly": true, - "format": "date-time" - }, - "archivedAt": { - "type": "string", - "description": "The date and time that this object was archived", - "readOnly": true, - "format": "date-time" + "name": { + "type": "string", + "example": "Designers" + } + }, + "required": ["name"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Group" }, - "deletedAt": { - "type": "string", - "nullable": true, - "description": "The date and time that this object was deleted", - "readOnly": true, - "format": "date-time" + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } } + } } - }, - "Event": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/groups.update": { + "post": { + "tags": ["Groups"], + "summary": "Update a group", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "name": { - "type": "string", - "example": "documents.create", - "readOnly": true - }, - "modelId": { - "type": "string", - "description": "Identifier for the object this event is associated with when it is not one of document, collection, or user.", - "format": "uuid", - "readOnly": true - }, - "actorId": { - "type": "string", - "description": "The user that performed the action.", - "format": "uuid", - "readOnly": true - }, - "actorIpAddress": { - "type": "string", - "description": "The ip address the action was performed from. This field is only returned when the `auditLog` boolean is true.", - "example": "60.169.88.100", - "readOnly": true + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string", + "example": "Designers" + } + }, + "required": ["id", "name"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Group" }, - "collectionId": { + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Policy" + } + } + } + } + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/groups.delete": { + "post": { + "tags": ["Groups"], + "summary": "Delete a group", + "description": "Deleting a group will cause all of its members to lose access to any collections the group has previously been added to. This action can’t be undone so please be careful.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true + } + } + } + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/groups.memberships": { + "post": { + "tags": ["Groups"], + "summary": "List all group members", + "description": "List and filter all the members in a group.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { + "type": "object", + "properties": { + "id": { "type": "string", - "format": "uuid", - "description": "Identifier for the associated collection, if any", - "readOnly": true - }, - "documentId": { + "description": "Group id", + "example": "a32c2ee6-fbde-4654-841b-0eabdc71b812" + }, + "query": { "type": "string", - "format": "uuid", - "description": "Identifier for the associated document, if any", - "readOnly": true - }, - "createdAt": { - "type": "string", - "description": "The date and time that this event was created", - "readOnly": true, - "format": "date-time" - }, + "description": "Filter memberships by user names", + "example": "jenny" + } + }, + "required": ["id"] + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { "data": { - "type": "object", - "example": { "name": "Equipment list" }, - "description": "Additional unstructured data associated with the event", - "readOnly": true - }, - "actor": { "$ref": "#/components/schemas/User" } + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "groupMemberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GroupMembership" + } + } + } + }, + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + } } - }, - "Error": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/groups.add_user": { + "post": { + "tags": ["Groups"], + "summary": "Add a group member", + "description": "This method allows you to add a user to the specified group.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "ok": { "type": "boolean", "example": false }, - "error": { "type": "string" } + "id": { + "type": "string", + "format": "uuid" + }, + "userId": { + "type": "string", + "format": "uuid" + } + }, + "required": ["id", "userId"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Group" + } + }, + "groupMemberships": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Membership" + } + } + } + } + } } - }, - "FileOperation": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/groups.remove_user": { + "post": { + "tags": ["Groups"], + "summary": "Remove a group member", + "description": "This method allows you to remove a user from the group.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "type": { - "type": "string", - "example": "export", - "description": "The type of file operation.", - "readOnly": true, - "enum": ["import", "export"] - }, - "state": { - "type": "string", - "description": "The state of the file operation.", - "example": "complete", - "readOnly": true, - "enum": [ - "creating", - "uploading", - "complete", - "error", - "expired" - ] - }, - "collection": { - "allOf": [ - { "nullable": true }, - { "$ref": "#/components/schemas/Collection" } - ] - }, - "user": { "$ref": "#/components/schemas/User" }, - "size": { - "type": "number", - "description": "The size of the resulting file in bytes", - "readOnly": true, - "example": 2048 - }, - "createdAt": { - "type": "string", - "description": "The date and time that this object was created", - "readOnly": true, - "format": "date-time" + "id": { + "type": "string", + "description": "Identifier for the collection", + "format": "uuid" + }, + "userId": { + "type": "string", + "format": "uuid" + } + }, + "required": ["id", "userId"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "groups": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Group" + } + } + } } + } } - }, - "Group": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/revisions.info": { + "post": { + "tags": ["Revisions"], + "summary": "Retrieve a revision", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "name": { - "type": "string", - "description": "The name of this group.", - "example": "Engineering" - }, - "memberCount": { - "type": "number", - "description": "The number of users that are members of the group", - "example": 11, - "readOnly": true - }, - "createdAt": { - "type": "string", - "description": "The date and time that this object was created", - "readOnly": true, - "format": "date-time" + "id": { + "type": "string", + "description": "Unique identifier for the revision.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Revision" + } + } + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/revisions.list": { + "post": { + "tags": ["Revisions"], + "summary": "List all revisions", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Revision" + } }, - "updatedAt": { - "type": "string", - "description": "The date and time that this object was last changed", - "readOnly": true, - "format": "date-time" + "pagination": { + "$ref": "#/components/schemas/Pagination" } + } } - }, - "Share": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/shares.info": { + "post": { + "tags": ["Shares"], + "summary": "Retrieve a share object", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "documentTitle": { - "type": "string", - "description": "Title of the shared document.", - "example": "React best practices", - "readOnly": true - }, - "documentUrl": { - "type": "string", - "format": "uri", - "description": "URL of the original document.", - "readOnly": true - }, - "url": { - "type": "string", - "format": "uri", - "description": "URL of the publicly shared document.", - "readOnly": true - }, - "published": { - "type": "boolean", - "example": false, - "description": "If true the share can be loaded without a user account." - }, - "includeChildDocuments": { - "type": "boolean", - "example": true, - "description": "If to also give permission to view documents nested beneath this one." - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "Date and time when this share was created", - "readOnly": true - }, - "createdBy": { "$ref": "#/components/schemas/User" }, - "updatedAt": { - "type": "string", - "format": "date-time", - "description": "Date and time when this share was edited", - "readOnly": true + "id": { + "type": "string", + "description": "Unique identifier for the share.", + "format": "uuid" + }, + "documentId": { + "type": "string", + "description": "Unique identifier for a document. One of id or documentId must be provided.", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Share" + } + } + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/shares.list": { + "post": { + "tags": ["Shares"], + "summary": "List all shares", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Share" + } }, - "lastAccessedAt": { - "type": "string", - "format": "date-time", - "description": "Date and time when this share was last viewed", - "readOnly": true + "pagination": { + "$ref": "#/components/schemas/Pagination" + } + } + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/shares.create": { + "post": { + "tags": ["Shares"], + "summary": "Create a share", + "description": "Creates a new share link that can be used by to access a document. If you request multiple shares for the same document with the same API key, the same share object will be returned. By default all shares are unpublished.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documentId": { + "type": "string", + "format": "uuid" + } + }, + "required": ["documentId"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Share" } + } } - }, - "Revision": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/shares.update": { + "post": { + "tags": ["Shares"], + "summary": "Update a share", + "description": "Allows changing an existing shares published status, which removes authentication and makes it available to anyone with the link.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "documentId": { - "type": "string", - "description": "Identifier for the associated document.", - "readOnly": true, - "format": "uuid" - }, - "title": { - "type": "string", - "description": "Title of the document.", - "readOnly": true - }, - "text": { - "type": "string", - "description": "Body of the document, may contain markdown formatting", - "readOnly": true - }, - "createdAt": { - "type": "string", - "format": "date-time", - "description": "Date and time when this revision was created", - "readOnly": true - }, - "createdBy": { "$ref": "#/components/schemas/User" } + "id": { + "type": "string", + "format": "uuid" + }, + "published": { "type": "boolean" } + }, + "required": ["id", "published"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Share" + } + } } - }, - "Team": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/shares.revoke": { + "post": { + "tags": ["Shares"], + "summary": "Revoke a share", + "description": "Makes the share link inactive so that it can no longer be used to access the document.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "name": { - "type": "string", - "description": "The name of this team, it is usually auto-generated when the first SSO connection is made but can be changed if neccessary." - }, - "avatarUrl": { - "type": "string", - "format": "uri", - "description": "The URL for the image associated with this team, it will be displayed in the team switcher and in the top left of the knowledge base along with the name." - }, - "sharing": { - "type": "boolean", - "description": "Whether this team has share links globally enabled. If this value is false then all sharing UI and APIs are disabled." - }, - "defaultCollectionId": { - "type": "string", - "description": "If set then the referenced collection is where users will be redirected to after signing in instead of the Home screen", - "format": "uuid" - }, - "defaultUserRole": { - "type": "string", - "description": "If set then this role will be used as the default for users that signup via SSO", - "enum": ["viewer", "member", "admin"] - }, - "memberCollectionCreate": { - "type": "boolean", - "description": "Whether members are allowed to create new collections. If false then only admins can create collections." - }, - "documentEmbeds": { - "type": "boolean", - "description": "Whether this team has embeds in documents globally enabled. It can be disabled to reduce potential data leakage to third parties." - }, - "collaborativeEditing": { - "type": "boolean", - "description": "Whether this team has collaborative editing in documents globally enabled." - }, - "inviteRequired": { - "type": "boolean", - "description": "Whether an invite is required to join this team, if false users may join with a linked SSO provider." - }, - "allowedDomains": { - "type": "array", - "items": { - "type": "string", - "description": "A hostname that user emails are restricted to" - } - }, - "guestSignin": { - "type": "boolean", - "description": "Whether this team has guest signin enabled. Guests can signin with an email address and are not required to have a Google Workspace/Slack SSO account once invited." - }, - "subdomain": { - "type": "string", - "description": "Represents the subdomain at which this team's knowledge base can be accessed." - }, - "url": { - "type": "string", - "description": "The fully qualified URL at which this team's knowledge base can be accessed.", - "readOnly": true, - "format": "uri" + "id": { "type": "string", "format": "uuid" } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } + } } - }, - "User": { + } + } + }, + "400": { "$ref": "#/components/responses/Validation" }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.invite": { + "post": { + "tags": ["Users"], + "summary": "Invite users", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true, - "format": "uuid" - }, - "name": { - "type": "string", - "description": "The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if neccessary.", - "example": "Jane Doe" - }, - "avatarUrl": { - "type": "string", - "format": "uri", - "description": "The URL for the image associated with this user, it will be displayed in the application UI and email notifications." - }, - "email": { - "type": "string", - "description": "The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if neccessary.", - "format": "email", - "readOnly": true - }, - "isAdmin": { - "type": "boolean", - "description": "Whether this user has admin permissions.", - "readOnly": true - }, - "isSuspended": { - "type": "boolean", - "description": "Whether this user has been suspended.", - "readOnly": true - }, - "lastActiveAt": { - "type": "string", - "description": "The last time this user made an API request, this value is updated at most every 5 minutes.", - "readOnly": true, - "format": "date-time" - }, - "createdAt": { - "type": "string", - "description": "The date and time that this user first signed in or was invited as a guest.", - "readOnly": true, - "format": "date-time" + "invites": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Invite" + } + } + }, + "required": ["invites"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "sent": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Invite" + } + }, + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } } + } } - }, - "Invite": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/users.info": { + "post": { + "tags": ["Users"], + "summary": "Retrieve a user", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "name": { + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" + } + } + } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.list": { + "post": { + "tags": ["Users"], + "summary": "List all users", + "description": "List and filter all the users in the team", + "requestBody": { + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/Pagination" + }, + { "$ref": "#/components/schemas/Sorting" }, + { + "type": "object", + "properties": { + "query": { "type": "string", - "description": "The full name of the user being invited" - }, - "email": { + "example": "jane" + }, + "emails": { + "type": "array", + "items": { + "type": "string", + "description": "Array of emails", + "example": [ + "jane.crandall@mail.com", + "prudence.crandall@mail.com" + ] + } + }, + "filter": { "type": "string", - "description": "The email address to invite" + "example": "all", + "enum": [ + "invited", + "viewers", + "admins", + "active", + "all", + "suspended" + ] + } + } + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } }, - "role": { - "type": "string", - "enum": ["member", "guest", "admin"] + "pagination": { + "$ref": "#/components/schemas/Pagination" } + } } - }, - "Membership": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/users.update": { + "post": { + "tags": ["Users"], + "summary": "Update a user", + "description": "Update a users name or avatar. No `id` is required as it is only possible to update the current user at this time.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true - }, - "userId": { - "type": "string", - "description": "Identifier for the associated user.", - "readOnly": true, - "format": "uuid" - }, - "collectionId": { - "type": "string", - "description": "Identifier for the associated collection.", - "readOnly": true, - "format": "uuid" - }, - "permission": { "$ref": "#/components/schemas/Permission" } + "name": { "type": "string" }, + "avatarUrl": { + "type": "string", + "format": "uri" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" + } + } } - }, - "Policy": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.promote": { + "post": { + "tags": ["Users"], + "summary": "Promote a user", + "description": "Promote a user to be a team admin. This endpoint is only available for admin users.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object this policy references.", - "format": "uuid", - "readOnly": true - }, - "abilities": { - "type": "object", - "properties": { - "create": { "type": "boolean" }, - "read": { "type": "boolean" }, - "update": { "type": "boolean" }, - "delete": { "type": "boolean" }, - "restore": { "type": "boolean" }, - "star": { "type": "boolean" }, - "unstar": { "type": "boolean" }, - "share": { "type": "boolean" }, - "download": { "type": "boolean" }, - "pin": { "type": "boolean" }, - "unpin": { "type": "boolean" }, - "move": { "type": "boolean" }, - "archive": { "type": "boolean" }, - "unarchive": { "type": "boolean" }, - "createChildDocument": { "type": "boolean" } - } + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" } + } } - }, - "GroupMembership": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.demote": { + "post": { + "tags": ["Users"], + "summary": "Demote a user", + "description": "Demote a team admin to regular user permissions. This endpoint is only available for admin users.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true - }, - "groupId": { - "type": "string", - "description": "Identifier for the associated group.", - "readOnly": true, - "format": "uuid" - }, - "userId": { - "type": "string", - "description": "Identifier for the associated user.", - "readOnly": true, - "format": "uuid" - }, - "user": { "$ref": "#/components/schemas/User" } + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + }, + "to": { + "type": "string", + "description": "Which role to demote to", + "enum": ["viewer", "member"] + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" + } + } } - }, - "CollectionGroupMembership": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.suspend": { + "post": { + "tags": ["Users"], + "summary": "Suspend a user", + "description": "Suspending a user prevents the user from signing in. Users that are suspended are also not counted against billing totals in the hosted version.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true - }, - "groupId": { - "type": "string", - "description": "Identifier for the associated group.", - "readOnly": true, - "format": "uuid" - }, - "collectionId": { - "type": "string", - "description": "Identifier for the associated collection.", - "readOnly": true, - "format": "uuid" - }, - "permission": { "$ref": "#/components/schemas/Permission" } + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" + } + } } - }, - "View": { + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.activate": { + "post": { + "tags": ["Users"], + "summary": "Activate a user", + "description": "Activating a previously suspended user allows them to signin again. Users that are activated will cause billing totals to be re-calculated in the hosted version.", + "requestBody": { + "content": { + "application/json": { + "schema": { "type": "object", "properties": { - "id": { - "type": "string", - "description": "Unique identifier for the object.", - "readOnly": true - }, - "documentId": { - "type": "string", - "description": "Identifier for the associated document.", - "readOnly": true, - "format": "uuid" - }, - "firstViewedAt": { - "type": "string", - "description": "When the document was first viewed by the user", - "readOnly": true, - "format": "date-time" - }, - "lastViewedAt": { - "type": "string", - "description": "When the document was last viewed by the user", - "readOnly": true, - "format": "date-time" - }, - "count": { - "type": "number", - "description": "The number of times the user has viewed the document.", - "example": 22, - "readOnly": true - }, - "user": { "$ref": "#/components/schemas/User" } - } + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + } + }, + "required": ["id"] + } } + } }, "responses": { - "NotFound": { - "description": "The specified resource was not found.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/Error" } + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/User" } + } } - }, - "Validation": { - "description": "The request failed one or more validations.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/users.delete": { + "post": { + "tags": ["Users"], + "summary": "Delete a user", + "description": "Deleting a user removes the object entirely. In almost every circumstance it is preferable to suspend a user, as a deleted user can be recreated by signing in with SSO again.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the user.", + "format": "uuid" + } + }, + "required": ["id"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true } + } } - }, - "Unauthorized": { - "description": "The current API key is not authorized to perform this action.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" }, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/views.list": { + "post": { + "tags": ["Views"], + "summary": "List all views", + "description": "List all users that have viewed a document and the overall view count.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documentId": { + "type": "string", + "format": "uuid" + } + }, + "required": ["documentId"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/View" + } } + } } - }, - "Unauthenticated": { - "description": "The API key is missing or otherwise invalid.", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + "/views.create": { + "post": { + "tags": ["Views"], + "summary": "Create a view", + "description": "Creates a new view for a document. This is documented in the interests of thoroughness however it is recommended that views are not created from outside of the Outline UI.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documentId": { + "type": "string", + "format": "uuid" + } + }, + "required": ["documentId"] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/View" } + } } + } } - }, - "securitySchemes": { - "http": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" + }, + "401": { "$ref": "#/components/responses/Unauthenticated" }, + "403": { "$ref": "#/components/responses/Unauthorized" } + } + } + } + }, + "components": { + "schemas": { + "Permission": { "type": "string", "enum": ["read", "read_write"] }, + "Attachment": { + "type": "object", + "properties": { + "contentType": { "type": "string", "example": "image/png" }, + "size": { "type": "number" }, + "name": { "type": "string" }, + "url": { "type": "string", "format": "uri" }, + "documentId": { + "type": "string", + "description": "Identifier for the associated document, if any.", + "format": "uuid" + } + } + }, + "Pagination": { + "type": "object", + "properties": { + "offset": { "type": "number" }, + "limit": { "type": "number", "example": 25 } + } + }, + "Sorting": { + "type": "object", + "properties": { + "sort": { "type": "string", "example": "updatedAt" }, + "direction": { + "type": "string", + "example": "DESC", + "enum": ["ASC", "DESC"] + } + } + }, + "NavigationNode": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the document.", + "format": "uuid" + }, + "title": { "type": "string" }, + "url": { "type": "string" }, + "children": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NavigationNode" + } + } + } + }, + "Auth": { + "type": "object", + "properties": { + "user": { "$ref": "#/components/schemas/User" }, + "team": { "$ref": "#/components/schemas/Team" } + } + }, + "Collection": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "name": { + "type": "string", + "description": "The name of the collection.", + "example": "Human Resources" + }, + "description": { + "type": "string", + "description": "A description of the collection, may contain markdown formatting", + "example": "" + }, + "sort": { + "type": "object", + "description": "The sort of documents in the collection. Note that not all API responses respect this and it is left as a frontend concern to implement.", + "properties": { + "field": { "type": "string" }, + "direction": { + "type": "string", + "enum": ["asc", "desc"] + } + } + }, + "index": { + "type": "string", + "description": "The position of the collection in the sidebar", + "example": "P" + }, + "color": { + "type": "string", + "description": "A color representing the collection, this is used to help make collections more identifiable in the UI. It should be in HEX format including the #", + "example": "#123123" + }, + "icon": { + "type": "string", + "description": "A string that represents an icon in the outline-icons package" + }, + "permission": { "$ref": "#/components/schemas/Permission" }, + "createdAt": { + "type": "string", + "description": "The date and time that this object was created", + "readOnly": true, + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "description": "The date and time that this object was last changed", + "readOnly": true, + "format": "date-time" + }, + "deletedAt": { + "type": "string", + "nullable": true, + "description": "The date and time that this object was deleted", + "readOnly": true, + "format": "date-time" + } + } + }, + "Comment": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "data": { + "type": "object", + "description": "The editor data representing this comment." + }, + "documentId": { + "type": "string", + "description": "Identifier for the document this is related to.", + "format": "uuid" + }, + "parentCommentId": { + "type": "string", + "description": "Identifier for the comment this is a child of, if any.", + "format": "uuid" + }, + "createdAt": { + "type": "string", + "description": "The date and time that this object was created", + "readOnly": true, + "format": "date-time" + }, + "createdBy": { "$ref": "#/components/schemas/User" }, + "updatedAt": { + "type": "string", + "description": "The date and time that this object was last changed", + "readOnly": true, + "format": "date-time" + }, + "updatedBy": { "$ref": "#/components/schemas/User" } + } + }, + "Document": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "collectionId": { + "type": "string", + "description": "Identifier for the associated collection.", + "format": "uuid" + }, + "parentDocumentId": { + "type": "string", + "description": "Identifier for the document this is a child of, if any.", + "format": "uuid" + }, + "title": { + "type": "string", + "description": "The title of the document.", + "example": "🎉 Welcome to Acme Inc" + }, + "fullWidth": { + "type": "boolean", + "description": "Whether this document should be displayed in a full-width view." + }, + "emoji": { + "type": "string", + "description": "An emoji associated with the document.", + "example": "🎉" + }, + "text": { + "type": "string", + "description": "The text content of the document, contains markdown formatting", + "example": "…" + }, + "urlId": { + "type": "string", + "description": "A short unique ID that can be used to identify the document as an alternative to the UUID", + "example": "hDYep1TPAM" + }, + "collaborators": { + "type": "array", + "items": { "$ref": "#/components/schemas/User" } + }, + "pinned": { + "type": "boolean", + "description": "Whether this document is pinned in the collection" + }, + "template": { + "type": "boolean", + "description": "Whether this document is a template" + }, + "templateId": { + "type": "string", + "description": "Unique identifier for the template this document was created from, if any", + "format": "uuid" + }, + "revision": { + "type": "number", + "description": "A number that is auto incrementing with every revision of the document that is saved", + "readOnly": true + }, + "createdAt": { + "type": "string", + "description": "The date and time that this object was created", + "readOnly": true, + "format": "date-time" + }, + "createdBy": { "$ref": "#/components/schemas/User" }, + "updatedAt": { + "type": "string", + "description": "The date and time that this object was last changed", + "readOnly": true, + "format": "date-time" + }, + "updatedBy": { "$ref": "#/components/schemas/User" }, + "publishedAt": { + "type": "string", + "nullable": true, + "description": "The date and time that this object was published", + "readOnly": true, + "format": "date-time" + }, + "archivedAt": { + "type": "string", + "description": "The date and time that this object was archived", + "readOnly": true, + "format": "date-time" + }, + "deletedAt": { + "type": "string", + "nullable": true, + "description": "The date and time that this object was deleted", + "readOnly": true, + "format": "date-time" + } + } + }, + "Event": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "name": { + "type": "string", + "example": "documents.create", + "readOnly": true + }, + "modelId": { + "type": "string", + "description": "Identifier for the object this event is associated with when it is not one of document, collection, or user.", + "format": "uuid", + "readOnly": true + }, + "actorId": { + "type": "string", + "description": "The user that performed the action.", + "format": "uuid", + "readOnly": true + }, + "actorIpAddress": { + "type": "string", + "description": "The ip address the action was performed from. This field is only returned when the `auditLog` boolean is true.", + "example": "60.169.88.100", + "readOnly": true + }, + "collectionId": { + "type": "string", + "format": "uuid", + "description": "Identifier for the associated collection, if any", + "readOnly": true + }, + "documentId": { + "type": "string", + "format": "uuid", + "description": "Identifier for the associated document, if any", + "readOnly": true + }, + "createdAt": { + "type": "string", + "description": "The date and time that this event was created", + "readOnly": true, + "format": "date-time" + }, + "data": { + "type": "object", + "example": { "name": "Equipment list" }, + "description": "Additional unstructured data associated with the event", + "readOnly": true + }, + "actor": { "$ref": "#/components/schemas/User" } + } + }, + "Error": { + "type": "object", + "properties": { + "ok": { "type": "boolean", "example": false }, + "error": { "type": "string" } + } + }, + "FileOperation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "type": { + "type": "string", + "example": "export", + "description": "The type of file operation.", + "readOnly": true, + "enum": ["import", "export"] + }, + "state": { + "type": "string", + "description": "The state of the file operation.", + "example": "complete", + "readOnly": true, + "enum": ["creating", "uploading", "complete", "error", "expired"] + }, + "collection": { + "allOf": [ + { "nullable": true }, + { "$ref": "#/components/schemas/Collection" } + ] + }, + "user": { "$ref": "#/components/schemas/User" }, + "size": { + "type": "number", + "description": "The size of the resulting file in bytes", + "readOnly": true, + "example": 2048 + }, + "createdAt": { + "type": "string", + "description": "The date and time that this object was created", + "readOnly": true, + "format": "date-time" + } + } + }, + "Group": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "name": { + "type": "string", + "description": "The name of this group.", + "example": "Engineering" + }, + "memberCount": { + "type": "number", + "description": "The number of users that are members of the group", + "example": 11, + "readOnly": true + }, + "createdAt": { + "type": "string", + "description": "The date and time that this object was created", + "readOnly": true, + "format": "date-time" + }, + "updatedAt": { + "type": "string", + "description": "The date and time that this object was last changed", + "readOnly": true, + "format": "date-time" + } + } + }, + "Share": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "documentTitle": { + "type": "string", + "description": "Title of the shared document.", + "example": "React best practices", + "readOnly": true + }, + "documentUrl": { + "type": "string", + "format": "uri", + "description": "URL of the original document.", + "readOnly": true + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL of the publicly shared document.", + "readOnly": true + }, + "published": { + "type": "boolean", + "example": false, + "description": "If true the share can be loaded without a user account." + }, + "includeChildDocuments": { + "type": "boolean", + "example": true, + "description": "If to also give permission to view documents nested beneath this one." + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Date and time when this share was created", + "readOnly": true + }, + "createdBy": { "$ref": "#/components/schemas/User" }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "Date and time when this share was edited", + "readOnly": true + }, + "lastAccessedAt": { + "type": "string", + "format": "date-time", + "description": "Date and time when this share was last viewed", + "readOnly": true + } + } + }, + "Revision": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "documentId": { + "type": "string", + "description": "Identifier for the associated document.", + "readOnly": true, + "format": "uuid" + }, + "title": { + "type": "string", + "description": "Title of the document.", + "readOnly": true + }, + "text": { + "type": "string", + "description": "Body of the document, may contain markdown formatting", + "readOnly": true + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Date and time when this revision was created", + "readOnly": true + }, + "createdBy": { "$ref": "#/components/schemas/User" } + } + }, + "Team": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "name": { + "type": "string", + "description": "The name of this team, it is usually auto-generated when the first SSO connection is made but can be changed if neccessary." + }, + "avatarUrl": { + "type": "string", + "format": "uri", + "description": "The URL for the image associated with this team, it will be displayed in the team switcher and in the top left of the knowledge base along with the name." + }, + "sharing": { + "type": "boolean", + "description": "Whether this team has share links globally enabled. If this value is false then all sharing UI and APIs are disabled." + }, + "defaultCollectionId": { + "type": "string", + "description": "If set then the referenced collection is where users will be redirected to after signing in instead of the Home screen", + "format": "uuid" + }, + "defaultUserRole": { + "type": "string", + "description": "If set then this role will be used as the default for users that signup via SSO", + "enum": ["viewer", "member", "admin"] + }, + "memberCollectionCreate": { + "type": "boolean", + "description": "Whether members are allowed to create new collections. If false then only admins can create collections." + }, + "documentEmbeds": { + "type": "boolean", + "description": "Whether this team has embeds in documents globally enabled. It can be disabled to reduce potential data leakage to third parties." + }, + "collaborativeEditing": { + "type": "boolean", + "description": "Whether this team has collaborative editing in documents globally enabled." + }, + "inviteRequired": { + "type": "boolean", + "description": "Whether an invite is required to join this team, if false users may join with a linked SSO provider." + }, + "allowedDomains": { + "type": "array", + "items": { + "type": "string", + "description": "A hostname that user emails are restricted to" + } + }, + "guestSignin": { + "type": "boolean", + "description": "Whether this team has guest signin enabled. Guests can signin with an email address and are not required to have a Google Workspace/Slack SSO account once invited." + }, + "subdomain": { + "type": "string", + "description": "Represents the subdomain at which this team's knowledge base can be accessed." + }, + "url": { + "type": "string", + "description": "The fully qualified URL at which this team's knowledge base can be accessed.", + "readOnly": true, + "format": "uri" + } + } + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true, + "format": "uuid" + }, + "name": { + "type": "string", + "description": "The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if neccessary.", + "example": "Jane Doe" + }, + "avatarUrl": { + "type": "string", + "format": "uri", + "description": "The URL for the image associated with this user, it will be displayed in the application UI and email notifications." + }, + "email": { + "type": "string", + "description": "The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if neccessary.", + "format": "email", + "readOnly": true + }, + "isAdmin": { + "type": "boolean", + "description": "Whether this user has admin permissions.", + "readOnly": true + }, + "isSuspended": { + "type": "boolean", + "description": "Whether this user has been suspended.", + "readOnly": true + }, + "lastActiveAt": { + "type": "string", + "description": "The last time this user made an API request, this value is updated at most every 5 minutes.", + "readOnly": true, + "format": "date-time" + }, + "createdAt": { + "type": "string", + "description": "The date and time that this user first signed in or was invited as a guest.", + "readOnly": true, + "format": "date-time" + } + } + }, + "Invite": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The full name of the user being invited" + }, + "email": { + "type": "string", + "description": "The email address to invite" + }, + "role": { + "type": "string", + "enum": ["member", "guest", "admin"] + } + } + }, + "Membership": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true + }, + "userId": { + "type": "string", + "description": "Identifier for the associated user.", + "readOnly": true, + "format": "uuid" + }, + "collectionId": { + "type": "string", + "description": "Identifier for the associated collection.", + "readOnly": true, + "format": "uuid" + }, + "permission": { "$ref": "#/components/schemas/Permission" } + } + }, + "Policy": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object this policy references.", + "format": "uuid", + "readOnly": true + }, + "abilities": { + "type": "object", + "properties": { + "create": { "type": "boolean" }, + "read": { "type": "boolean" }, + "update": { "type": "boolean" }, + "delete": { "type": "boolean" }, + "restore": { "type": "boolean" }, + "star": { "type": "boolean" }, + "unstar": { "type": "boolean" }, + "share": { "type": "boolean" }, + "download": { "type": "boolean" }, + "pin": { "type": "boolean" }, + "unpin": { "type": "boolean" }, + "move": { "type": "boolean" }, + "archive": { "type": "boolean" }, + "unarchive": { "type": "boolean" }, + "createChildDocument": { "type": "boolean" } } + } + } + }, + "GroupMembership": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true + }, + "groupId": { + "type": "string", + "description": "Identifier for the associated group.", + "readOnly": true, + "format": "uuid" + }, + "userId": { + "type": "string", + "description": "Identifier for the associated user.", + "readOnly": true, + "format": "uuid" + }, + "user": { "$ref": "#/components/schemas/User" } } + }, + "CollectionGroupMembership": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true + }, + "groupId": { + "type": "string", + "description": "Identifier for the associated group.", + "readOnly": true, + "format": "uuid" + }, + "collectionId": { + "type": "string", + "description": "Identifier for the associated collection.", + "readOnly": true, + "format": "uuid" + }, + "permission": { "$ref": "#/components/schemas/Permission" } + } + }, + "View": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the object.", + "readOnly": true + }, + "documentId": { + "type": "string", + "description": "Identifier for the associated document.", + "readOnly": true, + "format": "uuid" + }, + "firstViewedAt": { + "type": "string", + "description": "When the document was first viewed by the user", + "readOnly": true, + "format": "date-time" + }, + "lastViewedAt": { + "type": "string", + "description": "When the document was last viewed by the user", + "readOnly": true, + "format": "date-time" + }, + "count": { + "type": "number", + "description": "The number of times the user has viewed the document.", + "example": 22, + "readOnly": true + }, + "user": { "$ref": "#/components/schemas/User" } + } + } + }, + "responses": { + "NotFound": { + "description": "The specified resource was not found.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "Validation": { + "description": "The request failed one or more validations.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "Unauthorized": { + "description": "The current API key is not authorized to perform this action.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + }, + "Unauthenticated": { + "description": "The API key is missing or otherwise invalid.", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/Error" } + } + } + } + }, + "securitySchemes": { + "http": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } } + } } diff --git a/packages/cli/src/commands/format/FormatCommand.ts b/packages/cli/src/commands/format/FormatCommand.ts new file mode 100644 index 00000000..67b4c52c --- /dev/null +++ b/packages/cli/src/commands/format/FormatCommand.ts @@ -0,0 +1,46 @@ +import fs from 'node:fs' +import { Command } from 'commander' +import kleur from 'kleur' +import { format } from 'prettier' +import { readFile, useGivenFileOrConfiguration } from '../../utils' + +export function FormatCommand() { + const cmd = new Command('format') + + cmd.description('Format an OpenAPI file') + cmd.argument('[file]', 'file to format') + cmd.action(async (fileArgument: string) => { + const startTime = performance.now() + + const file = useGivenFileOrConfiguration(fileArgument) + + const fileContent = readFile(file) + + if (!fileContent) { + console.error(kleur.red('Couldn’t read file.')) + process.exit(1) + } + + const newContent = await format(fileContent, { + semi: false, + parser: 'json', + }) + + // Replace file content with newContent + fs.writeFileSync(file, newContent, 'utf8') + + const endTime = performance.now() + + console.log( + kleur.green('File formatted'), + kleur.grey( + `in ${kleur.white( + `${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`, + )}`, + ), + ) + console.log() + }) + + return cmd +} diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts new file mode 100644 index 00000000..85e19026 --- /dev/null +++ b/packages/cli/src/commands/index.ts @@ -0,0 +1,6 @@ +export * from './format/FormatCommand' +export * from './init/InitCommand' +export * from './mock/MockCommand' +export * from './reference/ReferenceCommand' +export * from './share/ShareCommand' +export * from './validate/ValidateCommand' diff --git a/packages/cli/src/commands/init/InitCommand.ts b/packages/cli/src/commands/init/InitCommand.ts new file mode 100644 index 00000000..eda40e87 --- /dev/null +++ b/packages/cli/src/commands/init/InitCommand.ts @@ -0,0 +1,83 @@ +import fs from 'node:fs' +import { Command } from 'commander' +import kleur from 'kleur' +import prompts from 'prompts' +import toml from 'toml-js' + +export function InitCommand() { + const cmd = new Command('init') + + cmd.description('Create a new `scalar.toml` file') + cmd.option('-f, --file [file]', 'your OpenAPI file') + cmd.action(async ({ file }) => { + // Check if `scalar.toml` already exists + if (fs.existsSync('scalar.toml')) { + console.warn(kleur.yellow('A `scalar.toml` file already exists.')) + console.log() + + const { overwrite } = await prompts({ + type: 'toggle', + name: 'overwrite', + message: 'Do you want to override the file?', + initial: false, + active: 'yes', + inactive: 'no', + }) + + if (overwrite === false) { + console.log() + process.exit(1) + } + } + + // Ask for the OpenAPI file + const configuration = { + reference: { file: '' }, + } + + const { input } = file + ? { + input: file, + } + : await prompts({ + type: 'text', + name: 'input', + message: 'Where is your OpenAPI file?', + initial: './openapi.json', + validate: (input: string) => { + return fs.existsSync(input) ? true : 'File doesn’t exist.' + }, + }) + + configuration.reference.file = input + + const content = toml.dump(configuration) + + console.log() + console.log(kleur.bold().white(' scalar.toml')) + console.log() + console.log( + content + .trim() + .split('\n') + .map((line) => kleur.grey(` ${line}`)) + .join('\n'), + ) + console.log() + + // Create `scalar.toml` file + fs.writeFileSync('scalar.toml', content) + + console.log(kleur.green('Created a new project configuration.')) + console.log( + kleur.white( + `Run ${kleur + .grey() + .bold('scalar --help')} to see all available commands.`, + ), + ) + console.log() + }) + + return cmd +} diff --git a/packages/cli/src/commands/mock/MockCommand.ts b/packages/cli/src/commands/mock/MockCommand.ts new file mode 100644 index 00000000..28f6d848 --- /dev/null +++ b/packages/cli/src/commands/mock/MockCommand.ts @@ -0,0 +1,134 @@ +import fs from 'node:fs' +import { serve } from '@hono/node-server' +import { getExampleFromSchema } from '@scalar/api-reference' +import { Hono } from 'hono' +import type { OpenAPI } from 'openapi-types' +import { Command } from 'commander' +import kleur from 'kleur' +import { + getMethodColor, + getOperationByMethodAndPath, + loadOpenApiFile, + useGivenFileOrConfiguration, +} from '../../utils' + +export function MockCommand() { + const cmd = new Command('mock') + + cmd.description('Mock an API from an OpenAPI file') + cmd.argument('[file]', 'OpenAPI file to mock the server for') + cmd.option('-w, --watch', 'watch the file for changes') + cmd.option('-p, --port ', 'set the HTTP port for the mock server') + cmd.action( + async ( + fileArgument: string, + { watch, port }: { watch?: boolean; port?: number }, + ) => { + const file = useGivenFileOrConfiguration(fileArgument) + + let schema = (await loadOpenApiFile(file)) + .specification as OpenAPI.Document + + // watch file for changes + if (watch) { + fs.watchFile(file, async () => { + console.log( + kleur.bold().white('[INFO]'), + kleur.grey('Mock Server was updated.'), + ) + schema = ( + await loadOpenApiFile(file) + ).resolveRefs() as OpenAPI.Document + }) + } + + console.log(kleur.bold().white('Available Paths')) + console.log() + + if ( + schema?.paths === undefined || + Object.keys(schema?.paths).length === 0 + ) { + console.log( + kleur.bold().yellow('[WARN]'), + kleur.grey('Couldn’t find any paths in the OpenAPI file.'), + ) + } + + // loop through all paths + for (const path in schema?.paths ?? []) { + // loop through all methods + for (const method in schema.paths?.[path]) { + console.log( + `${kleur + .bold() + [getMethodColor(method)]( + method.toUpperCase().padEnd(6), + )} ${kleur.grey(`${path}`)}`, + ) + } + } + + console.log() + + const app = new Hono() + + app.all('/*', (c) => { + const { method, path } = c.req + + const operation = getOperationByMethodAndPath(schema, method, path) + + console.log( + `${kleur + .bold() + [getMethodColor(method)]( + method.toUpperCase().padEnd(6), + )} ${kleur.grey(`${path}`)}`, + `${kleur.grey('→')} ${ + operation?.operationId + ? kleur.white(operation.operationId) + : kleur.red('[ERROR] 404 Not Found') + }`, + ) + + if (!operation) { + return c.text('Not found', 404) + } + + // if (!operation) { + // return c.text('Method not allowed', 405) + // } + + const jsonResponseConfiguration = + operation.responses['200'].content['application/json'] + + const response = jsonResponseConfiguration.example + ? jsonResponseConfiguration.example + : jsonResponseConfiguration.schema + ? getExampleFromSchema(jsonResponseConfiguration.schema, { + emptyString: '…', + }) + : null + + return c.json(response) + }) + + serve( + { + fetch: app.fetch, + port: port ?? 3000, + }, + (info) => { + console.log( + `${kleur.bold().green('➜ Mock Server')} ${kleur.white( + 'listening on', + )} ${kleur.cyan(`http://localhost:${info.port}`)}`, + ) + console.log() + }, + ) + }, + ) + + return cmd +} diff --git a/packages/cli/src/commands/reference/ReferenceCommand.ts b/packages/cli/src/commands/reference/ReferenceCommand.ts new file mode 100644 index 00000000..955f9cf8 --- /dev/null +++ b/packages/cli/src/commands/reference/ReferenceCommand.ts @@ -0,0 +1,99 @@ +import fs from 'node:fs' +import { serve } from '@hono/node-server' +import { Command } from 'commander' +import { Hono } from 'hono' +import { stream } from 'hono/streaming' +import kleur from 'kleur' +import type { OpenAPI } from 'openapi-types' +import { + getHtmlDocument, + loadOpenApiFile, + useGivenFileOrConfiguration, +} from '../../utils' + +export function ReferenceCommand() { + const cmd = new Command('reference') + + cmd.description('Serve an API Reference from an OpenAPI file') + cmd.argument('[file]', 'OpenAPI file to show the reference for') + cmd.option('-w, --watch', 'watch the file for changes') + cmd.option( + '-p, --port ', + 'set the HTTP port for the API reference server', + ) + cmd.action( + async ( + fileArgument: string, + { watch, port }: { watch?: boolean; port?: number }, + ) => { + const file = useGivenFileOrConfiguration(fileArgument) + + let specification = (await loadOpenApiFile(file)) + .specification as OpenAPI.Document + + if ( + specification?.paths === undefined || + Object.keys(specification?.paths).length === 0 + ) { + console.log( + kleur.bold().yellow('[WARN]'), + kleur.grey('Couldn’t find any paths in the OpenAPI file.'), + ) + } + + const app = new Hono() + + app.get('/', (c) => { + return c.html(getHtmlDocument(specification, watch)) + }) + + app.use('/__watcher', async (c, next) => { + c.header('Content-Type', 'text/event-stream') + c.header('Cache-Control', 'no-cache') + c.header('Connection', 'keep-alive') + await next() + }) + + app.get('/__watcher', (c) => { + return stream(c, async (stream) => { + // watch file for changes + if (watch) { + console.log(`Watch ${file}`) + fs.watchFile(file, async () => { + console.log( + kleur.bold().white('[INFO]'), + kleur.grey('OpenAPI file modified'), + ) + + specification = (await loadOpenApiFile(file)) + .specification as OpenAPI.Document + + stream.write('data: file modified\n\n') + }) + } + + while (true) { + await new Promise((resolve) => setTimeout(resolve, 100)) + } + }) + }) + + serve( + { + fetch: app.fetch, + port: port ?? 3000, + }, + (info) => { + console.log( + `${kleur.bold().green('➜ API Reference Server')} ${kleur.white( + 'listening on', + )} ${kleur.cyan(`http://localhost:${info.port}`)}`, + ) + console.log() + }, + ) + }, + ) + + return cmd +} diff --git a/packages/cli/src/commands/share/ShareCommand.ts b/packages/cli/src/commands/share/ShareCommand.ts new file mode 100644 index 00000000..3ec03a23 --- /dev/null +++ b/packages/cli/src/commands/share/ShareCommand.ts @@ -0,0 +1,69 @@ +import { Command } from 'commander' +import kleur from 'kleur' +import { readFile, useGivenFileOrConfiguration } from '../../utils' + +export function ShareCommand() { + const cmd = new Command('share') + + cmd.description('Share an OpenAPI file') + cmd.argument('[file]', 'file to share') + cmd.action(async (fileArgument: string) => { + const file = useGivenFileOrConfiguration(fileArgument) + + fetch('https://sandbox.scalar.com/api/share', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + content: readFile(file), + }), + }) + .then((response) => response.json()) + .then((data) => { + const { id } = data + + console.log(kleur.bold().green('Your OpenAPI file is public.')) + console.log() + console.log( + `${kleur.green('➜')} ${kleur + .bold() + .white('API Reference:'.padEnd(14))} ${kleur.cyan( + `https://sandbox.scalar.com/p/${id}`, + )}`, + ) + console.log( + `${kleur.grey('➜')} ${kleur + .bold() + .grey('Editor:'.padEnd(14))} ${kleur.cyan( + `https://sandbox.scalar.com/e/${id}`, + )}`, + ) + console.log() + console.log( + `${kleur.grey('➜')} ${kleur + .bold() + .grey('OpenAPI JSON:'.padEnd(14))} ${kleur.cyan( + `https://sandbox.scalar.com/files/${id}/openapi.json`, + )}`, + ) + console.log( + `${kleur.grey('➜')} ${kleur + .bold() + .grey('OpenAPI YAML:'.padEnd(14))} ${kleur.cyan( + `https://sandbox.scalar.com/files/${id}/openapi.yaml`, + )}`, + ) + console.log() + }) + .catch((error) => { + console.error('Failed to share the file.') + console.log() + console.error('Error:', error) + console.log() + process.exit(1) + }) + }) + + return cmd +} diff --git a/packages/cli/src/commands/validate/ValidateCommand.ts b/packages/cli/src/commands/validate/ValidateCommand.ts new file mode 100644 index 00000000..f2c6baff --- /dev/null +++ b/packages/cli/src/commands/validate/ValidateCommand.ts @@ -0,0 +1,61 @@ +import { Validator } from '@seriousme/openapi-schema-validator' +import prettyjson from 'prettyjson' +import { Command } from 'commander' +import kleur from 'kleur' +import { useGivenFileOrConfiguration } from '../../utils' + +export function ValidateCommand() { + const cmd = new Command('validate') + + cmd.description('Validate an OpenAPI file') + cmd.argument('[file]', 'file to validate') + cmd.action(async (fileArgument: string) => { + const startTime = performance.now() + + const file = useGivenFileOrConfiguration(fileArgument) + + const validator = new Validator() + const result = await validator.validate(file) + if (result.valid) { + console.log( + kleur.green( + `Matches the OpenAPI specification${kleur.white( + ` (OpenAPI ${kleur.bold(validator.version)})`, + )}`, + ), + ) + + const endTime = performance.now() + + console.log() + console.log( + kleur.green('File validated'), + kleur.grey( + `in ${kleur.white( + `${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`, + )}`, + ), + ) + console.log() + } else { + console.log(prettyjson.render(result.errors)) + console.log() + console.error(kleur.red('File doesn’t match the OpenAPI specification.')) + console.log() + console.error( + kleur.red( + `${kleur.bold( + `${result.errors?.length} error${ + result.errors && result.errors.length > 1 ? 's' : '' + }`, + )} found.`, + ), + ) + console.log() + + process.exit(1) + } + }) + + return cmd +} diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 79a0631d..374fc590 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -1,27 +1,15 @@ #!/usr/bin/env node -import fs from 'node:fs' -import { serve } from '@hono/node-server' -import { getExampleFromSchema } from '@scalar/api-reference' -import { Validator } from '@seriousme/openapi-schema-validator' import { Command } from 'commander' -import { Hono } from 'hono' -import { stream } from 'hono/streaming' -import kleur from 'kleur' -import type { OpenAPI } from 'openapi-types' -import { format } from 'prettier' -import prettyjson from 'prettyjson' -import prompts from 'prompts' -import toml from 'toml-js' import { version } from '../package.json' import { - getHtmlDocument, - getMethodColor, - getOperationByMethodAndPath, - loadOpenApiFile, - readFile, - useGivenFileOrConfiguration, -} from './utils' + FormatCommand, + InitCommand, + MockCommand, + ReferenceCommand, + ShareCommand, + ValidateCommand, +} from './commands' const program = new Command() @@ -30,429 +18,13 @@ program .description('CLI to work with your OpenAPI files') .version(version) -program - .command('init', { - isDefault: true, - }) - .description('Create a new `scalar.toml` file') - .option('-f, --file [file]', 'your OpenAPI file') - .action(async ({ file }) => { - // Check if `scalar.toml` already exists - if (fs.existsSync('scalar.toml')) { - console.warn(kleur.yellow('A `scalar.toml` file already exists.')) - console.log() - - const { overwrite } = await prompts({ - type: 'toggle', - name: 'overwrite', - message: 'Do you want to override the file?', - initial: false, - active: 'yes', - inactive: 'no', - }) - - if (overwrite === false) { - console.log() - process.exit(1) - } - } - - // Ask for the OpenAPI file - const configuration = { - reference: { file: '' }, - } - - const { input } = file - ? { - input: file, - } - : await prompts({ - type: 'text', - name: 'input', - message: 'Where is your OpenAPI file?', - initial: './openapi.json', - validate: (input: string) => { - return fs.existsSync(input) ? true : 'File doesn’t exist.' - }, - }) - - configuration.reference.file = input - - const content = toml.dump(configuration) - - console.log() - console.log(kleur.bold().white(' scalar.toml')) - console.log() - console.log( - content - .trim() - .split('\n') - .map((line) => kleur.grey(` ${line}`)) - .join('\n'), - ) - console.log() - - // Create `scalar.toml` file - fs.writeFileSync('scalar.toml', content) - - console.log(kleur.green('Created a new project configuration.')) - console.log( - kleur.white( - `Run ${kleur - .grey() - .bold('scalar --help')} to see all available commands.`, - ), - ) - console.log() - }) - -program - .command('format') - .description('Format an OpenAPI file') - .argument('[file]', 'file to format') - .action(async (fileArgument: string) => { - const startTime = performance.now() - - const file = useGivenFileOrConfiguration(fileArgument) - - const fileContent = readFile(file) - - if (!fileContent) { - console.error(kleur.red('Couldn’t read file.')) - process.exit(1) - } - - const newContent = await format(fileContent, { - semi: false, - parser: 'json', - }) - - // Replace file content with newContent - fs.writeFileSync(file, newContent, 'utf8') - - const endTime = performance.now() - - console.log( - kleur.green('File formatted'), - kleur.grey( - `in ${kleur.white( - `${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`, - )}`, - ), - ) - console.log() - }) - -program - .command('validate') - .description('Validate an OpenAPI file') - .argument('[file]', 'file to validate') - .action(async (fileArgument: string) => { - const startTime = performance.now() - - const file = useGivenFileOrConfiguration(fileArgument) - - const validator = new Validator() - const result = await validator.validate(file) - if (result.valid) { - console.log( - kleur.green( - `Matches the OpenAPI specification${kleur.white( - ` (OpenAPI ${kleur.bold(validator.version)})`, - )}`, - ), - ) - - const endTime = performance.now() - - console.log() - console.log( - kleur.green('File validated'), - kleur.grey( - `in ${kleur.white( - `${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`, - )}`, - ), - ) - console.log() - } else { - console.log(prettyjson.render(result.errors)) - console.log() - console.error(kleur.red('File doesn’t match the OpenAPI specification.')) - console.log() - console.error( - kleur.red( - `${kleur.bold( - `${result.errors?.length} error${ - result.errors && result.errors.length > 1 ? 's' : '' - }`, - )} found.`, - ), - ) - console.log() - - process.exit(1) - } - }) - -program - .command('share') - .description('Share an OpenAPI file') - .argument('[file]', 'file to share') - .action(async (fileArgument: string) => { - const file = useGivenFileOrConfiguration(fileArgument) - - fetch('https://sandbox.scalar.com/api/share', { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - }, - body: JSON.stringify({ - content: readFile(file), - }), - }) - .then((response) => response.json()) - .then((data) => { - const { id } = data - - console.log(kleur.bold().green('Your OpenAPI file is public.')) - console.log() - console.log( - `${kleur.green('➜')} ${kleur - .bold() - .white('API Reference:'.padEnd(14))} ${kleur.cyan( - `https://sandbox.scalar.com/p/${id}`, - )}`, - ) - console.log( - `${kleur.grey('➜')} ${kleur - .bold() - .grey('Editor:'.padEnd(14))} ${kleur.cyan( - `https://sandbox.scalar.com/e/${id}`, - )}`, - ) - console.log() - console.log( - `${kleur.grey('➜')} ${kleur - .bold() - .grey('OpenAPI JSON:'.padEnd(14))} ${kleur.cyan( - `https://sandbox.scalar.com/files/${id}/openapi.json`, - )}`, - ) - console.log( - `${kleur.grey('➜')} ${kleur - .bold() - .grey('OpenAPI YAML:'.padEnd(14))} ${kleur.cyan( - `https://sandbox.scalar.com/files/${id}/openapi.yaml`, - )}`, - ) - console.log() - }) - .catch((error) => { - console.error('Failed to share the file.') - console.log() - console.error('Error:', error) - console.log() - process.exit(1) - }) - }) - -program - .command('mock') - .description('Mock an API from an OpenAPI file') - .argument('[file]', 'OpenAPI file to mock the server for') - .option('-w, --watch', 'watch the file for changes') - .option('-p, --port ', 'set the HTTP port for the mock server') - .action( - async ( - fileArgument: string, - { watch, port }: { watch?: boolean; port?: number }, - ) => { - const file = useGivenFileOrConfiguration(fileArgument) - - let schema = ( - await loadOpenApiFile(file) - ).resolveRefs() as OpenAPI.Document - - // watch file for changes - if (watch) { - fs.watchFile(file, async () => { - console.log( - kleur.bold().white('[INFO]'), - kleur.grey('Mock Server was updated.'), - ) - schema = ( - await loadOpenApiFile(file) - ).resolveRefs() as OpenAPI.Document - }) - } - - console.log(kleur.bold().white('Available Paths')) - console.log() - - if ( - schema?.paths === undefined || - Object.keys(schema?.paths).length === 0 - ) { - console.log( - kleur.bold().yellow('[WARN]'), - kleur.grey('Couldn’t find any paths in the OpenAPI file.'), - ) - } - - // loop through all paths - for (const path in schema?.paths ?? []) { - // loop through all methods - for (const method in schema.paths?.[path]) { - console.log( - `${kleur - .bold() - [getMethodColor(method)]( - method.toUpperCase().padEnd(6), - )} ${kleur.grey(`${path}`)}`, - ) - } - } - - console.log() - - const app = new Hono() - - app.all('/*', (c) => { - const { method, path } = c.req - - const operation = getOperationByMethodAndPath(schema, method, path) - - console.log( - `${kleur - .bold() - [getMethodColor(method)]( - method.toUpperCase().padEnd(6), - )} ${kleur.grey(`${path}`)}`, - `${kleur.grey('→')} ${ - operation?.operationId - ? kleur.white(operation.operationId) - : kleur.red('[ERROR] 404 Not Found') - }`, - ) - - if (!operation) { - return c.text('Not found', 404) - } - - // if (!operation) { - // return c.text('Method not allowed', 405) - // } - - const jsonResponseConfiguration = - operation.responses['200'].content['application/json'] - - const response = jsonResponseConfiguration.example - ? jsonResponseConfiguration.example - : jsonResponseConfiguration.schema - ? getExampleFromSchema(jsonResponseConfiguration.schema, { - emptyString: '…', - }) - : null - - return c.json(response) - }) - - serve( - { - fetch: app.fetch, - port: port ?? 3000, - }, - (info) => { - console.log( - `${kleur.bold().green('➜ Mock Server')} ${kleur.white( - 'listening on', - )} ${kleur.cyan(`http://localhost:${info.port}`)}`, - ) - console.log() - }, - ) - }, - ) - -program - .command('reference') - .description('Serve an API Reference from an OpenAPI file') - .argument('[file]', 'OpenAPI file to show the reference for') - .option('-w, --watch', 'watch the file for changes') - .option('-p, --port ', 'set the HTTP port for the API reference server') - .action( - async ( - fileArgument: string, - { watch, port }: { watch?: boolean; port?: number }, - ) => { - const file = useGivenFileOrConfiguration(fileArgument) - - let specification = (await loadOpenApiFile(file)) - .specification as OpenAPI.Document - - if ( - specification?.paths === undefined || - Object.keys(specification?.paths).length === 0 - ) { - console.log( - kleur.bold().yellow('[WARN]'), - kleur.grey('Couldn’t find any paths in the OpenAPI file.'), - ) - } - - const app = new Hono() - - app.get('/', (c) => { - return c.html(getHtmlDocument(specification, watch)) - }) - - app.use('/__watcher', async (c, next) => { - c.header('Content-Type', 'text/event-stream') - c.header('Cache-Control', 'no-cache') - c.header('Connection', 'keep-alive') - await next() - }) - - app.get('/__watcher', (c) => { - return stream(c, async (stream) => { - // watch file for changes - if (watch) { - console.log(`Watch ${file}`) - fs.watchFile(file, async () => { - console.log( - kleur.bold().white('[INFO]'), - kleur.grey('OpenAPI file modified'), - ) - - specification = (await loadOpenApiFile(file)) - .specification as OpenAPI.Document - - stream.write('data: file modified\n\n') - }) - } - - while (true) { - await new Promise((resolve) => setTimeout(resolve, 100)) - } - }) - }) - - serve( - { - fetch: app.fetch, - port: port ?? 3000, - }, - (info) => { - console.log( - `${kleur.bold().green('➜ API Reference Server')} ${kleur.white( - 'listening on', - )} ${kleur.cyan(`http://localhost:${info.port}`)}`, - ) - console.log() - }, - ) - }, - ) +program.addCommand(InitCommand(), { + isDefault: true, +}) +program.addCommand(FormatCommand()) +program.addCommand(ValidateCommand()) +program.addCommand(ReferenceCommand()) +program.addCommand(MockCommand()) +program.addCommand(ShareCommand()) program.parse()