Documentation

The API is the heart and soul of Outline.

As developers, it’s our mission to make the API as great as possible. While Outline is still in public beta, we might make small adjustments, including breaking changes to the API.

Making requests

Outline’s API follows simple RPC style conventions where each API endpoint is a method on https://www.getoutline.com/api/<METHOD>. Both GET and POST methods are supported but it’s recommeded that you make all call using POST. Only HTTPS is supported in production.

For GET requests query string parameters are expected (e.g./api/document.info?id=...&token=...). When making POST requests, request parameters are parsed depending on Content-Type header. To make a call using JSON payload, one must pass Content-Type: application/json header:

Example POST request:

curl https://www.getoutline.com/api/documents.info
  -X POST
  -H 'authorization: Bearer API_KEY'
  -H 'content-type: application/json'
  -H 'accept: application/json'
  -d '{"id": "outline-api-NTpezNwhUP"}'

Example GET request:

curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY

Authentication

To access private API endpoints, you must provide a valid API key. You can create new API keys in your account settings. Be careful when handling your keys as they give access to all of your documents.

To authenticate with Outline API, you can supply the API key as a header (Authorization: Bearer YOUR_API_KEY) or as part of the payload using token parameter. If you’re making GET requests, header based authentication is recommended so that your keys don’t leak into logs.

Some API endpoints allow unauhenticated requests for public resources and they can be called without an API key.

Errors

All successful API requests will be returned with 200 status code and ok: true in the response payload. If there’s an error while making the request, appropriate status code is returned with the error message:

{
  "ok": false,
  "error: "Not Found"
}

Methods

auth.info - Get current auth

This method returns the user and team info for the user identified by the token.

HTTP request & arguments

https://www.getoutline.com/api/auth.info

ArgumentRequiredDescription
tokenrequiredAuthentication token

users.info - Get current user

This method returns the profile info for the user identified by the token.

HTTP request & arguments

https://www.getoutline.com/api/users.info

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredCollection id

users.s3Upload - Get S3 upload credentials

You can upload small files and images as part of your documents. All files are stored using Amazon S3. Instead of uploading files to Outline, you need to upload them directly to S3 with special credentials which can be obtained through this endpoint.

HTTP request & arguments

https://www.getoutline.com/api/users.s3Upload

ArgumentRequiredDescription
tokenrequiredAuthentication token
filenamerequiredFilename of the uploaded file
kindrequiredMimetype of the document
sizerequiredFilesize of the document

users.promote - Promote a new admin user

Promote a user to be a team admin. This endpoint is only available for admin users.

HTTP request & arguments

https://www.getoutline.com/api/users.promote

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
idrequiredUser ID to be promoted

users.demote - Demote existing admin user

Demote existing team admin if there are more than one as one admin is always required. This endpoint is only available for admin users.

HTTP request & arguments

https://www.getoutline.com/api/users.demote

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
idrequiredUser ID to be demoted

users.suspend - Suspend user account

Admin can suspend users to reduce the number of accounts on their billing plan or prevent them from accessing documention.

HTTP request & arguments

https://www.getoutline.com/api/users.suspend

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
idrequiredUser ID to be suspended

users.activate - Activate a suspended user account

Admin can re-active a suspended user. This will update the billing plan and re-enable their access to the documention.

HTTP request & arguments

https://www.getoutline.com/api/users.activate

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
idrequiredUser ID to be activated

collections.list - List your document collections

List all your document collections.

HTTP request & arguments

https://www.getoutline.com/api/collections.list

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

collections.info - Get a document collection

Returns detailed information on a document collection.

HTTP request & arguments

https://www.getoutline.com/api/collections.info

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredCollection id

collections.create - Create a document collection

Creates a new document collection.

HTTP request & arguments

https://www.getoutline.com/api/collections.create

ArgumentRequiredDescription
tokenrequiredAuthentication token
namerequiredCollection name
descriptionoptionalShort description for the collection

collections.update - Update a collection

This method allows you to modify already created document.

HTTP request & arguments

https://www.getoutline.com/api/collections.update

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredCollection ID
nameoptionalName for the collection
coloroptionalCollection color in hex form (e.g. #E1E1E1)

collections.delete - Delete a collection

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

HTTP request & arguments

https://www.getoutline.com/api/collections.delete

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredCollection ID

documents.list - List your documents

List all published documents.

HTTP request & arguments

https://www.getoutline.com/api/documents.list

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
collectionoptionalCollection ID to filter by

documents.drafts - List your draft documents

List all your draft documents.

HTTP request & arguments

https://www.getoutline.com/api/documents.drafts

documents.info - Get a document

This method returns information for a document with a specific ID. The following identifiers are allowed:

  • UUID - id field of the document
  • URI identifier - Human readable identifier used in Outline URLs (e.g. outline-api-i48ZEZc5zjXndcP)

HTTP request & arguments

https://www.getoutline.com/api/documents.info

ArgumentRequiredDescription
tokenrequiredAuthentication token
idoptionalDocument ID or URI identifier
shareIdoptionalAn active shareId

documents.search - Search documents

This methods allows you to search all of your documents with keywords.

HTTP request & arguments

https://www.getoutline.com/api/documents.search

ArgumentRequiredDescription
tokenrequiredAuthentication token
queryrequiredSearch query

documents.create - Create a new document

This method allows you to publish a new document under an existing collection. By default a document is set to the parent collection root. If you want to create a subdocument, you can pass parentDocument to set parent document.

HTTP request & arguments

https://www.getoutline.com/api/documents.create

ArgumentRequiredDescription
tokenrequiredAuthentication token
collectionrequiredID of the collection to which the document is created
titlerequiredTitle for the document
textrequiredContent of the document in Markdow
parentDocumentoptionalID of the parent document within the collection
publishoptionaltrue by default. Pass false to create a draft.

documents.update - Update a document

This method allows you to modify already created document.

HTTP request & arguments

https://www.getoutline.com/api/documents.update

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier
titleoptionalTitle for the document
textoptionalContent of the document in Markdown
publishoptionalPass true to publish a draft.
autosaveoptionalPass true to signify an autosave. This skips creating a revision.
doneoptionalPass true to signify the end of an editing session. This will trigger documents.update hooks.

documents.move - Move document in a collection

Move a document into a new location inside the collection. This is easily done by defining the parent document ID. If no parent document is provided, the document will be moved to the collection root.

HTTP request & arguments

https://www.getoutline.com/api/documents.move

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier
parentDocumentoptionalID of the new parent document (if any)

documents.delete - Delete a document

Delete a document and all of its child documents if any.

HTTP request & arguments

https://www.getoutline.com/api/documents.delete

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.info - Get a document

Get a document with its ID or URL identifier from user’s collections.

HTTP request & arguments

https://www.getoutline.com/api/documents.info

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.restore - Restore a previous revision

Restores a document to a previous revision by creating a new revision with the contents of the given revisionId.

HTTP request & arguments

https://www.getoutline.com/api/documents.restore

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier
revisionIdrequiredRevision ID to restore to

documents.pin - Pin a document

Pins a document to the collection home. The pinned document is visible to all members of the team.

HTTP request & arguments

https://www.getoutline.com/api/documents.pin

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.unpin - Unpin a document

Unpins a document from the collection home. It will still remain in the collection itself.

HTTP request & arguments

https://www.getoutline.com/api/documents.unpin

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.star - Star a document

Star (favorite) a document for authenticated user.

HTTP request & arguments

https://www.getoutline.com/api/documents.star

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.unstar - Unstar a document

Unstar a starred (favorited) document for authenticated user.

HTTP request & arguments

https://www.getoutline.com/api/documents.unstar

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier

documents.viewed - Get recently viewed document for user

Return recently viewed documents for the authenticated user

HTTP request & arguments

https://www.getoutline.com/api/documents.viewed

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

documents.starred - Get recently starred document for user

Return recently starred documents for the authenticated user

HTTP request & arguments

https://www.getoutline.com/api/documents.starred

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

documents.pinned - Get pinned documents for a collection

Return pinned documents for a collection

HTTP request & arguments

https://www.getoutline.com/api/documents.pinned

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

documents.revision - Get revision for a document

Return a specific revision of a document.

HTTP request & arguments

https://www.getoutline.com/api/documents.revision

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredDocument ID or URI identifier
revisionIdrequiredRevision ID

documents.revisions - Get revisions for a document

Return revisions for a document. Upon each edit, a new revision is stored.

HTTP request & arguments

https://www.getoutline.com/api/documents.revisions

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit
idrequiredDocument ID or URI identifier

team.users - List team's users

List team`s users. This endpoint is only available for admin users.

HTTP request & arguments

https://www.getoutline.com/api/team.users

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

shares.list - List shared document links

List all your currently shared document links.

HTTP request & arguments

https://www.getoutline.com/api/shares.list

ArgumentRequiredDescription
tokenrequiredAuthentication token
offsetoptionalPagination offset
limitoptionalPagination limit

shares.create - Create a share link

Creates a new share link that can be used by anyone to access a document. If you request multiple shares for the same document with the same user the same share will be returned.

HTTP request & arguments

https://www.getoutline.com/api/shares.create

ArgumentRequiredDescription
tokenrequiredAuthentication token
documentIdrequiredDocument ID

shares.revoke - Revoke a share link

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

HTTP request & arguments

https://www.getoutline.com/api/shares.revoke

ArgumentRequiredDescription
tokenrequiredAuthentication token
idrequiredShare ID