The maximum requests available in the current duration.

How many requests are left in the current duration.

Timestamp in the future the duration will reset.

Seconds in the future to retry the request, if rate limited.

The API key is missing or otherwise invalid.

The current API key is not authorized to perform this action.

The request failed one or more validations.

Identifier for the associated document, if any.

The date and time that this object was archived

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 #

The date and time that this object was created

The date and time that this object was deleted

A description of the collection, may contain markdown formatting

A string that represents an icon in the outline-icons package or an emoji

The position of the collection in the sidebar

Whether public document sharing is enabled in this collection

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.

The date and time that this object was last changed

A short unique identifier that can be used to identify the collection instead of the UUID.

Identifier for the associated collection.

The document text that the comment is anchored to, only included if includeAnchorText=true.

The editor data representing this comment.

Identifier for the document this is related to.

Identifier for the comment this is a child of, if any.

Whether this data attribute is pinned to the top of documents.

Additional options for certain data attribute types.

An icon representing the data attribute from the outline-icons package.

Whether this document should be displayed in a full-width view.

Identifier for the document this is a child of, if any.

Whether this document is pinned in the collection

The date and time that this object was published

A number that is auto incrementing with every revision of the document that is saved

Unique identifier for the template this document was created from, if any

The text content of the document, contains markdown formatting

A short unique ID that can be used to identify the document as an alternative to the UUID

Unique identifier for the associated data attribute.

The date and time that this object attribute was last changed

The value of the data attribute for this document.

The ip address the action was performed from. This field is only returned when the `auditLog` boolean is true.

Identifier for the associated collection, if any

The date and time that this event was created

Additional unstructured data associated with the event

Equipment list

Identifier for the associated document, if any

Identifier for the object this event is associated with when it is not one of document, collection, or user.

The number of users that are members of the group

Date and time when this authentication was last used

Identifier for the associated OAuthClient.

A URL pointing to an image representing the OAuth client.

Date and time when this OAuth client was created

A short description of this OAuth client.

The name of the developer who created this OAuth client.

The URL of the developer who created this OAuth client.

Whether the OAuth client is available to other workspaces.

Date and time when this OAuth client was updated

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.

Unique identifier for the object this policy references.

Date and time when this revision was created

Body of the document, may contain markdown formatting

Date and time when this share was created

If to also give permission to view documents nested beneath this one.

Date and time when this share was last viewed

If true the share can be loaded without a user account.

Unique identifier for the starred collection.

Unique identifier for the starred document.

A hostname that user emails are restricted to

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.

Whether this workspace has collaborative editing in documents globally enabled.

If set then the referenced collection is where users will be redirected to after signing in instead of the Home screen

Whether this workspace has embeds in documents globally enabled. It can be disabled to reduce potential data leakage to third parties.

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.

Whether an invite is required to join this workspace, if false users may join with a linked SSO provider.

Whether members are allowed to create new collections. If false then only admins can create collections.

The name of this workspace, it is usually auto-generated when the first SSO connection is made but can be changed if necessary.

Whether this workspace has share links globally enabled. If this value is false then all sharing UI and APIs are disabled.

Represents the subdomain at which this workspace's knowledge base can be accessed.

The fully qualified URL at which this workspace's knowledge base can be accessed.

Identifier for the associated collection, if any.

The color of the template icon in hex format.

The date and time that the template was created.

The body of the template as a Prosemirror document.

The date and time that the template was deleted.

Whether the template should be displayed full width.

The date and time that the template was published.

The date and time that the template was last changed.

A short unique identifier for the template used in URLs.

The editing mode for text updates to a document.

The URL for the image associated with this user, it will be displayed in the application UI and email notifications.

The date and time that this user first signed in or was invited as a guest.

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.

The last time this user made an API request, this value is updated at most every 5 minutes.

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.

The number of times the user has viewed the document.

When the document was first viewed by the user

When the document was last viewed by the user

# 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.


BSD-3-Clause

Outline API

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.

Deleting an attachment is permanent. It will not delete references or links to the attachment that may exist in your documents.

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.

Retrieve authentication details for the current API key

This method allows you to give all members in a group access to a collection.

This method allows you to add a user membership to the specified collection.

Create a new collection with the specified name, description, icon, color, and permission settings. Collections are used to organize documents.

Delete a collection and all of its documents. This action can’t be undone so please be careful.

Returns the document structure of a collection as a tree of navigation nodes, representing the hierarchy of documents within the collection.

Retrieve a collections document structure

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.

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.

This method allows you to list a collections group memberships. This is the list of groups that have been given access to the collection.

Retrieve the details of a collection by its unique identifier.

List all collections that the authenticated user has access to.

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.

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.

This method allows you to remove a user from the specified collection.

Update an existing collection's properties such as name, description, icon, color, sharing settings, or permission level.

Add a comment or reply to a document, either `data` or `text` is required.

Deletes a comment. If the comment is a top-level comment, all its children will be deleted as well.

This method will list all comments matching the given properties.

Create a new data attribute. Only admins can create data attributes.

Business

Enterprise

Delete a data attribute. Only admins can delete data attributes.

Retrieve a data attribute by its unique identifier.

Update an existing data attribute. Only admins can update data attributes. Note that the dataType cannot be changed after creation.

This method allows you to give all members in a group access to a document.

This method allows you to add a user membership to the specified document.

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.

Cloud

Archiving a document allows outdated information to be moved out of sight whilst retaining the ability to optionally search and restore it later.

This method will list all archived documents belonging to the workspace that the current user has access to.

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.

Deleting a document moves it to the trash. If not restored within 30 days it is permanently deleted.

This method will list all deleted documents belonging to the workspace that the current user has access to.

This method returns the nested document structure (tree) for the children of the specified document.

This method will list all draft documents belonging to the current user.

This method allows you to duplicate an existing document and optionally all of its child documents.

Permanently delete all documents in the trash. This action is irreversible. Only available to admin users.

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.

This method allows you to list a document's group memberships.

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.

Retrieve a document by its `UUID`, `urlId`, or `shareId`. At least one of these parameters must be provided.

This method will list all published documents and draft documents belonging to the current user.

Users with direct membership to a document. To list all users with access to a document use `documents.users`.

Move a document to a new location or collection. If no parent document is provided, the document will be moved to the collection root.

This method allows you to revoke all members in a group access to a document.

This method allows you to remove a user membership from the specified document.

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.

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.

This method allows you to search document titles with keywords. Unlike documents.search, this only searches titles and returns faster results.

This method allows you to create a new template using an existing document as the basis

Unpublishing a document moves it back to a draft status and out of the collection.

This method allows you to modify an already created document

All users with access to a document. To list only users with direct membership to the document use `documents.memberships`

This method will list all documents recently viewed by the current user.

Events are an audit trail of important events that happen in the knowledge base.

Delete a file operation and its associated files. This is useful for cleaning up completed or failed import/export operations.

Retrieve the details and current status of a file operation by its unique identifier. File operations represent long-running import or export tasks.

List all file operations for the current workspace, filtered by type (import or export).

Load the resulting file from where it is stored based on the id. A temporary, signed url with embedded credentials is generated on demand.

This method allows you to add a user to the specified group.

Create a new group with the specified name. Groups can be used to organize users and assign collection permissions to multiple users at once.

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.

Retrieve the details of a group by its unique identifier, including its name and member count.

List all groups in the workspace. Groups are used to organize users and manage permissions for collections.

List and filter all the members in a group.

This method allows you to remove a user from the group.

Update an existing group's name. The group is identified by its unique identifier.

Revoke an OAuth authentication, removing the third-party application's access to the user's account.

List all OAuth authentications for the current user. These represent the third-party applications that the user has authorized to access their account.

Create a new OAuth client application that can be used to authenticate users and access the API on their behalf.

Permanently delete an OAuth client and revoke all associated access tokens. This action cannot be undone.

To retrieve information about an OAuth client you must pass either an `id` or a `clientId`.

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.

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.

Update an existing OAuth client's properties such as name, description, redirect URIs, or published status.

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.

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.

Creates a new share link that can be used by to access a document. If you request multiple shares for the same document with the same API key, the same share object will be returned. By default all shares are unpublished.

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.

Makes the share link inactive so that it can no longer be used to access the document.

Allows changing an existing share's published status, which removes authentication and makes it available to anyone with the link.

Stars a document or collection so it appears in the users sidebar. One of either `documentId` or `collectionId` must be provided.

Remove a star from a document, removing it from the user's starred documents list in the sidebar.

List all starred documents for the authenticated user. Stars allow users to bookmark important documents for quick access in the sidebar.

Update the position of a starred document in the sidebar. The index parameter determines the display order relative to other starred documents.

Create a new template that can be used as a starting point for new documents. Templates can optionally be scoped to a specific collection.

Delete a template by its unique identifier. This will soft-delete the template, it can be restored later.

Create a copy of an existing template. Optionally override the title and target collection.

Retrieve a template by its unique identifier.

List all templates available to the current user. Optionally filter by collection. Templates not associated with a collection are workspace-wide.

Restore a previously deleted template by its unique identifier.

Update an existing template by its unique identifier.

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.

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.

Retrieve the details of a user by their unique identifier, including their name, email, avatar, and role within the workspace.

Send email invitations to one or more users to join the workspace. Invitations include a link to create an account and join the workspace.

List and filter all the users in the workspace

Suspending a user prevents the user from signing in. Users that are suspended are also not counted against billing totals in the hosted version.

Update a users name or avatar. If no `id` is passed then the user associated with the authentication will be updated by default.