openapi: 3.0.0 info: title: Outline AccessRequests Documents API description: "# Introduction\n\nThe Outline API is structured in an RPC style. It enables you to\nprogramatically interact with all aspects of Outline’s data – in fact, the\nmain application is built on exactly the same API.\n\nThe API structure is available as an\n[openapi specification](https://github.com/outline/openapi) if that’s your\njam – it can be used to generate clients for most programming languages.\n\n# Making requests\n\nOutline’s API follows simple RPC style conventions where each API endpoint is\na `POST` method on `https://app.getoutline.com/api/:method`. Only HTTPS is\nsupported and all response payloads are JSON.\n\nWhen making `POST` requests, request parameters are parsed depending on\nContent-Type header. To make a call using JSON payload, you must pass\nContent-Type: application/json header, here’s an example using CURL:\n\n```\ncurl https://app.getoutline.com/api/documents.info \\\n-X 'POST' \\\n-H 'authorization: Bearer MY_API_KEY' \\\n-H 'content-type: application/json' \\\n-H 'accept: application/json' \\\n-d '{\"id\": \"outline-api-NTpezNwhUP\"}'\n```\n\nOr, with JavaScript:\n\n```javascript\nconst response = await fetch(\"https://app.getoutline.com/api/documents.info\", {\n method: \"POST\",\n headers: {\n Accept: \"application/json\",\n \"Content-Type\": \"application/json\",\n Authorization: \"Bearer MY_API_KEY\"\n }\n})\n\nconst body = await response.json();\nconst document = body.data;\n```\n\n# Authentication\n\n## API key\n\nYou can create new API keys under **Settings => API & Apps**. Be\ncareful when handling your keys as they allow full access to your data,\nyou should treat them like passwords and they should never be committed to\nsource control.\n\n### Usage\n\nTo authenticate with API, you should supply the API key as a \"Bearer\" token in the `Authorization` header\n(`Authorization: Bearer YOUR_API_KEY`).\n\nAPI keys can be revoked at any time by the creating user or an administrator of the workspace. If an API\nkey is revoked, any requests made with that key will return a `401 Unauthenticated` response.\n\n### Format\n\nAll API keys always begin with `ol_api_` followed by a random string of 38 letters and numbers.\n\n## OAuth 2.0\n\nOAuth 2.0 is a widely used protocol for authorization and authentication. It allows users\nto grant third-party _or_ internal applications access to their resources without sharing\ntheir credentials. To use OAuth 2.0 you need to follow these steps:\n\n1. Register your application under **Settings => Applications**\n2. Obtain an access token by exchanging the client credentials for an access token\n3. Use the access token to authenticate requests to the API\n\nSome API endpoints allow unauthenticated requests for public resources and\nthey can be called without authentication.\n\n# Scopes\n\nScopes are used to limit the access of an API key or application to specific resources. For example,\nan application may only need access to read documents, but not write them. Scopes can be global in\nthe case of `read` and `write` scopes, scoped to a namespace, scoped to an API endpoint, or use\nwildcard scopes like `documents.*`. Some examples of scopes that can be used are:\n\n## Global\n\n- `read`: Allows all read actions\n- `write`: Allows all read and write actions\n\n## Namespaced\n\n- `documents:read`: Allows all document read actions\n- `collections:write`: Allows all collection write actions\n\n## Endpoints\n\n- `documents.info`: Allows only one specific API method\n- `documents.*`: Allows all document API methods\n- `users.*`: Allows all user API methods\n\n# Errors\n\nAll successful API requests will be returned with a 200 or 201 status code\nand `ok: true` in the response payload. If there’s an error while making the\nrequest, the appropriate status code is returned with the error message:\n\n```\n{\n \"ok\": false,\n \"error\": \"Not Found\"\n}\n```\n\n# Pagination\n\nMost top-level API resources have support for \"list\" API methods. For instance,\nyou can list users, documents, and collections. These list methods share\ncommon parameters, taking both `limit` and `offset`.\n\nResponses will echo these parameters in the root `pagination` key, and also\ninclude a `nextPath` key which can be used as a handy shortcut to fetch the\nnext page of results. For example:\n\n```\n{\n ok: true,\n status: 200,\n data: […],\n pagination: {\n limit: 25,\n offset: 0,\n nextPath: \"/api/documents.list?limit=25&offset=25\"\n }\n}\n```\n\n# Rate limits\n\nLike most APIs, Outline has rate limits in place to prevent abuse. Endpoints\nthat mutate data are more restrictive than read-only endpoints. If you exceed\nthe rate limit for a given endpoint, you will receive a `429 Too Many Requests`\nstatus code.\n\nThe response will include a `Retry-After` header that indicates how many seconds\nyou should wait before making another request.\n\n# Policies\n\nMost API resources have associated \"policies\", these objects describe the\ncurrent authentications authorized actions related to an individual resource. It\nshould be noted that the policy \"id\" is identical to the resource it is\nrelated to, policies themselves do not have unique identifiers.\n\nFor most usecases of the API, policies can be safely ignored. Calling\nunauthorized methods will result in the appropriate response code – these can\nbe used in an interface to adjust which elements are visible.\n" version: 0.1.0 contact: email: hello@getoutline.com license: name: BSD-3-Clause url: https://github.com/outline/openapi/blob/main/LICENSE servers: - url: https://app.getoutline.com/api description: Cloud hosted - url: https://{domain}/api description: Self-hosted on your own server variables: domain: default: example.com security: - BearerAuth: [] - OAuth2: - read - write tags: - name: 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. ' paths: /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, csv, tsv, and html format 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, or PDF format. The response format is determined by the Accept header. 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 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 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 components: responses: 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 Validation: description: The request failed one or more validations. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found. 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' Unauthorized: description: The current API key is not authorized to perform this action. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Document: type: object properties: id: type: string description: Unique identifier for the object. readOnly: true format: uuid collectionId: type: string description: Identifier for the associated collection. format: uuid nullable: true parentDocumentId: type: string description: Identifier for the document this is a child of, if any. format: uuid nullable: true title: type: string description: The title of the document. example: Welcome to Acme Inc fullWidth: type: boolean description: Whether this document should be displayed in a full-width view. icon: type: string nullable: true description: An emoji or icon associated with the document. example: 🎉 color: type: string nullable: true description: The color of the document icon in hex format. text: type: string description: The text content of the document, contains markdown formatting example: … data: type: object nullable: true description: The body of the document as a Prosemirror document, returned in place of text when requested. url: type: string description: A URL path to access the document. readOnly: true urlId: type: string description: A short unique ID that can be used to identify the document as an alternative to the UUID example: hDYep1TPAM collaboratorIds: type: array description: Identifiers of users who have edited the document. items: type: string format: uuid tasks: type: object description: Task completion counts for the document. properties: completed: type: number total: type: number templateId: type: string description: Unique identifier for the template this document was created from, if any format: uuid revision: type: number description: A number that is auto incrementing with every revision of the document that is saved readOnly: true createdAt: type: string description: The date and time that this object was created readOnly: true format: date-time createdBy: $ref: '#/components/schemas/User' updatedAt: type: string description: The date and time that this object was last changed readOnly: true format: date-time updatedBy: $ref: '#/components/schemas/User' publishedAt: type: string nullable: true description: The date and time that this object was published readOnly: true format: date-time dataAttributes: type: array nullable: true items: $ref: '#/components/schemas/DocumentDataAttribute' archivedAt: type: string nullable: true description: The date and time that this object was archived readOnly: true format: date-time deletedAt: type: string nullable: true description: The date and time that this object was deleted readOnly: true format: date-time Ability: description: A single permission granted by a policy example: true oneOf: - type: array items: type: string - type: boolean Pagination: type: object properties: offset: type: number example: 0 limit: type: number example: 25 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 createdAt: type: string description: The date and time that this object was created readOnly: true format: date-time UserRole: type: string enum: - admin - member - viewer - guest 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 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 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 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 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' Sorting: type: object properties: sort: type: string example: updatedAt direction: type: string example: DESC enum: - ASC - DESC Permission: type: string enum: - read - read_write 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. 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 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 Error: type: object properties: ok: type: boolean example: false error: type: string message: type: string status: type: number data: type: object 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 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 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 headers: 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. Retry-After: schema: type: integer description: Seconds in the future to retry the request, if rate limited. 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