diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 60d8d05..313b06d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -8,6 +8,7 @@ Deeper technical reference backing `CLAUDE.md`. Update this as decisions are mad - **Auth**: `Authorization: Bearer ` header. Keys are created per-user under Settings → API Keys on the Outline instance. Store in Keychain, scope a dedicated key to this app rather than reusing a personal one. - **Core endpoints to wrap first**: `documents.info`, `documents.list`, `documents.search`, `documents.create`, `documents.update`, `collections.list`, `collections.info`, `users.info`. - Full reference: your instance's `/developers` page (same docs as getoutline.com/developers, versioned per Outline release — check against your self-hosted version, not just the public docs). +- **Full OpenAPI spec, vendored**: [`docs/reference/outline-openapi-spec3.yml`](reference/outline-openapi-spec3.yml) — pulled from [`outline/openapi`](https://github.com/outline/openapi). Check this before adding any new `OutlineAPIClient` method — read the exact request/response shape here rather than guessing from prose docs. It's already caught real mismatches twice: `documents.search`'s `sort` field rejects `"relevance"` as an explicit value even though the field is documented as accepting it (server only treats it as the implicit default when omitted), and `documents.search_titles` doesn't work against this self-hosted instance at all despite being in the spec (see `DocumentTitleSearchViewModel`'s doc comment — likely server version drift, matching the risk already called out below). Re-pull from the source repo periodically since it can drift from what's actually deployed. ## 2. Realtime collaboration transport diff --git a/docs/reference/outline-openapi-spec3.yml b/docs/reference/outline-openapi-spec3.yml new file mode 100644 index 0000000..89636c3 --- /dev/null +++ b/docs/reference/outline-openapi-spec3.yml @@ -0,0 +1,7581 @@ +--- +openapi: 3.0.0 +info: + title: Outline API + description: | + # Introduction + + The Outline API is structured in an RPC style. It enables you to + programatically interact with all aspects of Outline’s data – in fact, the + main application is built on exactly the same API. + + The API structure is available as an + [openapi specification](https://github.com/outline/openapi) if that’s your + jam – it can be used to generate clients for most programming languages. + + # Making requests + + Outline’s API follows simple RPC style conventions where each API endpoint is + a `POST` method on `https://app.getoutline.com/api/:method`. Only HTTPS is + supported and all response payloads are JSON. + + When making `POST` requests, request parameters are parsed depending on + Content-Type header. To make a call using JSON payload, you must pass + Content-Type: application/json header, here’s an example using CURL: + + ``` + curl https://app.getoutline.com/api/documents.info \ + -X 'POST' \ + -H 'authorization: Bearer MY_API_KEY' \ + -H 'content-type: application/json' \ + -H 'accept: application/json' \ + -d '{"id": "outline-api-NTpezNwhUP"}' + ``` + + Or, with JavaScript: + + ```javascript + const response = await fetch("https://app.getoutline.com/api/documents.info", { + method: "POST", + headers: { + Accept: "application/json", + "Content-Type": "application/json", + Authorization: "Bearer MY_API_KEY" + } + }) + + const body = await response.json(); + const document = body.data; + ``` + + # Authentication + + ## API key + + You can create new API keys under **Settings => API & Apps**. Be + careful when handling your keys as they allow full access to your data, + you should treat them like passwords and they should never be committed to + source control. + + ### Usage + + To authenticate with API, you should supply the API key as a "Bearer" token in the `Authorization` header + (`Authorization: Bearer YOUR_API_KEY`). + + API keys can be revoked at any time by the creating user or an administrator of the workspace. If an API + key is revoked, any requests made with that key will return a `401 Unauthenticated` response. + + ### Format + + All API keys always begin with `ol_api_` followed by a random string of 38 letters and numbers. + + ## OAuth 2.0 + + OAuth 2.0 is a widely used protocol for authorization and authentication. It allows users + to grant third-party _or_ internal applications access to their resources without sharing + their credentials. To use OAuth 2.0 you need to follow these steps: + + 1. Register your application under **Settings => Applications** + 2. Obtain an access token by exchanging the client credentials for an access token + 3. Use the access token to authenticate requests to the API + + Some API endpoints allow unauthenticated requests for public resources and + they can be called without authentication. + + # Scopes + + Scopes are used to limit the access of an API key or application to specific resources. For example, + an application may only need access to read documents, but not write them. Scopes can be global in + the case of `read` and `write` scopes, scoped to a namespace, scoped to an API endpoint, or use + wildcard scopes like `documents.*`. Some examples of scopes that can be used are: + + ## Global + + - `read`: Allows all read actions + - `write`: Allows all read and write actions + + ## Namespaced + + - `documents:read`: Allows all document read actions + - `collections:write`: Allows all collection write actions + + ## Endpoints + + - `documents.info`: Allows only one specific API method + - `documents.*`: Allows all document API methods + - `users.*`: Allows all user API methods + + # Errors + + All successful API requests will be returned with a 200 or 201 status code + and `ok: true` in the response payload. If there’s an error while making the + request, the appropriate status code is returned with the error message: + + ``` + { + "ok": false, + "error": "Not Found" + } + ``` + + # Pagination + + Most top-level API resources have support for "list" API methods. For instance, + you can list users, documents, and collections. These list methods share + common parameters, taking both `limit` and `offset`. + + Responses will echo these parameters in the root `pagination` key, and also + include a `nextPath` key which can be used as a handy shortcut to fetch the + next page of results. For example: + + ``` + { + ok: true, + status: 200, + data: […], + pagination: { + limit: 25, + offset: 0, + nextPath: "/api/documents.list?limit=25&offset=25" + } + } + ``` + + # Rate limits + + Like most APIs, Outline has rate limits in place to prevent abuse. Endpoints + that mutate data are more restrictive than read-only endpoints. If you exceed + the rate limit for a given endpoint, you will receive a `429 Too Many Requests` + status code. + + The response will include a `Retry-After` header that indicates how many seconds + you should wait before making another request. + + # Policies + + Most API resources have associated "policies", these objects describe the + current authentications authorized actions related to an individual resource. It + should be noted that the policy "id" is identical to the resource it is + related to, policies themselves do not have unique identifiers. + + For most usecases of the API, policies can be safely ignored. Calling + unauthorized methods will result in the appropriate response code – these can + be used in an interface to adjust which elements are visible. + 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 + they do not currently have permission to view. The request can be approved + or dismissed by a user with permission to share the document. + - name: Attachments + description: | + `Attachments` represent a file uploaded to cloud storage. They are created + before the upload happens from the client and store all the meta information + such as file type, size, and location. + - name: Auth + description: | + `Auth` represents the current API Keys authentication details. It can be + used to check that a token is still valid and load the IDs for the current + user and workspace. + - name: Collections + description: | + `Collections` represent grouping of documents in the knowledge base, they + offer a way to structure information in a nested hierarchy and a level + at which read and write permissions can be granted to individual users or + groups of users. + - name: Comments + description: | + `Comments` represent a comment either on a selection of text in a document + or on the document itself. + - name: DataAttributes + description: | + `DataAttributes` represent custom metadata fields that can be attached to + documents. They allow workspaces to add structured data like status, priority, + or any other custom properties to their documents. + - name: Documents + description: | + `Documents` are what everything else revolves around. A document represents + a single page of information and always returns the latest version of the + content. Documents are stored in [Markdown](https://spec.commonmark.org/) + formatting. + - name: Events + description: | + `Events` represent an artifact of an action. Whether it is creating a user, + editing a document, changing permissions, or any other action – an event + is created that can be used as an audit trail or activity stream. + - name: FileOperations + description: | + `FileOperations` represent background jobs for importing or exporting files. + You can query the file operation to find the state of progress and any + resulting output. + - name: Groups + description: | + `Groups` represent a list of users that logically belong together, for + example there might be groups for each department in your organization. + Groups can be granted access to collections with read or write permissions. + - name: OAuthClients + description: | + `OAuthClients` represent OAuth clients that can be used to authenticate + users with third-party services. + - name: OAuthAuthentications + description: | + `OAuthAuthentications` represent individual scoped authentications between + Outline and an `OAuthClient`. + - name: Revisions + description: | + `Revisions` represent a snapshot of a document at a point in time. They + are used to keep track of editing and collaboration history – a document + can also be restored to a previous revision if necessary. + - name: Shares + description: | + `Shares` represent authorization to view a document without being a member + of the workspace. Shares are created in order to give access to documents publicly. + Each user that shares a document will have a unique share object. + - name: Stars + description: | + `Stars` represent a favorited document or collection in the application sidebar. + Each user has their own collection of starred items. + - name: Users + description: | + `Users` represent an individual with access to the knowledge base. Users + can be created automatically when signing in with SSO or when a user is + invited via email. + - name: Templates + description: | + `Templates` represent reusable document templates that can be used as a + starting point when creating new documents. Templates can be scoped to a + specific collection or available workspace-wide. + - name: Views + description: | + `Views` represent a compressed record of an individual users views of a + document. Individual views are not recorded but a first, last and total + is kept per user. +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 + original collection's settings – icon, color, permission, sharing, and + sorting – are preserved on the copy. Draft and archived documents are + not duplicated. Document duplication runs asynchronously in the + background, so the copy may initially be returned before all of its + documents have been created. + 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: + collectionId: + type: string + format: uuid + description: Optionally filter to a specific collection + userId: + type: string + format: uuid + description: Optionally filter to documents created by a specific user + backlinkDocumentId: + type: string + format: uuid + parentDocumentId: + type: string + format: uuid + statusFilter: + type: array + items: + type: string + enum: + - draft + - archived + - published + description: Document statuses to include in results + 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 + collectionId: + type: string + format: uuid + description: Filter to a specific collection + userId: + type: string + format: uuid + description: Filter results based on user + documentId: + type: string + format: uuid + description: Filter results based on content within a document and its children + statusFilter: + type: array + items: + type: string + enum: + - draft + - archived + - published + description: Document statuses to include in results + dateFilter: + type: string + description: + Any documents that have not been updated within the + specified period will be filtered out + 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 + 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: array + description: Document statuses to include in results + items: + type: string + enum: + - draft + - archived + - published + 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 + 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 + 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" + "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" + 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 + 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 + 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: "\U0001F389" + 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. + 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