Outline Documents API

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.
                   

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/outline/refs/heads/main/openapi/outline-documents-api-openapi.yml