{ "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 `POST` method on `https://app.getoutline.com/api/:method`. Only HTTPS is\nsupported 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\n## API key\n\nYou can create new API keys under **Settings => API & Apps**. Be\ncareful when handling your keys as they allow full access to your data,\nyou should treat them like passwords and they should never be committed to\nsource control.\n\n### Usage\n\nTo authenticate with API, you should supply the API key as a \"Bearer\" token in the `Authorization` header\n(`Authorization: Bearer YOUR_API_KEY`).\n\nAPI keys can be revoked at any time by the creating user or an administrator of the workspace. If an API\nkey is revoked, any requests made with that key will return a `401 Unauthenticated` response.\n\n### Format\n\nAll API keys always begin with `ol_api_` followed by a random string of 38 letters and numbers.\n\n## OAuth 2.0\n\nOAuth 2.0 is a widely used protocol for authorization and authentication. It allows users\nto grant third-party _or_ internal applications access to their resources without sharing\ntheir credentials. To use OAuth 2.0 you need to follow these steps:\n\n1. Register your application under **Settings => Applications**\n2. Obtain an access token by exchanging the client credentials for an access token\n3. Use the access token to authenticate requests to the API\n\nSome API endpoints allow unauthenticated requests for public resources and\nthey can be called without authentication.\n\n# Scopes\n\nScopes are used to limit the access of an API key or application to specific resources. For example,\nan application may only need access to read documents, but not write them. Scopes can be global in\nthe case of `read` and `write` scopes, scoped to a namespace, scoped to an API endpoint, or use\nwildcard scopes like `documents.*`. Some examples of scopes that can be used are:\n\n## Global\n\n- `read`: Allows all read actions\n- `write`: Allows all read and write actions\n\n## Namespaced\n\n- `documents:read`: Allows all document read actions\n- `collections:write`: Allows all collection write actions\n\n## Endpoints\n\n- `documents.info`: Allows only one specific API method\n- `documents.*`: Allows all document API methods\n- `users.*`: Allows all user API methods\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# Rate limits\n\nLike most APIs, Outline has rate limits in place to prevent abuse. Endpoints\nthat mutate data are more restrictive than read-only endpoints. If you exceed\nthe rate limit for a given endpoint, you will receive a `429 Too Many Requests`\nstatus code.\n\nThe response will include a `Retry-After` header that indicates how many seconds\nyou should wait before making another request.\n\n# Policies\n\nMost API resources have associated \"policies\", these objects describe the\ncurrent authentications 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 can\nbe used in an interface to adjust which elements are visible.\n", "version": "0.1.0", "contact": { "email": "hello@getoutline.com" }, "license": { "name": "BSD-3-Clause", "url": "https://github.com/outline/openapi/blob/main/LICENSE" } }, "servers": [ { "url": "https://app.getoutline.com/api", "description": "Cloud hosted" }, { "url": "https://{domain}/api", "description": "Self-hosted on your own server", "variables": { "domain": { "default": "example.com" } } } ], "security": [ { "BearerAuth": [] }, { "OAuth2": [ "read", "write" ] } ], "tags": [ { "name": "AccessRequests", "description": "`AccessRequests` represent a request by a user for access to a document\nthey do not currently have permission to view. The request can be approved\nor dismissed by a user with permission to share the document.\n" }, { "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 workspace.\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": "DataAttributes", "description": "`DataAttributes` represent custom metadata fields that can be attached to\ndocuments. They allow workspaces to add structured data like status, priority,\nor any other custom properties to their documents.\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": "OAuthClients", "description": "`OAuthClients` represent OAuth clients that can be used to authenticate\nusers with third-party services.\n" }, { "name": "OAuthAuthentications", "description": "`OAuthAuthentications` represent individual scoped authentications between\nOutline and an `OAuthClient`.\n" }, { "name": "Revisions", "description": "`Revisions` represent a snapshot of a document at a point in time. They\nare used to keep track of editing and collaboration history – a document\ncan also be restored to a previous revision if necessary.\n" }, { "name": "Shares", "description": "`Shares` represent authorization to view a document without being a member\nof the workspace. 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": "Stars", "description": "`Stars` represent a favorited document or collection in the application sidebar.\nEach user has their own collection of starred items.\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": "Templates", "description": "`Templates` represent reusable document templates that can be used as a\nstarting point when creating new documents. Templates can be scoped to a\nspecific collection or available workspace-wide.\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": { "/accessRequests.create": { "post": { "tags": [ "AccessRequests" ], "summary": "Create an access request", "description": "Request access to a document. The request will be sent to users with permission to share the document for approval or dismissal.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "Identifier for the document to request access to." } }, "required": [ "documentId" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccessRequest" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "accessRequestsCreate" } }, "/accessRequests.info": { "post": { "tags": [ "AccessRequests" ], "summary": "Retrieve an access request", "description": "Retrieve information about an access request by `id`, or the current user's pending request for a document by `documentId`. At least one of these parameters must be provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the access request." }, "documentId": { "type": "string", "format": "uuid", "description": "Identifier for the document to find a pending request for the current user." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccessRequest" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "accessRequestsInfo" } }, "/accessRequests.approve": { "post": { "tags": [ "AccessRequests" ], "summary": "Approve an access request", "description": "Approve a pending access request, granting the requesting user a membership on the document with the specified permission.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the access request." }, "permission": { "type": "string", "description": "The permission to grant the requesting user.", "enum": [ "read", "read_write", "admin" ], "default": "read" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccessRequest" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "accessRequestsApprove" } }, "/accessRequests.dismiss": { "post": { "tags": [ "AccessRequests" ], "summary": "Dismiss an access request", "description": "Dismiss a pending access request without granting the requesting user access to the document.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the access request." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AccessRequest" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "accessRequestsDismiss" } }, "/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", "description": "Name of the file attachment.", "example": "image.png" }, "documentId": { "type": "string", "description": "Identifier for the associated document, if any.", "format": "uuid" }, "contentType": { "type": "string", "description": "MIME type of the file attachment.", "example": "image/png" }, "size": { "type": "integer", "minimum": 0, "description": "Size of the file attachment in bytes." } }, "required": [ "name", "contentType", "size" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "maxUploadSize": { "type": "number" }, "mode": { "type": "string", "enum": [ "post", "put" ], "description": "Indicates which presigned upload method the server is configured to use. When `post`, the client should perform a multipart form POST using `uploadUrl` and `form`. When `put`, the client should perform a PUT request to `url` with the supplied `headers`." }, "uploadUrl": { "type": "string", "format": "uri", "description": "Present when `mode` is `post`. The endpoint to POST a multipart form upload to." }, "form": { "type": "object", "description": "Present when `mode` is `post`. The form fields to include in the multipart upload, including signed credentials." }, "url": { "type": "string", "format": "uri", "description": "Present when `mode` is `put`. The presigned URL to PUT the file contents to." }, "headers": { "type": "object", "description": "Present when `mode` is `put`. The HTTP headers that must be sent with the PUT request." }, "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "attachmentsCreate" } }, "/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": { "302": { "description": "Redirect to the attachment URL" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "attachmentsRedirect" } }, "/attachments.delete": { "post": { "tags": [ "Attachments" ], "summary": "Delete an attachment", "description": "Deleting an attachment is permanent. 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" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "attachmentsDelete" } }, "/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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "authInfo" } }, "/auth.config": { "post": { "tags": [ "Auth" ], "summary": "Retrieve auth config", "description": "Retrieve authentication options", "security": [], "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" } } } } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "authConfig" } }, "/collections.info": { "post": { "tags": [ "Collections" ], "summary": "Retrieve a collection", "description": "Retrieve the details of a collection by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the collection.", "format": "uuid" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsInfo" } }, "/collections.documents": { "post": { "tags": [ "Collections" ], "summary": "Retrieve a collections document structure", "description": "Returns the document structure of a collection as a tree of navigation nodes, representing the hierarchy of documents within the collection.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the collection.", "format": "uuid" } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsDocuments" } }, "/collections.list": { "post": { "tags": [ "Collections" ], "summary": "List all collections", "description": "List all collections that the authenticated user has access to.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/Sorting" }, { "type": "object", "properties": { "query": { "type": "string", "description": "If set, will filter the results by collection name." }, "statusFilter": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionStatus" }, "description": "An optional array of statuses to filter by." } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsList" } }, "/collections.create": { "post": { "tags": [ "Collections" ], "summary": "Create a collection", "description": "Create a new collection with the specified name, description, icon, color, and permission settings. Collections are used to organize documents.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Human Resources" }, "description": { "type": "string", "description": "A brief description of the collection, markdown supported. Only one of `description` or `data` may be provided.", "example": "HR documentation is confidential and should be handled with care." }, "data": { "type": "object", "description": "The collection description as a rich-text ProseMirror JSON document. Only one of `description` or `data` may be provided." }, "permission": { "$ref": "#/components/schemas/Permission" }, "icon": { "type": "string", "description": "A string that represents an icon in the outline-icons package or an emoji" }, "color": { "type": "string", "description": "A hex color code for the collection icon", "example": "#123123" }, "sharing": { "type": "boolean", "description": "Whether public sharing of documents is allowed", "example": false } }, "required": [ "name" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsCreate" } }, "/collections.duplicate": { "post": { "tags": [ "Collections" ], "summary": "Duplicate a collection", "description": "Duplicate an existing collection along with its published documents. The\noriginal collection's settings – icon, color, permission, sharing, and\nsorting – are preserved on the copy. Draft and archived documents are\nnot duplicated. Document duplication runs asynchronously in the\nbackground, so the copy may initially be returned before all of its\ndocuments have been created.\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the collection to duplicate.", "format": "uuid" }, "name": { "type": "string", "description": "An optional name for the new collection. If omitted, the original collection's name is reused." } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsDuplicate" } }, "/collections.update": { "post": { "tags": [ "Collections" ], "summary": "Update a collection", "description": "Update an existing collection's properties such as name, description, icon, color, sharing settings, or permission level.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Human Resources" }, "description": { "type": "string", "description": "A brief description of the collection, markdown supported. Only one of `description` or `data` may be provided.", "example": "HR documentation is confidential and should be handled with care." }, "data": { "type": "object", "description": "The collection description as a rich-text ProseMirror JSON document. Only one of `description` or `data` may be provided." }, "permission": { "$ref": "#/components/schemas/Permission" }, "icon": { "type": "string", "description": "A string that represents an icon in the outline-icons package or an emoji" }, "color": { "type": "string", "description": "A hex color code for the collection icon", "example": "#123123" }, "sharing": { "type": "boolean", "description": "Whether public sharing of documents is allowed", "example": false } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsUpdate" } }, "/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", "description": "Identifier for the collection", "format": "uuid" }, "userId": { "type": "string", "description": "Identifier for the user to add to the collection", "format": "uuid" }, "permission": { "$ref": "#/components/schemas/Permission" } }, "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" } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsAddUser" } }, "/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", "description": "Identifier for the user to remove from the collection", "format": "uuid" } }, "required": [ "id", "userId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsRemoveUser" } }, "/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" ] } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsMemberships" } }, "/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" } } } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsAddGroup" } }, "/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" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsRemoveGroup" } }, "/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" } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsGroupMemberships" } }, "/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" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsDelete" } }, "/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": { "fileOperation": { "$ref": "#/components/schemas/FileOperation" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsExport" } }, "/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" ] }, "includeAttachments": { "type": "boolean", "description": "Whether to include attachments in the export.", "default": true }, "includePrivate": { "type": "boolean", "description": "Whether to include private collections in the export.", "default": true } } } } } }, "description": "Triggers a bulk export of multiple collections and their documents. 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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "collectionsExportAll" } }, "/comments.create": { "post": { "tags": [ "Comments" ], "summary": "Create a comment", "description": "Add a comment or reply to a document, either `data` or `text` is required. Provide `anchorText` to create an inline comment attached to a specific text range in the document.", "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", "description": "The body of the comment." }, "text": { "type": "string", "description": "The body of the comment in markdown.", "example": "Sounds great" }, "anchorText": { "type": "string", "description": "Plain text substring to anchor the comment to as an inline comment. The first occurrence in the document's plain text is used unless disambiguated by `anchorPrefix` and/or `anchorSuffix`." }, "anchorPrefix": { "type": "string", "description": "Text immediately preceding `anchorText`, used to disambiguate between multiple occurrences. Requires `anchorText`." }, "anchorSuffix": { "type": "string", "description": "Text immediately following `anchorText`, used to disambiguate between multiple occurrences. Requires `anchorText`." } }, "required": [ "documentId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "commentsCreate" } }, "/comments.info": { "post": { "tags": [ "Comments" ], "summary": "Retrieve a comment", "description": "Retrieve a comment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "includeAnchorText": { "type": "boolean", "description": "Include the document text that the comment is anchored to, if any, in the response." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Comment" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "commentsInfo" } }, "/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": { "$ref": "#/components/schemas/Comment" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "commentsUpdate" } }, "/comments.delete": { "post": { "tags": [ "Comments" ], "summary": "Delete a comment", "description": "Deletes a comment. If the comment is a top-level comment, all its children will be deleted as well.", "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "commentsDelete" } }, "/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" }, "includeAnchorText": { "type": "boolean", "description": "Include the document text that the comment is anchored to, if any, in the response." } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "commentsList" } }, "/dataAttributes.info": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" } ], "tags": [ "DataAttributes" ], "summary": "Retrieve a data attribute", "description": "Retrieve a data attribute by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data attribute.", "format": "uuid" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataAttribute" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "dataAttributesInfo" } }, "/dataAttributes.list": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" } ], "tags": [ "DataAttributes" ], "summary": "List all data attributes", "description": "List all data attributes.", "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/DataAttribute" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "dataAttributesList" } }, "/dataAttributes.create": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" } ], "tags": [ "DataAttributes" ], "summary": "Create a data attribute", "description": "Create a new data attribute. Only admins can create data attributes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the data attribute.", "example": "Status" }, "description": { "type": "string", "description": "Description of the data attribute.", "example": "The current status of the document." }, "dataType": { "$ref": "#/components/schemas/DataAttributeDataType" }, "options": { "$ref": "#/components/schemas/DataAttributeOptions" }, "pinned": { "type": "boolean", "description": "Whether the data attribute is pinned to the top of document.", "default": false } }, "required": [ "name", "dataType" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataAttribute" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "dataAttributesCreate" } }, "/dataAttributes.update": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" } ], "tags": [ "DataAttributes" ], "summary": "Update a data attribute", "description": "Update an existing data attribute. Only admins can update data attributes. Note that the dataType cannot be changed after creation.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data attribute.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the data attribute.", "example": "Status" }, "description": { "type": "string", "description": "Description of the data attribute." }, "options": { "$ref": "#/components/schemas/DataAttributeOptions" }, "pinned": { "type": "boolean", "description": "Whether the data attribute is pinned to the top of document." } }, "required": [ "id", "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataAttribute" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "dataAttributesUpdate" } }, "/dataAttributes.delete": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" } ], "tags": [ "DataAttributes" ], "summary": "Delete a data attribute", "description": "Delete a data attribute. Only admins can delete data attributes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data attribute.", "format": "uuid" } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "dataAttributesDelete" } }, "/documents.info": { "post": { "tags": [ "Documents" ], "summary": "Retrieve a document", "description": "Retrieve a document by its `UUID`, `urlId`, or `shareId`. At least one of these parameters must be provided.", "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" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Document" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsInfo" } }, "/documents.insights": { "post": { "tags": [ "Documents" ], "summary": "Retrieve insights for a document", "description": "Retrieve a chronologically sorted array of activity rollups (views, comments, reactions, revisions, editors) for a document. Recent activity is returned as daily rollups, while older activity is aggregated into weekly rollups. Insights must be enabled on the document. Defaults to the last 30 days when no date range is provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the document." }, "startDate": { "type": "string", "format": "date-time", "description": "Start of the insights window (inclusive). Defaults to 30 days ago." }, "endDate": { "type": "string", "format": "date-time", "description": "End of the insights window (inclusive). Defaults to today." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInsight" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsInsights" } }, "/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": "Plain text, markdown, docx, pdf, csv, tsv, html, mhtml (or mht) web pages, eml email messages, and textbundle/textpack bundles are supported." }, "collectionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the collection to import into. One of collectionId or parentDocumentId is required." }, "parentDocumentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the parent document to import under. One of collectionId or parentDocumentId is required." }, "publish": { "type": "boolean", "description": "Whether to publish the imported document" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Document" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsImport" } }, "/documents.export": { "post": { "tags": [ "Documents" ], "summary": "Export a document.", "description": "Export a document in Markdown, HTML, PDF, or TextBundle format. The response format is determined by the Accept header (`text/markdown`, `text/html`, `application/pdf`, or `application/x-textbundle`). Optionally include child documents in the export as a zip file.", "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." }, "paperSize": { "type": "string", "description": "Paper size for PDF export (e.g., \"A4\", \"Letter\")" }, "signedUrls": { "type": "number", "description": "How long signed URLs should remain valid for attachment links (in seconds)" }, "includeChildDocuments": { "type": "boolean", "description": "Whether to include child documents in the export. Using this option will always return a zip file.", "default": false } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsExport" } }, "/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": { "filters": { "type": "array", "description": "Structured filter expression, evaluated as an AND of top-level entries. Cannot be combined with the deprecated `collectionId`, `userId`, `parentDocumentId` or `statusFilter` parameters.", "items": { "$ref": "#/components/schemas/DocumentFilter" } }, "collectionId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Optionally filter to a specific collection. Deprecated – prefer the `filters` parameter." }, "userId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Optionally filter to documents created by a specific user. Deprecated – prefer the `filters` parameter." }, "backlinkDocumentId": { "type": "string", "format": "uuid" }, "parentDocumentId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Optionally filter to child documents of a specific parent. Deprecated – prefer the `filters` parameter." }, "statusFilter": { "type": "array", "items": { "type": "string", "enum": [ "draft", "archived", "published" ] }, "deprecated": true, "description": "Document statuses to include in results. Deprecated – prefer the `filters` parameter." } } } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsList" } }, "/documents.documents": { "post": { "tags": [ "Documents" ], "summary": "Retrieve a document's child structure", "description": "This method returns the nested document structure (tree) for the children of the specified 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." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NavigationNode" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsDocuments" } }, "/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": { "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsDrafts" } }, "/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" } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsViewed" } }, "/documents.answerQuestion": { "post": { "x-badges": [ { "name": "Business" }, { "name": "Enterprise" }, { "name": "Cloud" } ], "tags": [ "Documents" ], "summary": "Query documents with natural language", "description": "This method allows asking direct questions of your documents – where possible an answer will be provided. Search results will be restricted to those accessible by the current access token. Note that \"AI answers\" must be enabled for the workspace.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "query": { "type": "string", "example": "What is our holiday policy?" }, "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" }, "documentId": { "type": "string", "description": "A document to search within", "format": "uuid" }, "statusFilter": { "type": "string", "description": "Any documents that are not in the specified status will be filtered out", "enum": [ "draft", "archived", "published" ] }, "dateFilter": { "type": "string", "description": "Any documents that have not been updated within the specified period will be filtered out", "enum": [ "day", "week", "month", "year" ] } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "search": { "$ref": "#/components/schemas/SearchResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsAnswerQuestion" } }, "/documents.search_titles": { "post": { "tags": [ "Documents" ], "summary": "Search document titles", "description": "This method allows you to search document titles with keywords. Unlike documents.search, this only searches titles and returns faster results.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "query": { "type": "string", "description": "Search query to match against document titles" }, "filters": { "type": "array", "description": "Structured filter expression, evaluated as an AND of top-level entries. Cannot be combined with the deprecated `collectionId`, `userId`, `documentId`, `dateFilter` or `statusFilter` parameters.", "items": { "$ref": "#/components/schemas/DocumentFilter" } }, "collectionId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Filter to a specific collection. Deprecated – prefer the `filters` parameter." }, "userId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Filter results based on user. Deprecated – prefer the `filters` parameter." }, "documentId": { "type": "string", "format": "uuid", "deprecated": true, "description": "Filter results based on content within a document and its children. Deprecated – prefer the `filters` parameter." }, "statusFilter": { "type": "array", "items": { "type": "string", "enum": [ "draft", "archived", "published" ] }, "deprecated": true, "description": "Document statuses to include in results. Deprecated – prefer the `filters` parameter." }, "dateFilter": { "type": "string", "deprecated": true, "description": "Any documents that have not been updated within the specified period will be filtered out. Deprecated – prefer the `filters` parameter with a date field and an ISO 8601 duration value.", "enum": [ "day", "week", "month", "year" ] }, "shareId": { "type": "string", "description": "Filter results for the collection or document referenced by the shareId" }, "sort": { "type": "string", "enum": [ "relevance", "createdAt", "updatedAt", "title" ], "description": "Specifies the attributes by which search results will be sorted" }, "direction": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Specifies the sort order with respect to sort field" } }, "required": [ "query" ] } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsSearchTitles" } }, "/documents.search": { "post": { "tags": [ "Documents" ], "summary": "Search all documents", "description": "This methods allows you to search your workspace's 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" }, "filters": { "type": "array", "description": "Structured filter expression, evaluated as an AND of top-level entries. Cannot be combined with the deprecated `collectionId`, `userId`, `documentId`, `dateFilter` or `statusFilter` parameters.", "items": { "$ref": "#/components/schemas/DocumentFilter" } }, "userId": { "type": "string", "deprecated": true, "description": "Any documents that have not been edited by the user identifier will be filtered out. Deprecated – prefer the `filters` parameter.", "format": "uuid" }, "collectionId": { "type": "string", "deprecated": true, "description": "A collection to search within. Deprecated – prefer the `filters` parameter.", "format": "uuid" }, "documentId": { "type": "string", "deprecated": true, "description": "A document to search within. Deprecated – prefer the `filters` parameter.", "format": "uuid" }, "statusFilter": { "type": "array", "deprecated": true, "description": "Document statuses to include in results. Deprecated – prefer the `filters` parameter.", "items": { "type": "string", "enum": [ "draft", "archived", "published" ] } }, "dateFilter": { "type": "string", "deprecated": true, "description": "Any documents that have not been updated within the specified period will be filtered out. Deprecated – prefer the `filters` parameter with a date field and an ISO 8601 duration value.", "example": "month", "enum": [ "day", "week", "month", "year" ] }, "shareId": { "type": "string", "description": "Filter results to the collection or document referenced by the shareId" }, "snippetMinWords": { "type": "number", "description": "Minimum number of words to show in search result snippets", "default": 20 }, "snippetMaxWords": { "type": "number", "description": "Maximum number of words to show in search result snippets", "default": 30 }, "sort": { "type": "string", "enum": [ "relevance", "createdAt", "updatedAt", "title" ], "description": "Specifies the attributes by which search results will be sorted" }, "direction": { "type": "string", "enum": [ "ASC", "DESC" ], "description": "Specifies the sort order with respect to sort field" } } } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsSearch" } }, "/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": { "id": { "type": "string", "format": "uuid", "description": "Optional identifier for the document" }, "title": { "type": "string", "example": "Welcome to Acme Inc" }, "text": { "type": "string", "maxLength": 1536000, "description": "The body of the document in markdown" }, "icon": { "type": "string", "description": "Icon displayed alongside the document title" }, "color": { "type": "string", "nullable": true, "description": "Color for the document icon (hex format)" }, "collectionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the collection. Required to publish unless parentDocumentId is provided" }, "parentDocumentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the parent document. Required to publish unless collectionId is provided" }, "templateId": { "type": "string", "format": "uuid" }, "publish": { "type": "boolean", "description": "Whether this document should be immediately published and made visible to other workspace members." }, "fullWidth": { "type": "boolean", "description": "Whether the document should be displayed in full width" }, "createdAt": { "type": "string", "format": "date-time", "description": "Optionally set the created date in the past" }, "dataAttributes": { "type": "array", "description": "Data attributes to be included on the document.", "items": { "type": "object", "properties": { "dataAttributeId": { "type": "string", "description": "Unique identifier for the data attribute.", "format": "uuid" }, "value": { "description": "The value of the data attribute. Can be a string, boolean, or number depending on the data attribute type.", "example": "In Progress", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } }, "required": [ "dataAttributeId", "value" ] } } } } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsCreate" } }, "/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", "maxLength": 1536000, "description": "The body of the document in markdown." }, "icon": { "type": "string", "nullable": true, "description": "Icon displayed alongside the document title" }, "color": { "type": "string", "nullable": true, "description": "Color for the document icon (hex format)" }, "fullWidth": { "type": "boolean", "description": "Whether the document should be displayed in full width" }, "templateId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the template this document is based on" }, "collectionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the collection to move the document to" }, "insightsEnabled": { "type": "boolean", "description": "Whether insights should be visible on the document" }, "editMode": { "$ref": "#/components/schemas/TextEditMode" }, "findText": { "type": "string", "description": "The text to find within the document when using `patch` editMode. This text will be replaced with the value of `text`. Required when `editMode` is `patch`." }, "publish": { "type": "boolean", "description": "Whether this document should be published and made visible to other workspace members, if a draft" }, "lastRevision": { "type": "integer", "minimum": 0, "description": "If set, the update is rejected with a 409 response when the document's current revision number does not match this value. Use this for optimistic concurrency control to avoid overwriting changes made since the client last loaded the document." }, "dataAttributes": { "type": "array", "description": "Data attributes to be updated. Attributes not included will be removed from the document.", "nullable": true, "items": { "type": "object", "properties": { "dataAttributeId": { "type": "string", "description": "Unique identifier for the data attribute.", "format": "uuid" }, "value": { "description": "The value of the data attribute. Can be a string, boolean, or number depending on the data attribute type.", "example": "In Progress", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } }, "required": [ "dataAttributeId", "value" ] } } }, "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" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The provided `lastRevision` did not match the document's current revision, indicating a conflicting update." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsUpdate" } }, "/documents.templatize": { "post": { "tags": [ "Documents" ], "summary": "Create a template from a document", "description": "This method allows you to create a new template using an existing document as the basis", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier for the collection where the template should be created" }, "publish": { "type": "boolean", "description": "Whether the new template should be published" } }, "required": [ "id", "publish" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Template" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsTemplatize" } }, "/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." }, "detach": { "type": "boolean", "description": "Whether to detach the document from the collection", "default": false } }, "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" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsUnpublish" } }, "/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" }, "index": { "type": "number", "description": "The position index in the collection structure" } }, "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" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsMove" } }, "/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": { "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsArchive" } }, "/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." }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection to restore the document to." }, "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" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsRestore" } }, "/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 permanently 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": { "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsDelete" } }, "/documents.users": { "post": { "tags": [ "Documents" ], "summary": "List document users", "description": "All users with access to a document. To list only users with direct membership to the document use `documents.memberships`", "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." }, "query": { "type": "string", "description": "If set, will filter the results by user name." }, "userId": { "type": "string", "format": "uuid", "description": "If set, will filter the results to a specific user." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsUsers" } }, "/documents.memberships": { "post": { "tags": [ "Documents" ], "summary": "List document memberships", "description": "Users with direct membership to a document. To list all users with access to a document use `documents.users`.", "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." }, "query": { "type": "string", "description": "If set, will filter the results by user name" }, "permission": { "$ref": "#/components/schemas/Permission" } }, "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" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsMemberships" } }, "/documents.add_user": { "post": { "tags": [ "Documents" ], "summary": "Add a document user", "description": "This method allows you to add a user membership to the specified 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." }, "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": "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsAddUser" } }, "/documents.remove_user": { "post": { "tags": [ "Documents" ], "summary": "Remove a document user", "description": "This method allows you to remove a user membership from the specified 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." }, "userId": { "type": "string", "format": "uuid" } }, "required": [ "id", "userId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsRemoveUser" } }, "/documents.archived": { "post": { "tags": [ "Documents" ], "summary": "List all archived documents", "description": "This method will list all archived documents belonging to the workspace that the current user has access to.", "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" } } } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsArchived" } }, "/documents.deleted": { "post": { "tags": [ "Documents" ], "summary": "List all deleted documents", "description": "This method will list all deleted documents belonging to the workspace that the current user has access to.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/Sorting" }, { "type": "object", "properties": { "filters": { "type": "array", "description": "Structured filter expression, evaluated as an AND of top-level entries. Supported fields are `deletedAt` (date) and `deletedById` (uuid, identifier of the user who deleted the document).", "items": { "$ref": "#/components/schemas/DocumentsDeletedFilter" } } } } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsDeleted" } }, "/documents.duplicate": { "post": { "tags": [ "Documents" ], "summary": "Duplicate a document", "description": "This method allows you to duplicate an existing document and optionally all of its child documents.", "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." }, "title": { "type": "string", "description": "New title for the duplicated document" }, "recursive": { "type": "boolean", "description": "Whether child documents should also be duplicated" }, "publish": { "type": "boolean", "description": "Whether the new document should be published" }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection the document should be copied to" }, "parentDocumentId": { "type": "string", "format": "uuid", "description": "Identifier for the parent document the document should be copied to" } }, "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" } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsDuplicate" } }, "/documents.add_group": { "post": { "tags": [ "Documents" ], "summary": "Add a group to a document", "description": "This method allows you to give all members in a group access to 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." }, "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": { "groupMemberships": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionGroupMembership" } } } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsAddGroup" } }, "/documents.remove_group": { "post": { "tags": [ "Documents" ], "summary": "Remove a group from a document", "description": "This method allows you to revoke all members in a group access to 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." }, "groupId": { "type": "string", "format": "uuid" } }, "required": [ "id", "groupId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsRemoveGroup" } }, "/documents.group_memberships": { "post": { "tags": [ "Documents" ], "summary": "List document group memberships", "description": "This method allows you to list a document's group memberships.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the document. Either the UUID or the urlId is acceptable." }, "query": { "type": "string", "description": "Filter memberships by group names" }, "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" } }, "groupMemberships": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionGroupMembership" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsGroupMemberships" } }, "/documents.empty_trash": { "post": { "tags": [ "Documents" ], "summary": "Empty trash", "description": "Permanently delete all documents in the trash. This action is irreversible. Only available to admin users.", "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "documentsEmptyTrash" } }, "/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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "eventsList" } }, "/fileOperations.info": { "post": { "tags": [ "FileOperations" ], "summary": "Retrieve a file operation", "description": "Retrieve the details and current status of a file operation by its unique identifier. File operations represent long-running import or export tasks.", "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/FileOperation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "fileOperationsInfo" } }, "/fileOperations.delete": { "post": { "tags": [ "FileOperations" ], "summary": "Delete a file operation", "description": "Delete a file operation and its associated files. This is useful for cleaning up completed or failed import/export operations.", "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": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "fileOperationsDelete" } }, "/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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "fileOperationsRedirect" } }, "/fileOperations.list": { "post": { "tags": [ "FileOperations" ], "summary": "List all file operations", "description": "List all file operations for the current workspace, filtered by type (import or export).", "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": { "type": "array", "items": { "$ref": "#/components/schemas/FileOperation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "fileOperationsList" } }, "/groups.info": { "post": { "tags": [ "Groups" ], "summary": "Retrieve a group", "description": "Retrieve the details of a group by its unique identifier, including its name and member count.", "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" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsInfo" } }, "/groups.list": { "post": { "tags": [ "Groups" ], "summary": "List all groups", "description": "List all groups in the workspace. Groups are used to organize users and manage permissions for collections.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/Sorting" }, { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "description": "Filter to groups including a specific user" }, "externalId": { "type": "string", "format": "uuid", "description": "Filter to groups matching an external ID" }, "query": { "type": "string", "format": "uuid", "description": "Filter to groups matching a search query" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "groupMemberships": { "type": "array", "description": "A preview of memberships in the group, note that this is not all memberships which can be queried from `groups.memberships`.", "items": { "$ref": "#/components/schemas/GroupMembership" } } } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsList" } }, "/groups.create": { "post": { "tags": [ "Groups" ], "summary": "Create a group", "description": "Create a new group with the specified name. Groups can be used to organize users and assign collection permissions to multiple users at once.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Designers" } }, "required": [ "name" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsCreate" } }, "/groups.update": { "post": { "tags": [ "Groups" ], "summary": "Update a group", "description": "Update an existing group's name. The group is identified by its unique identifier.", "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": { "$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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsUpdate" } }, "/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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsDelete" } }, "/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": "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsMemberships" } }, "/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", "description": "Identifier for the group", "format": "uuid" }, "userId": { "type": "string", "description": "Identifier for the user to add to the group", "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/GroupMembership" } } } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsAddUser" } }, "/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 group", "format": "uuid" }, "userId": { "type": "string", "description": "Identifier for the user to remove from the group", "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" } } } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "groupsRemoveUser" } }, "/oauthClients.info": { "post": { "tags": [ "OAuthClients" ], "summary": "Retrieve an OAuth client", "description": "To retrieve information about an OAuth client you must pass either an `id` or a `clientId`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the OAuth client.", "format": "uuid" }, "clientId": { "type": "string", "description": "Public identifier for the OAuth client.", "example": "2bquf8avrpdv31par42a" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsInfo" } }, "/oauthClients.list": { "post": { "tags": [ "OAuthClients" ], "summary": "List accessible OAuth clients", "description": "List all OAuth clients that the authenticated user has access to. This includes both clients created by the user and published clients available to the workspace.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthClient" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsList" } }, "/oauthClients.create": { "post": { "tags": [ "OAuthClients" ], "summary": "Create an OAuth client", "description": "Create a new OAuth client application that can be used to authenticate users and access the API on their behalf.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the OAuth client.", "example": "My App" }, "description": { "type": "string", "description": "A short description of this OAuth client.", "example": "Integrate Acme Inc's services into Outline." }, "developerName": { "type": "string", "description": "The name of the developer who created this OAuth client.", "example": "Acme Inc" }, "developerUrl": { "type": "string", "description": "The URL of the developer who created this OAuth client.", "example": "https://example.com" }, "avatarUrl": { "type": "string", "description": "A URL pointing to an image representing the OAuth client." }, "redirectUris": { "type": "array", "items": { "type": "string" }, "description": "List of redirect URIs for the OAuth client.", "example": [ "https://example.com/callback" ] }, "published": { "type": "boolean", "description": "Whether the OAuth client is available to other workspaces.", "example": true } }, "required": [ "name", "redirectUris" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsCreate" } }, "/oauthClients.update": { "post": { "tags": [ "OAuthClients" ], "summary": "Update an OAuth client", "description": "Update an existing OAuth client's properties such as name, description, redirect URIs, or published status.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the OAuth client.", "format": "uuid" }, "name": { "type": "string", "description": "Name of the OAuth client.", "example": "My App" }, "description": { "type": "string", "description": "A short description of this OAuth client.", "example": "Integrate Acme Inc's services into Outline." }, "developerName": { "type": "string", "description": "The name of the developer who created this OAuth client.", "example": "Acme Inc" }, "developerUrl": { "type": "string", "description": "The URL of the developer who created this OAuth client.", "example": "https://example.com" }, "avatarUrl": { "type": "string", "description": "A URL pointing to an image representing the OAuth client." }, "redirectUris": { "type": "array", "items": { "type": "string" }, "description": "List of redirect URIs for the OAuth client.", "example": [ "https://example.com/callback" ] }, "published": { "type": "boolean", "description": "Whether the OAuth client is available to other workspaces.", "example": true } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsUpdate" } }, "/oauthClients.rotate_secret": { "post": { "tags": [ "OAuthClients" ], "summary": "Rotate the secret for an OAuth client", "description": "Generate a new client secret for an OAuth client. The old secret will be invalidated immediately, so ensure your application is updated to use the new secret.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the OAuth client.", "format": "uuid" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OAuthClient" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsRotateSecret" } }, "/oauthClients.delete": { "post": { "tags": [ "OAuthClients" ], "summary": "Delete an OAuth client", "description": "Permanently delete an OAuth client and revoke all associated access tokens. This action cannot be undone.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the OAuth client.", "format": "uuid" } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthClientsDelete" } }, "/oauthAuthentications.list": { "post": { "tags": [ "OAuthAuthentications" ], "summary": "List accessible OAuth authentications", "description": "List all OAuth authentications for the current user. These represent the third-party applications that the user has authorized to access their account.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthAuthentication" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthAuthenticationsList" } }, "/oauthAuthentications.delete": { "post": { "tags": [ "OAuthAuthentications" ], "summary": "Delete an OAuth authentiation", "description": "Revoke an OAuth authentication, removing the third-party application's access to the user's account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oauthClientId": { "type": "string", "format": "uuid" }, "scope": { "type": "array", "items": { "type": "string" } } }, "required": [ "oauthClientId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "oauthAuthenticationsDelete" } }, "/revisions.info": { "post": { "tags": [ "Revisions" ], "summary": "Retrieve a revision", "description": "A revision is a snapshot of a document at a specific point in time. This endpoint allows you to retrieve a specific version of a document by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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/RevisionDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "revisionsInfo" } }, "/revisions.list": { "post": { "tags": [ "Revisions" ], "summary": "List all revisions", "description": "List all revisions for a specific document. Revisions represent historical snapshots of a document's content and can be used to track changes over time. The `data` and `text` fields are omitted from listed revisions for performance; use `revisions.info` to retrieve the full content of a specific revision.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/Sorting" }, { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "The document ID to retrieve revisions for" } } } ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "revisionsList" } }, "/shares.info": { "post": { "tags": [ "Shares" ], "summary": "Retrieve a share object", "description": "Retrieve the details of a share link by its unique identifier or by the associated document ID. Shares allow documents to be accessed publicly or by specific users.", "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" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Share" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "sharesInfo" } }, "/shares.list": { "post": { "tags": [ "Shares" ], "summary": "List all shares", "description": "List all share links in the workspace.", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/Sorting" }, { "type": "object", "properties": { "query": { "type": "string", "description": "Filter to shared documents matching a search query" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Share" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "sharesList" } }, "/shares.create": { "post": { "tags": [ "Shares" ], "summary": "Create a share", "description": "Creates a new share link that can be used by to access a document or collection. If you request multiple shares for the same resource with the same API key, the same share object will be returned. By default all shares are unpublished. Exactly one of `documentId` or `collectionId` must be provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "Identifier for the document to share. Mutually exclusive with `collectionId`." }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection to share. Mutually exclusive with `documentId`." } }, "oneOf": [ { "required": [ "documentId" ] }, { "required": [ "collectionId" ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Share" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "sharesCreate" } }, "/shares.update": { "post": { "tags": [ "Shares" ], "summary": "Update a share", "description": "Allows changing an existing share's 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" }, "title": { "type": "string", "maxLength": 255, "nullable": true, "description": "Override title displayed on the publicly shared page. If not set the source document or collection title is used." }, "iconUrl": { "type": "string", "format": "uri", "maxLength": 4096, "nullable": true, "description": "URL of an icon to display on the publicly shared page, overriding the workspace branding." } }, "required": [ "id", "published" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Share" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "sharesUpdate" } }, "/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" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "sharesRevoke" } }, "/stars.create": { "post": { "tags": [ "Stars" ], "summary": "Create a star", "description": "Stars a document or collection so it appears in the users sidebar. One of either `documentId` or `collectionId` must be provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid" }, "index": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Star" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "starsCreate" } }, "/stars.list": { "post": { "tags": [ "Stars" ], "summary": "List all stars", "description": "List all starred documents for the authenticated user. Stars allow users to bookmark important documents for quick access in the sidebar.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "stars": { "type": "array", "items": { "$ref": "#/components/schemas/Star" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "starsList" } }, "/stars.update": { "post": { "tags": [ "Stars" ], "summary": "Update a stars order in the sidebar", "description": "Update the position of a starred document in the sidebar. The index parameter determines the display order relative to other starred documents.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "index": { "type": "string" } }, "required": [ "id", "index" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Star" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "starsUpdate" } }, "/stars.delete": { "post": { "tags": [ "Stars" ], "summary": "Delete a star", "description": "Remove a star from a document, removing it from the user's starred documents list in the sidebar.", "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "starsDelete" } }, "/users.invite": { "post": { "tags": [ "Users" ], "summary": "Invite users", "description": "Send email invitations to one or more users to join the workspace. Invitations include a link to create an account and join the workspace.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } }, "suppressEmail": { "type": "boolean", "description": "If true, the invitation emails will not be sent to the invited users. Defaults to false." } }, "required": [ "invites" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersInvite" } }, "/users.info": { "post": { "tags": [ "Users" ], "summary": "Retrieve a user", "description": "Retrieve the details of a user by their unique identifier, including their name, email, avatar, and role within the workspace.", "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" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersInfo" } }, "/users.list": { "post": { "tags": [ "Users" ], "summary": "List all users", "description": "List and filter all the users in the workspace", "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", "description": "Array of emails", "items": { "type": "string" }, "example": [ "jane.crandall@mail.com", "prudence.crandall@mail.com" ] }, "filter": { "type": "string", "description": "The status to filter by", "enum": [ "all", "invited", "active", "suspended" ] }, "role": { "$ref": "#/components/schemas/UserRole" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersList" } }, "/users.update": { "post": { "tags": [ "Users" ], "summary": "Update a user", "description": "Update a users name or avatar. If no `id` is passed then the user associated with the authentication will be updated by default.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string", "format": "BCP47" }, "avatarUrl": { "type": "string", "format": "uri" }, "preferences": { "type": "object", "description": "User-level preference flags. Only the fields supplied are updated; existing values for other preferences are preserved.", "properties": { "sidebarSectionOrder": { "type": "array", "description": "The order in which the top-level sections appear in the sidebar of the app UI.", "items": { "type": "string", "enum": [ "starred", "shared", "collections" ] } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersUpdate" } }, "/users.update_role": { "post": { "tags": [ "Users" ], "summary": "Change a users role", "description": "Change the role of a user, only available to admin authorization.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the user.", "format": "uuid" }, "role": { "$ref": "#/components/schemas/UserRole" } }, "required": [ "id", "role" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersUpdateRole" } }, "/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" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersSuspend" } }, "/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" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersActivate" } }, "/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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "usersDelete" } }, "/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", "description": "The document ID to retrieve views for" }, "includeSuspended": { "type": "boolean", "description": "Whether to include views from suspended users", "default": false } }, "required": [ "documentId" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "viewsList" } }, "/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" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "viewsCreate" } }, "/templates.create": { "post": { "tags": [ "Templates" ], "summary": "Create a template", "description": "Create a new template that can be used as a starting point for new documents. Templates can optionally be scoped to a specific collection.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Optionally provide a specific UUID for the template." }, "title": { "type": "string", "description": "The title of the template. Required when publishing.", "maxLength": 255 }, "data": { "type": "object", "description": "The body of the template as a Prosemirror document. Required when publishing." }, "icon": { "type": "string", "description": "An emoji to use as the template icon.", "nullable": true }, "color": { "type": "string", "description": "The color of the template icon in hex format.", "nullable": true, "pattern": "^#[0-9A-Fa-f]{6}$" }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection to which the template belongs." }, "publish": { "type": "boolean", "default": true, "description": "Whether the template is available to other members. Set to false to create a draft that is only visible to its creator." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Template" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } } } }, "400": { "$ref": "#/components/responses/Validation" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesCreate" } }, "/templates.list": { "post": { "tags": [ "Templates" ], "summary": "List all templates", "description": "List all templates available to the current user. Optionally filter by collection. Templates not associated with a collection are workspace-wide.", "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" }, "query": { "type": "string", "description": "Search query to filter templates by title" } } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesList" } }, "/templates.info": { "post": { "tags": [ "Templates" ], "summary": "Retrieve a template", "description": "Retrieve a template by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template. 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/Template" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesInfo" } }, "/templates.update": { "post": { "tags": [ "Templates" ], "summary": "Update a template", "description": "Update an existing template by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template. Either the UUID or the urlId is acceptable." }, "title": { "type": "string", "description": "The title of the template." }, "data": { "type": "object", "description": "The body of the template as a Prosemirror document." }, "icon": { "type": "string", "description": "An emoji to use as the template icon.", "nullable": true }, "color": { "type": "string", "description": "The color of the template icon in hex format.", "nullable": true, "pattern": "^#[0-9A-Fa-f]{6}$" }, "fullWidth": { "type": "boolean", "description": "Whether the template should be displayed full width." }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection to which the template belongs. Set to null for a workspace-wide template.", "nullable": true }, "publish": { "type": "boolean", "description": "Set to true to publish a draft template so it becomes available to other members." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Template" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesUpdate" } }, "/templates.delete": { "post": { "tags": [ "Templates" ], "summary": "Delete a template", "description": "Delete a template by its unique identifier. This will soft-delete the template, it can be restored later.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template. Either the UUID or the urlId is acceptable." } }, "required": [ "id" ] } } } }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesDelete" } }, "/templates.restore": { "post": { "tags": [ "Templates" ], "summary": "Restore a template", "description": "Restore a previously deleted template by its unique identifier.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template. 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/Template" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesRestore" } }, "/templates.duplicate": { "post": { "tags": [ "Templates" ], "summary": "Duplicate a template", "description": "Create a copy of an existing template. Optionally override the title and target collection.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the template to duplicate. Either the UUID or the urlId is acceptable." }, "title": { "type": "string", "description": "Override the title of the duplicated template." }, "collectionId": { "type": "string", "format": "uuid", "description": "Identifier for the collection to place the duplicated template in. If not provided, uses the original template's collection.", "nullable": true } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Template" }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "operationId": "templatesDuplicate" } } }, "components": { "schemas": { "Permission": { "type": "string", "enum": [ "read", "read_write" ] }, "TextEditMode": { "type": "string", "description": "The editing mode for text updates to a document. When set to `patch`, the `findText` parameter is required and the existing occurrence of `findText` will be replaced with the value of `text`.", "enum": [ "append", "prepend", "replace", "patch" ] }, "AccessRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "documentId": { "type": "string", "description": "Identifier for the document this request is for.", "format": "uuid" }, "userId": { "type": "string", "description": "Identifier for the user that made the request.", "format": "uuid" }, "user": { "$ref": "#/components/schemas/User" }, "teamId": { "type": "string", "description": "Identifier for the workspace the request belongs to.", "format": "uuid" }, "status": { "type": "string", "description": "The current status of the access request.", "enum": [ "pending", "approved", "dismissed" ] }, "responderId": { "type": "string", "description": "Identifier for the user that responded to the request, if any.", "format": "uuid", "nullable": true }, "responder": { "$ref": "#/components/schemas/User" }, "respondedAt": { "type": "string", "description": "The date and time the request was responded to, if any.", "format": "date-time", "nullable": 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" } } }, "Attachment": { "type": "object", "properties": { "contentType": { "type": "string", "example": "image/png" }, "size": { "type": "string", "description": "The size of the attachment in bytes. Returned as a string as the value may exceed the safe integer range." }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "documentId": { "type": "string", "description": "Identifier for the associated document, if any.", "format": "uuid", "nullable": true }, "userId": { "type": "string", "description": "Identifier for the user that created the attachment.", "format": "uuid" } } }, "Pagination": { "type": "object", "properties": { "offset": { "type": "number", "example": 0 }, "limit": { "type": "number", "example": 25 } } }, "Sorting": { "type": "object", "properties": { "sort": { "type": "string", "example": "updatedAt" }, "direction": { "type": "string", "example": "DESC", "enum": [ "ASC", "DESC" ] } } }, "DocumentFilter": { "description": "A single filter node, either a leaf condition matching a document field or a group combining nested filters with a logical operator.", "oneOf": [ { "type": "object", "description": "A condition that compares a document field against a value.", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "Name of the document field to filter on.", "enum": [ "createdAt", "updatedAt", "publishedAt", "archivedAt", "title", "templateId", "collectionId", "userId", "documentId", "parentDocumentId" ] }, "operator": { "type": "string", "description": "Comparison operator to apply. Note that some fields only accept a subset of operators – for example `userId` and `documentId` only support `eq` and `in`.", "enum": [ "eq", "neq", "lt", "lte", "gt", "gte", "contains", "startsWith", "endsWith", "containsStrict", "startsWithStrict", "endsWithStrict", "in", "notIn", "isNull", "isNotNull" ] }, "value": { "description": "Value to compare against. May be a string, number, boolean or array of these depending on the field and operator. Date fields accept an ISO 8601 date or an ISO 8601 duration (relative to now). Omit for `isNull` and `isNotNull`." } } }, { "type": "object", "description": "A logical group that combines nested filters with an `AND` or `OR` operator. Groups may themselves contain further groups.", "required": [ "operator", "filters" ], "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentFilter" } } } } ] }, "DocumentsDeletedFilter": { "description": "A single filter node for `/documents.deleted`, either a leaf condition matching a supported field or a group combining nested filters with a logical operator.", "oneOf": [ { "type": "object", "description": "A condition that compares a deleted-document field against a value.", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "Name of the field to filter on.", "enum": [ "deletedAt", "deletedById" ] }, "operator": { "type": "string", "description": "Comparison operator to apply. `deletedById` only supports `eq` and `in`.", "enum": [ "eq", "neq", "lt", "lte", "gt", "gte", "in", "notIn", "isNull", "isNotNull" ] }, "value": { "description": "Value to compare against. `deletedAt` accepts an ISO 8601 date or an ISO 8601 duration (relative to now); `deletedById` accepts a user UUID (or an array of UUIDs with `in`/`notIn`). Omit for `isNull` and `isNotNull`." } } }, { "type": "object", "description": "A logical group that combines nested filters with an `AND` or `OR` operator. Groups may themselves contain further groups.", "required": [ "operator", "filters" ], "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentsDeletedFilter" } } } } ] }, "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" }, "url": { "type": "string", "description": "The relative URL path at which the collection can be accessed.", "readOnly": true }, "urlId": { "type": "string", "description": "A short unique identifier that can be used to identify the collection instead of the UUID.", "readOnly": true, "example": "hDYep1TPAM" }, "name": { "type": "string", "description": "The name of the collection.", "example": "Human Resources" }, "description": { "type": "string", "nullable": true, "description": "A description of the collection, may contain markdown formatting", "example": "" }, "data": { "type": "object", "nullable": true, "description": "The collection description as rich-text JSON, when available." }, "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", "nullable": true, "description": "The position of the collection in the sidebar", "example": "P" }, "color": { "type": "string", "nullable": true, "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", "nullable": true, "description": "A string that represents an icon in the outline-icons package or an emoji" }, "permission": { "$ref": "#/components/schemas/Permission" }, "templateManagement": { "$ref": "#/components/schemas/Permission" }, "sharing": { "type": "boolean", "description": "Whether public document sharing is enabled in this collection", "default": false }, "commenting": { "type": "boolean", "nullable": true, "description": "Whether commenting is enabled in this collection" }, "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" }, "archivedAt": { "type": "string", "nullable": true, "description": "The date and time that this object was archived", "readOnly": true, "format": "date-time" }, "archivedBy": { "$ref": "#/components/schemas/User" }, "sourceMetadata": { "type": "object", "nullable": true, "description": "Metadata about the external source this collection was imported from, if any.", "properties": { "externalId": { "type": "string" }, "externalName": { "type": "string" }, "createdByName": { "type": "string" } } } } }, "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" }, "createdById": { "type": "string", "description": "Identifier for the user who created this comment.", "format": "uuid", "readOnly": true }, "updatedAt": { "type": "string", "description": "The date and time that this object was last changed", "readOnly": true, "format": "date-time" }, "resolvedAt": { "type": "string", "description": "The date and time that this comment was resolved, if it has been.", "format": "date-time", "nullable": true, "readOnly": true }, "resolvedBy": { "allOf": [ { "nullable": true }, { "$ref": "#/components/schemas/User" } ] }, "resolvedById": { "type": "string", "description": "Identifier for the user who resolved this comment, if any.", "format": "uuid", "nullable": true, "readOnly": true }, "reactions": { "type": "array", "description": "List of emoji reactions on this comment.", "items": { "type": "object" }, "readOnly": true }, "anchorText": { "type": "string", "description": "The document text that the comment is anchored to, only included if includeAnchorText=true.", "readOnly": true } } }, "DataAttribute": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "name": { "type": "string", "description": "The name of this data attribute.", "example": "Status" }, "description": { "type": "string", "description": "A description of the data attribute.", "example": "The current status of the document." }, "dataType": { "$ref": "#/components/schemas/DataAttributeDataType" }, "options": { "$ref": "#/components/schemas/DataAttributeOptions" }, "pinned": { "type": "boolean", "description": "Whether this data attribute is pinned to the top of documents.", "default": false }, "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" } } }, "DataAttributeDataType": { "type": "string", "description": "The data type of the attribute value.", "enum": [ "string", "number", "boolean", "list" ] }, "DataAttributeOptions": { "type": "object", "description": "Additional options for certain data attribute types.", "properties": { "icon": { "type": "string", "description": "An icon representing the data attribute from the outline-icons package." }, "options": { "type": "array", "description": "Valid options for list data type.", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The label/value of the option." }, "color": { "type": "string", "description": "Optional color for the option." } } } } } }, "DocumentDataAttribute": { "type": "object", "properties": { "dataAttributeId": { "type": "string", "description": "Unique identifier for the associated data attribute.", "format": "uuid" }, "value": { "description": "The value of the data attribute for this document.", "example": "In Progress", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] }, "updatedAt": { "type": "string", "description": "The date and time that this object attribute was last changed", "readOnly": true, "format": "date-time" } } }, "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", "nullable": true }, "parentDocumentId": { "type": "string", "description": "Identifier for the document this is a child of, if any.", "format": "uuid", "nullable": true }, "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." }, "icon": { "type": "string", "nullable": true, "description": "An emoji or icon associated with the document.", "example": "🎉" }, "color": { "type": "string", "nullable": true, "description": "The color of the document icon in hex format." }, "text": { "type": "string", "description": "The text content of the document, contains markdown formatting", "example": "…" }, "data": { "type": "object", "nullable": true, "description": "The body of the document as a Prosemirror document, returned in place of text when requested." }, "url": { "type": "string", "description": "A URL path to access the document.", "readOnly": true }, "urlId": { "type": "string", "description": "A short unique ID that can be used to identify the document as an alternative to the UUID", "example": "hDYep1TPAM" }, "collaboratorIds": { "type": "array", "description": "Identifiers of users who have edited the document.", "items": { "type": "string", "format": "uuid" } }, "tasks": { "type": "object", "description": "Task completion counts for the document.", "properties": { "completed": { "type": "number" }, "total": { "type": "number" } } }, "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" }, "dataAttributes": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DocumentDataAttribute" } }, "archivedAt": { "type": "string", "nullable": true, "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" } } }, "DocumentInsight": { "type": "object", "description": "A rollup of activity counts for a document over a daily or weekly period.", "properties": { "date": { "type": "string", "format": "date", "description": "The UTC day the rollup represents. For weekly rollups this is the first day (Monday) of the week." }, "period": { "type": "string", "description": "The length of time the rollup covers. Daily rollups are stored for recent activity, older rollups are aggregated into weekly buckets.", "enum": [ "day", "week" ] }, "viewCount": { "type": "integer", "description": "Total number of document views on this day." }, "viewerCount": { "type": "integer", "description": "Number of unique viewers on this day." }, "commentCount": { "type": "integer", "description": "Total comments made on this day." }, "reactionCount": { "type": "integer", "description": "Total reactions added on this day." }, "revisionCount": { "type": "integer", "description": "Number of document revisions on this day." }, "editorCount": { "type": "integer", "description": "Number of unique editors on this day." } } }, "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 }, "userId": { "type": "string", "description": "Identifier for the user associated with the event, if any.", "format": "uuid", "readOnly": true }, "actorId": { "type": "string", "description": "The user that performed the action.", "format": "uuid", "readOnly": true }, "authType": { "type": "string", "description": "The authentication method used to perform the action.", "enum": [ "api", "app", "mcp", "oauth" ], "nullable": true, "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 }, "changes": { "type": "object", "nullable": true, "description": "The set of changes made by this event. This field is only returned when the `auditLog` boolean is true.", "readOnly": true }, "actor": { "$ref": "#/components/schemas/User" } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "number" }, "data": { "type": "object" } } }, "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" ] }, "format": { "type": "string", "description": "The file format of the resulting file.", "example": "outline-markdown", "readOnly": true }, "name": { "type": "string", "description": "The name of the file operation, derived from the collection name, document title, or file name.", "readOnly": true }, "state": { "type": "string", "description": "The state of the file operation.", "example": "complete", "readOnly": true, "enum": [ "creating", "uploading", "complete", "error", "expired" ] }, "error": { "type": "string", "nullable": true, "description": "An error message if the file operation failed.", "readOnly": true }, "size": { "type": "string", "description": "The size of the resulting file in bytes. Returned as a string as the value may exceed the safe integer range.", "readOnly": true, "example": "2048" }, "collectionId": { "type": "string", "nullable": true, "description": "Identifier for the associated collection, if the file operation is scoped to a single collection.", "readOnly": true, "format": "uuid" }, "documentId": { "type": "string", "nullable": true, "description": "Identifier for the associated document, if the file operation is scoped to a single document.", "readOnly": true, "format": "uuid" }, "user": { "$ref": "#/components/schemas/User" }, "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" } } }, "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" }, "description": { "type": "string", "nullable": true, "description": "A short description of this group." }, "externalId": { "type": "string", "nullable": true, "description": "An identifier for this group in an external system, if linked." }, "disableMentions": { "type": "boolean", "description": "Whether mentioning this group is disabled." }, "externalGroup": { "type": "object", "nullable": true, "description": "Details of the linked external group, if any." }, "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" } } }, "OAuthClient": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "name": { "type": "string", "description": "The name of this OAuth client.", "example": "Acme Inc" }, "description": { "type": "string", "nullable": true, "description": "A short description of this OAuth client.", "example": "Integrate Acme Inc's services into Outline." }, "developerName": { "type": "string", "nullable": true, "description": "The name of the developer who created this OAuth client.", "example": "Acme Inc" }, "developerUrl": { "type": "string", "nullable": true, "description": "The URL of the developer who created this OAuth client.", "example": "https://example.com" }, "avatarUrl": { "type": "string", "nullable": true, "description": "A URL pointing to an image representing the OAuth client." }, "clientId": { "type": "string", "description": "The client ID for the OAuth client.", "readOnly": true, "example": "2bquf8avrpdv31par42a" }, "clientSecret": { "type": "string", "description": "The client secret for the OAuth client. Only returned when the request is authenticated with a credential whose scope permits managing OAuth clients.", "readOnly": true, "example": "ol_sk_rapdv31..." }, "clientType": { "type": "string", "description": "The type of the OAuth client.", "readOnly": true, "enum": [ "public", "confidential" ] }, "redirectUris": { "type": "array", "items": { "type": "string" }, "description": "The redirect URIs for the OAuth client.", "example": [ "https://example.com/callback" ] }, "published": { "type": "boolean", "description": "Whether the OAuth client is available to other workspaces.", "example": true }, "lastActiveAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when this OAuth client was last used.", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when this OAuth client was created", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when this OAuth client was updated", "readOnly": true } } }, "OAuthAuthentication": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "oauthClientId": { "type": "string", "description": "Identifier for the associated OAuthClient.", "readOnly": true, "format": "uuid" }, "oauthClient": { "type": "object", "readOnly": true, "description": "A reduced, public representation of the associated OAuth client.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "developerName": { "type": "string", "nullable": true }, "developerUrl": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "clientId": { "type": "string" }, "published": { "type": "boolean" } } }, "userId": { "type": "string", "description": "Identifier for the associated User.", "readOnly": true, "format": "uuid" }, "scope": { "type": "array", "items": { "type": "string" } }, "lastActiveAt": { "type": "string", "format": "date-time", "description": "Date and time when this authentication was last used", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when this authentication was created", "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 }, "name": { "type": "string", "nullable": true, "description": "The name of the revision, if any.", "readOnly": true }, "icon": { "type": "string", "nullable": true, "description": "An emoji or icon associated with the revision.", "readOnly": true }, "color": { "type": "string", "nullable": true, "description": "The color of the revision icon in hex format.", "readOnly": true }, "collaborators": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when this revision was created", "readOnly": true }, "createdBy": { "$ref": "#/components/schemas/User" }, "createdById": { "type": "string", "description": "Identifier for the user who created this revision.", "format": "uuid", "readOnly": true }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when this revision was deleted, if applicable.", "readOnly": true }, "sourceMetadata": { "type": "object", "nullable": true, "description": "Metadata about how the revision was created, if any.", "readOnly": true, "properties": { "authType": { "type": "string", "description": "The authentication method used to create the revision.", "enum": [ "api", "app", "mcp", "oauth" ], "nullable": true, "readOnly": true } } } } }, "RevisionDetail": { "allOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "object", "properties": { "data": { "type": "object", "description": "The body of the revision as a Prosemirror document.", "readOnly": true }, "text": { "type": "string", "description": "Body of the document, may contain markdown formatting", "readOnly": true } } } ] }, "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 }, "sourceTitle": { "type": "string", "description": "Title of the shared document or collection.", "readOnly": true }, "sourcePath": { "type": "string", "description": "Path of the shared document or collection.", "readOnly": true }, "documentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier of the shared document, if any.", "readOnly": true }, "collectionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier of the shared collection, if any.", "readOnly": true }, "urlId": { "type": "string", "nullable": true, "description": "Short URL identifier for the share, if set.", "readOnly": true }, "url": { "type": "string", "format": "uri", "description": "URL of the publicly shared document.", "readOnly": true }, "domain": { "type": "string", "nullable": true, "description": "Custom domain the share is served on, if any." }, "title": { "type": "string", "maxLength": 255, "nullable": true, "description": "Override title displayed on the publicly shared page. If not set the source document or collection title is used." }, "iconUrl": { "type": "string", "format": "uri", "maxLength": 4096, "nullable": true, "description": "URL of an icon displayed on the publicly shared page, overriding the workspace branding." }, "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." }, "allowSubscriptions": { "type": "boolean", "example": true, "description": "Whether visitors to the public share can subscribe to receive email notifications when the document is updated. Requires SMTP to be configured on the workspace." }, "allowIndexing": { "type": "boolean", "description": "Whether the shared page may be indexed by search engines." }, "showLastUpdated": { "type": "boolean", "description": "Whether to show the last-updated time on the shared page." }, "showTOC": { "type": "boolean", "description": "Whether to show a table of contents on the shared page." }, "views": { "type": "number", "description": "The number of times the shared page has been viewed.", "readOnly": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when this share was created", "readOnly": true }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "The user that created the share. Only returned to viewers with access to read the share; omitted from responses to unauthenticated viewers of a published share, and when the creating user has been deleted.", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when this share was edited", "readOnly": true }, "lastAccessedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when this share was last viewed. Only returned to workspace admins.", "readOnly": true } } }, "Star": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "index": { "type": "string", "description": "Index of the star in the list of stars." }, "documentId": { "type": "string", "description": "Unique identifier for the starred document.", "readOnly": true, "format": "uuid", "nullable": true }, "collectionId": { "type": "string", "description": "Unique identifier for the starred collection.", "readOnly": true, "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when this star was created", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when this star was last changed", "readOnly": true } } }, "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 workspace, it is usually auto-generated when the first SSO connection is made but can be changed if necessary." }, "description": { "type": "string", "nullable": true, "description": "A short description of this workspace." }, "avatarUrl": { "type": "string", "format": "uri", "description": "The URL for the image associated with this workspace, it will be displayed in the workspace switcher and in the top left of the knowledge base along with the name." }, "sharing": { "type": "boolean", "description": "Whether this workspace 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": { "$ref": "#/components/schemas/UserRole" }, "memberCollectionCreate": { "type": "boolean", "description": "Whether members are allowed to create new collections. If false then only admins can create collections." }, "memberTeamCreate": { "type": "boolean", "description": "Whether members are allowed to create new groups. If false then only admins can create groups." }, "documentEmbeds": { "type": "boolean", "description": "Whether this workspace has embeds in documents globally enabled. It can be disabled to reduce potential data leakage to third parties." }, "inviteRequired": { "type": "boolean", "description": "Whether an invite is required to join this workspace, 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 workspace 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 workspace's knowledge base can be accessed." }, "domain": { "type": "string", "nullable": true, "description": "The custom domain configured for this workspace, if any." }, "url": { "type": "string", "description": "The fully qualified URL at which this workspace's knowledge base can be accessed.", "readOnly": true, "format": "uri" }, "passkeysEnabled": { "type": "boolean", "description": "Whether passkey authentication is enabled for this workspace." }, "preferences": { "type": "object", "nullable": true, "description": "Workspace-level preference flags." }, "guidanceMCP": { "type": "string", "nullable": true, "description": "Guidance text provided to MCP integrations." } } }, "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 necessary.", "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." }, "color": { "type": "string", "description": "A color representing the user, used in the UI for avatars without an image.", "readOnly": true }, "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 necessary.", "format": "email", "readOnly": true }, "role": { "$ref": "#/components/schemas/UserRole" }, "isSuspended": { "type": "boolean", "description": "Whether this user has been suspended.", "readOnly": true }, "lastActiveAt": { "type": "string", "nullable": true, "description": "The last time this user made an API request, this value is updated at most every 5 minutes.", "readOnly": true, "format": "date-time" }, "timezone": { "type": "string", "nullable": true, "description": "The timezone this user has registered." }, "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" }, "updatedAt": { "type": "string", "description": "The date and time that this user was last updated.", "readOnly": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "description": "The date and time that this user was deleted, if applicable.", "readOnly": true, "format": "date-time" }, "invitedBy": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "The user that invited this user, if they were invited. Only included in responses to admin users.", "readOnly": true } } }, "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": { "$ref": "#/components/schemas/UserRole" } } }, "UserRole": { "type": "string", "enum": [ "admin", "member", "viewer", "guest" ] }, "CollectionStatus": { "type": "string", "enum": [ "archived" ] }, "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" }, "documentId": { "type": "string", "description": "Identifier for the associated document, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "collectionId": { "type": "string", "description": "Identifier for the associated collection, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "permission": { "$ref": "#/components/schemas/Permission" }, "createdById": { "type": "string", "description": "Identifier for the user who created this membership.", "readOnly": true, "format": "uuid" }, "sourceId": { "type": "string", "description": "Identifier for the membership this one was inherited from, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "index": { "type": "string", "description": "The position of the collection in the user's sidebar.", "nullable": true } } }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "format": "uuid" }, "query": { "type": "string", "description": "The user-provided search query", "example": "What is our hiring policy?", "readOnly": true }, "answer": { "type": "string", "description": "An answer to the query, if possible", "example": "Our hiring policy can be summarized as…", "readOnly": true }, "source": { "type": "string", "example": "app", "description": "The source of the query", "readOnly": true, "enum": [ "api", "app", "mcp" ] }, "createdAt": { "type": "string", "description": "The date and time that this object was created", "readOnly": true, "format": "date-time" } } }, "Policy": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object this policy references.", "format": "uuid", "readOnly": true }, "abilities": { "type": "object", "description": "The abilities that are allowed by this policy, if an array is returned then the individual ID's in the array represent the memberships that grant the ability.", "additionalProperties": { "$ref": "#/components/schemas/Ability" }, "example": { "read": true, "update": true, "delete": false } } } }, "Ability": { "description": "A single permission granted by a policy", "example": true, "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "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" }, "documentId": { "type": "string", "description": "Identifier for the associated document, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "collectionId": { "type": "string", "description": "Identifier for the associated collection, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "permission": { "$ref": "#/components/schemas/Permission" }, "sourceId": { "type": "string", "description": "Identifier for the membership this one was inherited from, if any.", "readOnly": true, "format": "uuid", "nullable": true } } }, "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" }, "documentId": { "type": "string", "description": "Identifier for the associated document, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "collectionId": { "type": "string", "description": "Identifier for the associated collection, if any.", "readOnly": true, "format": "uuid", "nullable": true }, "permission": { "$ref": "#/components/schemas/Permission" }, "sourceId": { "type": "string", "description": "Identifier for the membership this one was inherited from, if any.", "readOnly": true, "format": "uuid", "nullable": true } } }, "Template": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the object.", "readOnly": true, "format": "uuid" }, "url": { "type": "string", "description": "A URL path to access the template.", "readOnly": true }, "urlId": { "type": "string", "description": "A short unique identifier for the template used in URLs.", "readOnly": true }, "title": { "type": "string", "description": "The title of the template." }, "data": { "type": "object", "description": "The body of the template as a Prosemirror document." }, "icon": { "type": "string", "description": "An emoji to use as the template icon.", "nullable": true }, "color": { "type": "string", "description": "The color of the template icon in hex format.", "nullable": true }, "fullWidth": { "type": "boolean", "description": "Whether the template should be displayed full width." }, "collectionId": { "type": "string", "description": "Identifier for the associated collection, if any.", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time that the template was created.", "readOnly": true, "format": "date-time" }, "createdBy": { "$ref": "#/components/schemas/User" }, "updatedAt": { "type": "string", "description": "The date and time that the template was last changed.", "readOnly": true, "format": "date-time" }, "updatedBy": { "$ref": "#/components/schemas/User" }, "deletedAt": { "type": "string", "description": "The date and time that the template was deleted.", "readOnly": true, "format": "date-time", "nullable": true }, "publishedAt": { "type": "string", "nullable": true, "description": "The date and time that the template was published.", "readOnly": true, "format": "date-time" } } }, "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 }, "userId": { "type": "string", "format": "uuid", "description": "Identifier of the user who viewed the document.", "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" } } } }, "RateLimited": { "description": "The request was rate limited.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "rate_limit_exceeded" }, "status": { "type": "number", "example": 429 } } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds in the future to retry the request, if rate limited." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "The maximum requests available in the current duration." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "How many requests are left in the current duration." }, "RateLimit-Reset": { "schema": { "type": "string" }, "description": "Timestamp in the future the duration will reset." } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://app.getoutline.com/oauth/authorize", "tokenUrl": "https://app.getoutline.com/oauth/token", "refreshUrl": "https://app.getoutline.com/oauth/token", "scopes": { "read": "Read access", "write": "Write access" } } } } } } }