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

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

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

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 team, it will be displayed in the team switcher and in the top left of the knowledge base along with the name.

Whether this team 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 team has embeds in documents globally enabled. It can be disabled to reduce potential data leakage to third parties.

Whether this team 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 team, 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 team, it is usually auto-generated when the first SSO connection is made but can be changed if neccessary.

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

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

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

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

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

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 give access to all of your documents,
you should treat them like passwords and they should never be committed to
source control.

To authenticate with API, you should supply the API key as the `Authorization` header
(`Authorization: Bearer YOUR_API_KEY`).

## 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, specific to an API endpoint like
`documents.read` and `documents.create`, or use wildcard scopes like `documents.*`.

Some examples of scopes that can be used are:

- `documents.read`: Allows reading documents
- `documents.write`: Allows writing documents
- `documents.*`: Allows all document-related actions
- `users.*`: Allows all user-related actions
- `read`: Allows all read actions
- `write`: Allows all write actions

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


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

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

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 all documents in and their attachments. 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.

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.

This method will list all comments matching the given properties.

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.

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 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 permenantly deleted.

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

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.

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 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 teams documents with keywords. Note that search results will be restricted to those accessible by the current access token.

This method allows you to createa 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.

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.

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.

List and filter all the members in a group.

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

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.

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

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

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.

List and filter all the users in the team

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.

Change the role of a user, only available to admin authorization.

Creates a new view for a document. This is documented in the interests of thoroughness however it is recommended that views are not created from outside of the Outline UI.

List all users that have viewed a document and the overall view count.