From 733a5a582c6d33a4f7152c7e79896cad07648705 Mon Sep 17 00:00:00 2001 From: psavarmattas Date: Fri, 14 Aug 2026 01:59:19 +0100 Subject: [PATCH] docs(architecture): convert vendored OpenAPI spec to a git submodule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Was a flat copy — a submodule against outline/openapi tracks a real pinned commit and can be refreshed with a normal git command (git submodule update --remote) instead of manually re-downloading and overwriting a file. --- .gitmodules | 3 + docs/ARCHITECTURE.md | 4 +- docs/reference/outline-openapi | 1 + docs/reference/outline-openapi-spec3.yml | 7581 ---------------------- 4 files changed, 7 insertions(+), 7582 deletions(-) create mode 100644 .gitmodules create mode 160000 docs/reference/outline-openapi delete mode 100644 docs/reference/outline-openapi-spec3.yml diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..8c99c45 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/reference/outline-openapi"] + path = docs/reference/outline-openapi + url = https://github.com/outline/openapi.git diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 313b06d..4fea49f 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -8,7 +8,9 @@ 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. +- **Full OpenAPI spec, vendored as a git submodule**: [`docs/reference/outline-openapi`](reference/outline-openapi) → [`outline/openapi`](https://github.com/outline/openapi), spec at `docs/reference/outline-openapi/spec3.yml`. 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). + - Fresh clone: `git submodule update --init --recursive`. + - Refresh to upstream's latest: `git submodule update --remote docs/reference/outline-openapi`. ## 2. Realtime collaboration transport diff --git a/docs/reference/outline-openapi b/docs/reference/outline-openapi new file mode 160000 index 0000000..43d990d --- /dev/null +++ b/docs/reference/outline-openapi @@ -0,0 +1 @@ +Subproject commit 43d990d5ec250e9f8daa05962d68b099128d2895 diff --git a/docs/reference/outline-openapi-spec3.yml b/docs/reference/outline-openapi-spec3.yml deleted file mode 100644 index 89636c3..0000000 --- a/docs/reference/outline-openapi-spec3.yml +++ /dev/null @@ -1,7581 +0,0 @@ ---- -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