Puranjay Savar Mattas
b933b19d6e
Local copy at docs/reference/outline-openapi-spec3.yml (from outline/openapi) so exact request/response shapes are checkable without network access before adding new OutlineAPIClient methods — already caught two real mismatches (documents.search's sort field rejecting "relevance" as an explicit value, documents.search_titles not working against this instance at all).
7582 lines
248 KiB
YAML
7582 lines
248 KiB
YAML
---
|
||
openapi: 3.0.0
|
||
info:
|
||
title: Outline API
|
||
description: |
|
||
# 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.
|
||
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: AccessRequests
|
||
description: |
|
||
`AccessRequests` represent a request by a user for access to a document
|
||
they do not currently have permission to view. The request can be approved
|
||
or dismissed by a user with permission to share the document.
|
||
- name: Attachments
|
||
description: |
|
||
`Attachments` represent a file uploaded to cloud storage. They are created
|
||
before the upload happens from the client and store all the meta information
|
||
such as file type, size, and location.
|
||
- name: Auth
|
||
description: |
|
||
`Auth` represents the current API Keys authentication details. It can be
|
||
used to check that a token is still valid and load the IDs for the current
|
||
user and workspace.
|
||
- name: Collections
|
||
description: |
|
||
`Collections` represent grouping of documents in the knowledge base, they
|
||
offer a way to structure information in a nested hierarchy and a level
|
||
at which read and write permissions can be granted to individual users or
|
||
groups of users.
|
||
- name: Comments
|
||
description: |
|
||
`Comments` represent a comment either on a selection of text in a document
|
||
or on the document itself.
|
||
- name: DataAttributes
|
||
description: |
|
||
`DataAttributes` represent custom metadata fields that can be attached to
|
||
documents. They allow workspaces to add structured data like status, priority,
|
||
or any other custom properties to their documents.
|
||
- 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.
|
||
- name: Events
|
||
description: |
|
||
`Events` represent an artifact of an action. Whether it is creating a user,
|
||
editing a document, changing permissions, or any other action – an event
|
||
is created that can be used as an audit trail or activity stream.
|
||
- name: FileOperations
|
||
description: |
|
||
`FileOperations` represent background jobs for importing or exporting files.
|
||
You can query the file operation to find the state of progress and any
|
||
resulting output.
|
||
- name: Groups
|
||
description: |
|
||
`Groups` represent a list of users that logically belong together, for
|
||
example there might be groups for each department in your organization.
|
||
Groups can be granted access to collections with read or write permissions.
|
||
- name: OAuthClients
|
||
description: |
|
||
`OAuthClients` represent OAuth clients that can be used to authenticate
|
||
users with third-party services.
|
||
- name: OAuthAuthentications
|
||
description: |
|
||
`OAuthAuthentications` represent individual scoped authentications between
|
||
Outline and an `OAuthClient`.
|
||
- name: Revisions
|
||
description: |
|
||
`Revisions` represent a snapshot of a document at a point in time. They
|
||
are used to keep track of editing and collaboration history – a document
|
||
can also be restored to a previous revision if necessary.
|
||
- name: Shares
|
||
description: |
|
||
`Shares` represent authorization to view a document without being a member
|
||
of the workspace. Shares are created in order to give access to documents publicly.
|
||
Each user that shares a document will have a unique share object.
|
||
- name: Stars
|
||
description: |
|
||
`Stars` represent a favorited document or collection in the application sidebar.
|
||
Each user has their own collection of starred items.
|
||
- name: Users
|
||
description: |
|
||
`Users` represent an individual with access to the knowledge base. Users
|
||
can be created automatically when signing in with SSO or when a user is
|
||
invited via email.
|
||
- name: Templates
|
||
description: |
|
||
`Templates` represent reusable document templates that can be used as a
|
||
starting point when creating new documents. Templates can be scoped to a
|
||
specific collection or available workspace-wide.
|
||
- name: Views
|
||
description: |
|
||
`Views` represent a compressed record of an individual users views of a
|
||
document. Individual views are not recorded but a first, last and total
|
||
is kept per user.
|
||
paths:
|
||
"/accessRequests.create":
|
||
post:
|
||
tags:
|
||
- AccessRequests
|
||
summary: Create an access request
|
||
description:
|
||
Request access to a document. The request will be sent to users with
|
||
permission to share the document for approval or dismissal.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the document to request access to.
|
||
required:
|
||
- documentId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/AccessRequest"
|
||
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: accessRequestsCreate
|
||
"/accessRequests.info":
|
||
post:
|
||
tags:
|
||
- AccessRequests
|
||
summary: Retrieve an access request
|
||
description:
|
||
Retrieve information about an access request by `id`, or the current
|
||
user's pending request for a document by `documentId`. At least one of
|
||
these parameters must be provided.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique identifier for the access request.
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description:
|
||
Identifier for the document to find a pending request for the
|
||
current user.
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/AccessRequest"
|
||
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: accessRequestsInfo
|
||
"/accessRequests.approve":
|
||
post:
|
||
tags:
|
||
- AccessRequests
|
||
summary: Approve an access request
|
||
description:
|
||
Approve a pending access request, granting the requesting user a
|
||
membership on the document with the specified permission.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique identifier for the access request.
|
||
permission:
|
||
type: string
|
||
description: The permission to grant the requesting user.
|
||
enum:
|
||
- read
|
||
- read_write
|
||
- admin
|
||
default: read
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/AccessRequest"
|
||
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: accessRequestsApprove
|
||
"/accessRequests.dismiss":
|
||
post:
|
||
tags:
|
||
- AccessRequests
|
||
summary: Dismiss an access request
|
||
description:
|
||
Dismiss a pending access request without granting the requesting user
|
||
access to the document.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique identifier for the access request.
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/AccessRequest"
|
||
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: accessRequestsDismiss
|
||
"/attachments.create":
|
||
post:
|
||
tags:
|
||
- Attachments
|
||
summary: Create an attachment
|
||
description:
|
||
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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Name of the file attachment.
|
||
example: image.png
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the associated document, if any.
|
||
format: uuid
|
||
contentType:
|
||
type: string
|
||
description: MIME type of the file attachment.
|
||
example: image/png
|
||
size:
|
||
type: integer
|
||
minimum: 0
|
||
description: Size of the file attachment in bytes.
|
||
required:
|
||
- name
|
||
- contentType
|
||
- size
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
maxUploadSize:
|
||
type: number
|
||
mode:
|
||
type: string
|
||
enum:
|
||
- post
|
||
- put
|
||
description:
|
||
Indicates which presigned upload method the server is
|
||
configured to use. When `post`, the client should perform
|
||
a multipart form POST using `uploadUrl` and `form`. When
|
||
`put`, the client should perform a PUT request to `url`
|
||
with the supplied `headers`.
|
||
uploadUrl:
|
||
type: string
|
||
format: uri
|
||
description: Present when `mode` is `post`. The endpoint to
|
||
POST a multipart form upload to.
|
||
form:
|
||
type: object
|
||
description: Present when `mode` is `post`. The form fields
|
||
to include in the multipart upload, including signed
|
||
credentials.
|
||
url:
|
||
type: string
|
||
format: uri
|
||
description: Present when `mode` is `put`. The presigned URL
|
||
to PUT the file contents to.
|
||
headers:
|
||
type: object
|
||
description: Present when `mode` is `put`. The HTTP headers
|
||
that must be sent with the PUT request.
|
||
attachment:
|
||
"$ref": "#/components/schemas/Attachment"
|
||
"400":
|
||
"$ref": "#/components/responses/Validation"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: attachmentsCreate
|
||
"/attachments.redirect":
|
||
post:
|
||
tags:
|
||
- Attachments
|
||
summary: Retrieve an attachment
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the attachment.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"302":
|
||
description: Redirect to the attachment URL
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: attachmentsRedirect
|
||
"/attachments.delete":
|
||
post:
|
||
tags:
|
||
- Attachments
|
||
summary: Delete an attachment
|
||
description: Deleting an attachment is permanent. It will not delete references
|
||
or links to the attachment that may exist in your documents.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Unique identifier for the attachment.
|
||
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: attachmentsDelete
|
||
"/auth.info":
|
||
post:
|
||
tags:
|
||
- Auth
|
||
summary: Retrieve auth
|
||
description: Retrieve authentication details for the current API key
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Auth"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: authInfo
|
||
"/auth.config":
|
||
post:
|
||
tags:
|
||
- Auth
|
||
summary: Retrieve auth config
|
||
description: Retrieve authentication options
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
example: Acme Inc
|
||
hostname:
|
||
type: string
|
||
example: acme-inc.getoutline.com
|
||
services:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
example: slack
|
||
name:
|
||
type: string
|
||
example: Slack
|
||
authUrl:
|
||
type: string
|
||
example: https://acme-inc.getoutline.com/auth/slack
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: authConfig
|
||
"/collections.info":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Retrieve a collection
|
||
description: Retrieve the details of a collection by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the collection.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Collection"
|
||
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: collectionsInfo
|
||
"/collections.documents":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Retrieve a collections document structure
|
||
description: Returns the document structure of a collection as a tree of navigation nodes, representing the hierarchy of documents within the collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the collection.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/NavigationNode"
|
||
example: []
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsDocuments
|
||
"/collections.list":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: List all collections
|
||
description: List all collections that the authenticated user has access to.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
query:
|
||
type: string
|
||
description: If set, will filter the results by collection name.
|
||
statusFilter:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/CollectionStatus"
|
||
description: An optional array of statuses to filter by.
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Collection"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsList
|
||
"/collections.create":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Create a collection
|
||
description: Create a new collection with the specified name, description, icon, color, and permission settings. Collections are used to organize documents.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
example: Human Resources
|
||
description:
|
||
type: string
|
||
description: A brief description of the collection, markdown supported. Only one of `description` or `data` may be provided.
|
||
example: HR documentation is confidential and should be handled with care.
|
||
data:
|
||
type: object
|
||
description: The collection description as a rich-text ProseMirror JSON document. Only one of `description` or `data` may be provided.
|
||
permission:
|
||
"$ref": "#/components/schemas/Permission"
|
||
icon:
|
||
type: string
|
||
description: A string that represents an icon in the outline-icons package or an emoji
|
||
color:
|
||
type: string
|
||
description: A hex color code for the collection icon
|
||
example: "#123123"
|
||
sharing:
|
||
type: boolean
|
||
description: Whether public sharing of documents is allowed
|
||
example: false
|
||
required:
|
||
- name
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$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"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsCreate
|
||
"/collections.duplicate":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Duplicate a collection
|
||
description: |
|
||
Duplicate an existing collection along with its published documents. The
|
||
original collection's settings – icon, color, permission, sharing, and
|
||
sorting – are preserved on the copy. Draft and archived documents are
|
||
not duplicated. Document duplication runs asynchronously in the
|
||
background, so the copy may initially be returned before all of its
|
||
documents have been created.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the collection to duplicate.
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: An optional name for the new collection. If omitted, the original collection's name is reused.
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$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: collectionsDuplicate
|
||
"/collections.update":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Update a collection
|
||
description: Update an existing collection's properties such as name, description, icon, color, sharing settings, or permission level.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
example: Human Resources
|
||
description:
|
||
type: string
|
||
description: A brief description of the collection, markdown supported. Only one of `description` or `data` may be provided.
|
||
example: HR documentation is confidential and should be handled with care.
|
||
data:
|
||
type: object
|
||
description: The collection description as a rich-text ProseMirror JSON document. Only one of `description` or `data` may be provided.
|
||
permission:
|
||
"$ref": "#/components/schemas/Permission"
|
||
icon:
|
||
type: string
|
||
description: A string that represents an icon in the outline-icons package or an emoji
|
||
color:
|
||
type: string
|
||
description: A hex color code for the collection icon
|
||
example: "#123123"
|
||
sharing:
|
||
type: boolean
|
||
description: Whether public sharing of documents is allowed
|
||
example: false
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$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: collectionsUpdate
|
||
"/collections.add_user":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Add a collection user
|
||
description: This method allows you to add a user membership to the specified
|
||
collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the collection
|
||
format: uuid
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user to add to the collection
|
||
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: collectionsAddUser
|
||
"/collections.remove_user":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Remove a collection user
|
||
description: This method allows you to remove a user from the specified collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the collection
|
||
format: uuid
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user to remove from the collection
|
||
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: collectionsRemoveUser
|
||
"/collections.memberships":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: List all collection memberships
|
||
description:
|
||
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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the collection
|
||
format: uuid
|
||
query:
|
||
type: string
|
||
description: Filter memberships by user names
|
||
example: jenny
|
||
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"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsMemberships
|
||
"/collections.add_group":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Add a group to a collection
|
||
description: This method allows you to give all members in a group access to
|
||
a collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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:
|
||
collectionGroupMemberships:
|
||
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: collectionsAddGroup
|
||
"/collections.remove_group":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Remove a collection group
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the collection
|
||
format: uuid
|
||
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: collectionsRemoveGroup
|
||
"/collections.group_memberships":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: List all collection group members
|
||
description: This method allows you to list a collections group memberships.
|
||
This is the list of groups that have been given access to the collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the collection
|
||
format: uuid
|
||
query:
|
||
type: string
|
||
description: Filter memberships by group names
|
||
example: developers
|
||
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"
|
||
collectionGroupMemberships:
|
||
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"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsGroupMemberships
|
||
"/collections.delete":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Delete a collection
|
||
description: Delete a collection and all of its documents. This action can’t
|
||
be undone so please be careful.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsDelete
|
||
"/collections.export":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Export a collection
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
format:
|
||
type: string
|
||
enum:
|
||
- outline-markdown
|
||
- json
|
||
- html
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
fileOperation:
|
||
"$ref": "#/components/schemas/FileOperation"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsExport
|
||
"/collections.export_all":
|
||
post:
|
||
tags:
|
||
- Collections
|
||
summary: Export all collections
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
format:
|
||
type: string
|
||
enum:
|
||
- outline-markdown
|
||
- json
|
||
- html
|
||
includeAttachments:
|
||
type: boolean
|
||
description: Whether to include attachments in the export.
|
||
default: true
|
||
includePrivate:
|
||
type: boolean
|
||
description: Whether to include private collections in the export.
|
||
default: true
|
||
description:
|
||
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.
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
fileOperation:
|
||
"$ref": "#/components/schemas/FileOperation"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: collectionsExportAll
|
||
"/comments.create":
|
||
post:
|
||
tags:
|
||
- Comments
|
||
summary: Create a comment
|
||
description:
|
||
Add a comment or reply to a document, either `data` or `text` is required.
|
||
Provide `anchorText` to create an inline comment attached to a specific
|
||
text range in the document.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
parentCommentId:
|
||
type: string
|
||
format: uuid
|
||
data:
|
||
type: object
|
||
description: The body of the comment.
|
||
text:
|
||
type: string
|
||
description: The body of the comment in markdown.
|
||
example: Sounds great
|
||
anchorText:
|
||
type: string
|
||
description:
|
||
Plain text substring to anchor the comment to as an inline
|
||
comment. The first occurrence in the document's plain text
|
||
is used unless disambiguated by `anchorPrefix` and/or
|
||
`anchorSuffix`.
|
||
anchorPrefix:
|
||
type: string
|
||
description:
|
||
Text immediately preceding `anchorText`, used to disambiguate
|
||
between multiple occurrences. Requires `anchorText`.
|
||
anchorSuffix:
|
||
type: string
|
||
description:
|
||
Text immediately following `anchorText`, used to disambiguate
|
||
between multiple occurrences. Requires `anchorText`.
|
||
required:
|
||
- documentId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Comment"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: commentsCreate
|
||
"/comments.info":
|
||
post:
|
||
tags:
|
||
- Comments
|
||
summary: Retrieve a comment
|
||
description: Retrieve a comment
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
includeAnchorText:
|
||
type: boolean
|
||
description: Include the document text that the comment is anchored
|
||
to, if any, in the response.
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Comment"
|
||
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: commentsInfo
|
||
"/comments.update":
|
||
post:
|
||
tags:
|
||
- Comments
|
||
summary: Update a comment
|
||
description: Update a comment
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
data:
|
||
type: object
|
||
required:
|
||
- id
|
||
- data
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Comment"
|
||
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: commentsUpdate
|
||
"/comments.delete":
|
||
post:
|
||
tags:
|
||
- Comments
|
||
summary: Delete a comment
|
||
description: Deletes a comment. If the comment is a top-level comment, all its children will be deleted as well.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: commentsDelete
|
||
"/comments.list":
|
||
post:
|
||
tags:
|
||
- Comments
|
||
summary: List all comments
|
||
description: This method will list all comments matching the given properties.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to a specific document
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to a specific collection
|
||
includeAnchorText:
|
||
type: boolean
|
||
description:
|
||
Include the document text that the comment is anchored
|
||
to, if any, in the response.
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Comment"
|
||
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: commentsList
|
||
"/dataAttributes.info":
|
||
post:
|
||
x-badges:
|
||
- name: Business
|
||
- name: Enterprise
|
||
tags:
|
||
- DataAttributes
|
||
summary: Retrieve a data attribute
|
||
description: Retrieve a data attribute by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the data attribute.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/DataAttribute"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: dataAttributesInfo
|
||
"/dataAttributes.list":
|
||
post:
|
||
x-badges:
|
||
- name: Business
|
||
- name: Enterprise
|
||
tags:
|
||
- DataAttributes
|
||
summary: List all data attributes
|
||
description: List all data attributes.
|
||
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/DataAttribute"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: dataAttributesList
|
||
"/dataAttributes.create":
|
||
post:
|
||
x-badges:
|
||
- name: Business
|
||
- name: Enterprise
|
||
tags:
|
||
- DataAttributes
|
||
summary: Create a data attribute
|
||
description: Create a new data attribute. Only admins can create data attributes.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Name of the data attribute.
|
||
example: Status
|
||
description:
|
||
type: string
|
||
description: Description of the data attribute.
|
||
example: The current status of the document.
|
||
dataType:
|
||
"$ref": "#/components/schemas/DataAttributeDataType"
|
||
options:
|
||
"$ref": "#/components/schemas/DataAttributeOptions"
|
||
pinned:
|
||
type: boolean
|
||
description: Whether the data attribute is pinned to the top of document.
|
||
default: false
|
||
required:
|
||
- name
|
||
- dataType
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/DataAttribute"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: dataAttributesCreate
|
||
"/dataAttributes.update":
|
||
post:
|
||
x-badges:
|
||
- name: Business
|
||
- name: Enterprise
|
||
tags:
|
||
- DataAttributes
|
||
summary: Update a data attribute
|
||
description: Update an existing data attribute. Only admins can update data attributes. Note that the dataType cannot be changed after creation.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the data attribute.
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: Name of the data attribute.
|
||
example: Status
|
||
description:
|
||
type: string
|
||
description: Description of the data attribute.
|
||
options:
|
||
"$ref": "#/components/schemas/DataAttributeOptions"
|
||
pinned:
|
||
type: boolean
|
||
description: Whether the data attribute is pinned to the top of document.
|
||
required:
|
||
- id
|
||
- name
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/DataAttribute"
|
||
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: dataAttributesUpdate
|
||
"/dataAttributes.delete":
|
||
post:
|
||
x-badges:
|
||
- name: Business
|
||
- name: Enterprise
|
||
tags:
|
||
- DataAttributes
|
||
summary: Delete a data attribute
|
||
description: Delete a data attribute. Only admins can delete data attributes.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the data attribute.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: dataAttributesDelete
|
||
"/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, pdf, csv, tsv, html,
|
||
mhtml (or mht) web pages, eml email messages, and
|
||
textbundle/textpack bundles 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, PDF, or TextBundle format. The response format is determined by the Accept header (`text/markdown`, `text/html`, `application/pdf`, or `application/x-textbundle`). 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
|
||
maxLength: 1536000
|
||
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
|
||
maxLength: 1536000
|
||
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
|
||
"/events.list":
|
||
post:
|
||
tags:
|
||
- Events
|
||
summary: List all events
|
||
description: Events are an audit trail of important events that happen in the
|
||
knowledge base.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
Filter to a specific event, e.g. "collections.create".
|
||
Event names are in the format "objects.verb"
|
||
actorId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to events performed by the selected user
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to events performed in the selected document
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to events performed in the selected collection
|
||
auditLog:
|
||
type: boolean
|
||
description: Whether to return detailed events suitable for an
|
||
audit log. Without this flag less detailed event types will
|
||
be returned.
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Event"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: eventsList
|
||
"/fileOperations.info":
|
||
post:
|
||
tags:
|
||
- FileOperations
|
||
summary: Retrieve a file operation
|
||
description: Retrieve the details and current status of a file operation by its unique identifier. File operations represent long-running import or export tasks.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the file operation.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/FileOperation"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: fileOperationsInfo
|
||
"/fileOperations.delete":
|
||
post:
|
||
tags:
|
||
- FileOperations
|
||
summary: Delete a file operation
|
||
description: Delete a file operation and its associated files. This is useful for cleaning up completed or failed import/export operations.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the file operation.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: fileOperationsDelete
|
||
"/fileOperations.redirect":
|
||
post:
|
||
tags:
|
||
- FileOperations
|
||
summary: Retrieve the file
|
||
description: Load the resulting file from where it is stored based on the id.
|
||
A temporary, signed url with embedded credentials is generated on demand.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the file operation.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/octet-stream:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: fileOperationsRedirect
|
||
"/fileOperations.list":
|
||
post:
|
||
tags:
|
||
- FileOperations
|
||
summary: List all file operations
|
||
description: List all file operations for the current workspace, filtered by type (import or export).
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
type:
|
||
type: string
|
||
description: The type of fileOperation
|
||
example: export
|
||
enum:
|
||
- export
|
||
- import
|
||
required:
|
||
- type
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/FileOperation"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: fileOperationsList
|
||
"/groups.info":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Retrieve a group
|
||
description: Retrieve the details of a group by its unique identifier, including its name and member count.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the group.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Group"
|
||
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: groupsInfo
|
||
"/groups.list":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: List all groups
|
||
description: List all groups in the workspace. Groups are used to organize users and manage permissions for collections.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
userId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to groups including a specific user
|
||
externalId:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to groups matching an external ID
|
||
query:
|
||
type: string
|
||
format: uuid
|
||
description: Filter to groups matching a search query
|
||
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
|
||
description: A preview of memberships in the group, note that
|
||
this is not all memberships which can be queried from `groups.memberships`.
|
||
items:
|
||
"$ref": "#/components/schemas/GroupMembership"
|
||
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: groupsList
|
||
"/groups.create":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Create a group
|
||
description: Create a new group with the specified name. Groups can be used to organize users and assign collection permissions to multiple users at once.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
example: Designers
|
||
required:
|
||
- name
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Group"
|
||
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: groupsCreate
|
||
"/groups.update":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Update a group
|
||
description: Update an existing group's name. The group is identified by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
example: Designers
|
||
required:
|
||
- id
|
||
- name
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Group"
|
||
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: groupsUpdate
|
||
"/groups.delete":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Delete a group
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: groupsDelete
|
||
"/groups.memberships":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: List all group members
|
||
description: List and filter all the members in a group.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Group id
|
||
example: a32c2ee6-fbde-4654-841b-0eabdc71b812
|
||
query:
|
||
type: string
|
||
description: Filter memberships by user names
|
||
example: jenny
|
||
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"
|
||
groupMemberships:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/GroupMembership"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
"400":
|
||
"$ref": "#/components/responses/Validation"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: groupsMemberships
|
||
"/groups.add_user":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Add a group member
|
||
description: This method allows you to add a user to the specified group.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the group
|
||
format: uuid
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user to add to the group
|
||
format: uuid
|
||
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"
|
||
groups:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Group"
|
||
groupMemberships:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/GroupMembership"
|
||
"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: groupsAddUser
|
||
"/groups.remove_user":
|
||
post:
|
||
tags:
|
||
- Groups
|
||
summary: Remove a group member
|
||
description: This method allows you to remove a user from the group.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Identifier for the group
|
||
format: uuid
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user to remove from the group
|
||
format: uuid
|
||
required:
|
||
- id
|
||
- userId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
groups:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Group"
|
||
"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: groupsRemoveUser
|
||
"/oauthClients.info":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: Retrieve an OAuth client
|
||
description: To retrieve information about an OAuth client you must pass either an `id` or a `clientId`.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the OAuth client.
|
||
format: uuid
|
||
clientId:
|
||
type: string
|
||
description: Public identifier for the OAuth client.
|
||
example: 2bquf8avrpdv31par42a
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/OAuthClient"
|
||
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: oauthClientsInfo
|
||
|
||
"/oauthClients.list":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: List accessible OAuth clients
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/OAuthClient"
|
||
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: oauthClientsList
|
||
|
||
"/oauthClients.create":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: Create an OAuth client
|
||
description: Create a new OAuth client application that can be used to authenticate users and access the API on their behalf.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: Name of the OAuth client.
|
||
example: My App
|
||
description:
|
||
type: string
|
||
description: A short description of this OAuth client.
|
||
example: Integrate Acme Inc's services into Outline.
|
||
developerName:
|
||
type: string
|
||
description: The name of the developer who created this OAuth client.
|
||
example: Acme Inc
|
||
developerUrl:
|
||
type: string
|
||
description: The URL of the developer who created this OAuth client.
|
||
example: https://example.com
|
||
avatarUrl:
|
||
type: string
|
||
description: A URL pointing to an image representing the OAuth client.
|
||
redirectUris:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: List of redirect URIs for the OAuth client.
|
||
example: ["https://example.com/callback"]
|
||
published:
|
||
type: boolean
|
||
description: Whether the OAuth client is available to other workspaces.
|
||
example: true
|
||
required:
|
||
- name
|
||
- redirectUris
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/OAuthClient"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: oauthClientsCreate
|
||
|
||
"/oauthClients.update":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: Update an OAuth client
|
||
description: Update an existing OAuth client's properties such as name, description, redirect URIs, or published status.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the OAuth client.
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: Name of the OAuth client.
|
||
example: My App
|
||
description:
|
||
type: string
|
||
description: A short description of this OAuth client.
|
||
example: Integrate Acme Inc's services into Outline.
|
||
developerName:
|
||
type: string
|
||
description: The name of the developer who created this OAuth client.
|
||
example: Acme Inc
|
||
developerUrl:
|
||
type: string
|
||
description: The URL of the developer who created this OAuth client.
|
||
example: https://example.com
|
||
avatarUrl:
|
||
type: string
|
||
description: A URL pointing to an image representing the OAuth client.
|
||
redirectUris:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: List of redirect URIs for the OAuth client.
|
||
example: ["https://example.com/callback"]
|
||
published:
|
||
type: boolean
|
||
description: Whether the OAuth client is available to other workspaces.
|
||
example: true
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/OAuthClient"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: oauthClientsUpdate
|
||
|
||
"/oauthClients.rotate_secret":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: Rotate the secret for an OAuth client
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the OAuth client.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/OAuthClient"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: oauthClientsRotateSecret
|
||
|
||
"/oauthClients.delete":
|
||
post:
|
||
tags:
|
||
- OAuthClients
|
||
summary: Delete an OAuth client
|
||
description: Permanently delete an OAuth client and revoke all associated access tokens. This action cannot be undone.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the OAuth client.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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: oauthClientsDelete
|
||
|
||
"/oauthAuthentications.list":
|
||
post:
|
||
tags:
|
||
- OAuthAuthentications
|
||
summary: List accessible OAuth authentications
|
||
description: List all OAuth authentications for the current user. These represent the third-party applications that the user has authorized to access their account.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/OAuthAuthentication"
|
||
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: oauthAuthenticationsList
|
||
|
||
"/oauthAuthentications.delete":
|
||
post:
|
||
tags:
|
||
- OAuthAuthentications
|
||
summary: Delete an OAuth authentiation
|
||
description: Revoke an OAuth authentication, removing the third-party application's access to the user's account.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
oauthClientId:
|
||
type: string
|
||
format: uuid
|
||
scope:
|
||
type: array
|
||
items:
|
||
type: string
|
||
required:
|
||
- oauthClientId
|
||
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: oauthAuthenticationsDelete
|
||
|
||
"/revisions.info":
|
||
post:
|
||
tags:
|
||
- Revisions
|
||
summary: Retrieve a revision
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the revision.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/RevisionDetail"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: revisionsInfo
|
||
"/revisions.list":
|
||
post:
|
||
tags:
|
||
- Revisions
|
||
summary: List all revisions
|
||
description: 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. The `data` and `text` fields are omitted from listed revisions for performance; use `revisions.info` to retrieve the full content of a specific revision.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: The document ID to retrieve revisions for
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Revision"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: revisionsList
|
||
"/shares.info":
|
||
post:
|
||
tags:
|
||
- Shares
|
||
summary: Retrieve a share object
|
||
description: 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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the share.
|
||
format: uuid
|
||
documentId:
|
||
type: string
|
||
description:
|
||
Unique identifier for a document. One of id or documentId
|
||
must be provided.
|
||
format: uuid
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Share"
|
||
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: sharesInfo
|
||
"/shares.list":
|
||
post:
|
||
tags:
|
||
- Shares
|
||
summary: List all shares
|
||
description: List all share links in the workspace.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
query:
|
||
type: string
|
||
description: Filter to shared documents matching a search query
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Share"
|
||
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: sharesList
|
||
"/shares.create":
|
||
post:
|
||
tags:
|
||
- Shares
|
||
summary: Create a share
|
||
description: Creates a new share link that can be used by to access a document
|
||
or collection. If you request multiple shares for the same resource with the
|
||
same API key, the same share object will be returned. By default all shares
|
||
are unpublished. Exactly one of `documentId` or `collectionId` must be
|
||
provided.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the document to share. Mutually exclusive with `collectionId`.
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the collection to share. Mutually exclusive with `documentId`.
|
||
oneOf:
|
||
- required:
|
||
- documentId
|
||
- required:
|
||
- collectionId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Share"
|
||
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: sharesCreate
|
||
"/shares.update":
|
||
post:
|
||
tags:
|
||
- Shares
|
||
summary: Update a share
|
||
description:
|
||
Allows changing an existing share's published status, which removes
|
||
authentication and makes it available to anyone with the link.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
published:
|
||
type: boolean
|
||
title:
|
||
type: string
|
||
maxLength: 255
|
||
nullable: true
|
||
description:
|
||
Override title displayed on the publicly shared page. If
|
||
not set the source document or collection title is used.
|
||
iconUrl:
|
||
type: string
|
||
format: uri
|
||
maxLength: 4096
|
||
nullable: true
|
||
description:
|
||
URL of an icon to display on the publicly shared page,
|
||
overriding the workspace branding.
|
||
required:
|
||
- id
|
||
- published
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Share"
|
||
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: sharesUpdate
|
||
"/shares.revoke":
|
||
post:
|
||
tags:
|
||
- Shares
|
||
summary: Revoke a share
|
||
description: Makes the share link inactive so that it can no longer be used
|
||
to access the document.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: sharesRevoke
|
||
"/stars.create":
|
||
post:
|
||
tags:
|
||
- Stars
|
||
summary: Create a star
|
||
description: Stars a document or collection so it appears in the users sidebar. One of either `documentId` or `collectionId` must be provided.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
index:
|
||
type: string
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Star"
|
||
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: starsCreate
|
||
"/stars.list":
|
||
post:
|
||
tags:
|
||
- Stars
|
||
summary: List all stars
|
||
description: List all starred documents for the authenticated user. Stars allow users to bookmark important documents for quick access in the sidebar.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
stars:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Star"
|
||
documents:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Document"
|
||
pagination:
|
||
"$ref": "#/components/schemas/Pagination"
|
||
policies:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Policy"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: starsList
|
||
"/stars.update":
|
||
post:
|
||
tags:
|
||
- Stars
|
||
summary: Update a stars order in the sidebar
|
||
description: Update the position of a starred document in the sidebar. The index parameter determines the display order relative to other starred documents.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
index:
|
||
type: string
|
||
required:
|
||
- id
|
||
- index
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/Star"
|
||
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: starsUpdate
|
||
"/stars.delete":
|
||
post:
|
||
tags:
|
||
- Stars
|
||
summary: Delete a star
|
||
description: Remove a star from a document, removing it from the user's starred documents list in the sidebar.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
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: starsDelete
|
||
"/users.invite":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Invite users
|
||
description: Send email invitations to one or more users to join the workspace. Invitations include a link to create an account and join the workspace.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
invites:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Invite"
|
||
suppressEmail:
|
||
type: boolean
|
||
description: If true, the invitation emails will not be sent to the invited users. Defaults to false.
|
||
required:
|
||
- invites
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
properties:
|
||
sent:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Invite"
|
||
users:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/User"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: usersInvite
|
||
"/users.info":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Retrieve a user
|
||
description: Retrieve the details of a user by their unique identifier, including their name, email, avatar, and role within the workspace.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the user.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersInfo
|
||
"/users.list":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: List all users
|
||
description: List and filter all the users in the workspace
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Pagination"
|
||
- "$ref": "#/components/schemas/Sorting"
|
||
- type: object
|
||
properties:
|
||
query:
|
||
type: string
|
||
example: jane
|
||
emails:
|
||
type: array
|
||
description: Array of emails
|
||
items:
|
||
type: string
|
||
example:
|
||
- jane.crandall@mail.com
|
||
- prudence.crandall@mail.com
|
||
filter:
|
||
type: string
|
||
description: The status to filter by
|
||
enum:
|
||
- all
|
||
- invited
|
||
- active
|
||
- suspended
|
||
role:
|
||
"$ref": "#/components/schemas/UserRole"
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersList
|
||
"/users.update":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Update a user
|
||
description: Update a users name or avatar. If no `id` is passed then the user
|
||
associated with the authentication will be updated by default.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
language:
|
||
type: string
|
||
format: BCP47
|
||
avatarUrl:
|
||
type: string
|
||
format: uri
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersUpdate
|
||
"/users.update_role":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Change a users role
|
||
description: Change the role of a user, only available to admin authorization.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the user.
|
||
format: uuid
|
||
role:
|
||
"$ref": "#/components/schemas/UserRole"
|
||
required:
|
||
- id
|
||
- role
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersUpdateRole
|
||
"/users.suspend":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Suspend a user
|
||
description: Suspending a user prevents the user from signing in. Users that
|
||
are suspended are also not counted against billing totals in the hosted version.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the user.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersSuspend
|
||
"/users.activate":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Activate a user
|
||
description:
|
||
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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the user.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/User"
|
||
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: usersActivate
|
||
"/users.delete":
|
||
post:
|
||
tags:
|
||
- Users
|
||
summary: Delete a user
|
||
description:
|
||
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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the user.
|
||
format: uuid
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: usersDelete
|
||
"/views.list":
|
||
post:
|
||
tags:
|
||
- Views
|
||
summary: List all views
|
||
description: List all users that have viewed a document and the overall view
|
||
count.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: The document ID to retrieve views for
|
||
includeSuspended:
|
||
type: boolean
|
||
description: Whether to include views from suspended users
|
||
default: false
|
||
required:
|
||
- documentId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/View"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: viewsList
|
||
"/views.create":
|
||
post:
|
||
tags:
|
||
- Views
|
||
summary: Create a view
|
||
description:
|
||
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.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- documentId
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
"$ref": "#/components/schemas/View"
|
||
"401":
|
||
"$ref": "#/components/responses/Unauthenticated"
|
||
"403":
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: viewsCreate
|
||
"/templates.create":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Create a template
|
||
description: Create a new template that can be used as a starting point for new documents. Templates can optionally be scoped to a specific collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: Optionally provide a specific UUID for the template.
|
||
title:
|
||
type: string
|
||
description: The title of the template. Required when publishing.
|
||
maxLength: 255
|
||
data:
|
||
type: object
|
||
description: The body of the template as a Prosemirror document. Required when publishing.
|
||
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
|
||
pattern: "^#[0-9A-Fa-f]{6}$"
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the collection to which the template belongs.
|
||
publish:
|
||
type: boolean
|
||
default: true
|
||
description: Whether the template is available to other members. Set to false to create a draft that is only visible to its creator.
|
||
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: templatesCreate
|
||
"/templates.list":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: List all templates
|
||
description: List all templates available to the current user. Optionally filter by collection. Templates not associated with a collection are workspace-wide.
|
||
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
|
||
query:
|
||
type: string
|
||
description: Search query to filter templates by title
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/Template"
|
||
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: templatesList
|
||
"/templates.info":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Retrieve a template
|
||
description: Retrieve a template by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the template. 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/Template"
|
||
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: templatesInfo
|
||
"/templates.update":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Update a template
|
||
description: Update an existing template by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the template. Either the UUID or the urlId is acceptable.
|
||
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
|
||
pattern: "^#[0-9A-Fa-f]{6}$"
|
||
fullWidth:
|
||
type: boolean
|
||
description: Whether the template should be displayed full width.
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the collection to which the template belongs. Set to null for a workspace-wide template.
|
||
nullable: true
|
||
publish:
|
||
type: boolean
|
||
description: Set to true to publish a draft template so it becomes available to other members.
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: templatesUpdate
|
||
"/templates.delete":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Delete a template
|
||
description: Delete a template by its unique identifier. This will soft-delete the template, it can be restored later.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the template. Either the UUID or the urlId is acceptable.
|
||
required:
|
||
- id
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
success:
|
||
type: boolean
|
||
"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: templatesDelete
|
||
"/templates.restore":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Restore a template
|
||
description: Restore a previously deleted template by its unique identifier.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the template. 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/Template"
|
||
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: templatesRestore
|
||
"/templates.duplicate":
|
||
post:
|
||
tags:
|
||
- Templates
|
||
summary: Duplicate a template
|
||
description: Create a copy of an existing template. Optionally override the title and target collection.
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the template to duplicate. Either the UUID or the urlId is acceptable.
|
||
title:
|
||
type: string
|
||
description: Override the title of the duplicated template.
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the collection to place the duplicated template in. If not provided, uses the original template's collection.
|
||
nullable: true
|
||
required:
|
||
- id
|
||
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"
|
||
"404":
|
||
"$ref": "#/components/responses/NotFound"
|
||
"429":
|
||
"$ref": "#/components/responses/RateLimited"
|
||
operationId: templatesDuplicate
|
||
components:
|
||
schemas:
|
||
Permission:
|
||
type: string
|
||
enum:
|
||
- read
|
||
- read_write
|
||
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
|
||
AccessRequest:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the document this request is for.
|
||
format: uuid
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user that made the request.
|
||
format: uuid
|
||
user:
|
||
"$ref": "#/components/schemas/User"
|
||
teamId:
|
||
type: string
|
||
description: Identifier for the workspace the request belongs to.
|
||
format: uuid
|
||
status:
|
||
type: string
|
||
description: The current status of the access request.
|
||
enum:
|
||
- pending
|
||
- approved
|
||
- dismissed
|
||
responderId:
|
||
type: string
|
||
description: Identifier for the user that responded to the request, if any.
|
||
format: uuid
|
||
nullable: true
|
||
responder:
|
||
"$ref": "#/components/schemas/User"
|
||
respondedAt:
|
||
type: string
|
||
description: The date and time the request was responded to, if any.
|
||
format: date-time
|
||
nullable: 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
|
||
Attachment:
|
||
type: object
|
||
properties:
|
||
contentType:
|
||
type: string
|
||
example: image/png
|
||
size:
|
||
type: string
|
||
description: >-
|
||
The size of the attachment in bytes. Returned as a string as the
|
||
value may exceed the safe integer range.
|
||
name:
|
||
type: string
|
||
url:
|
||
type: string
|
||
format: uri
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the associated document, if any.
|
||
format: uuid
|
||
nullable: true
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user that created the attachment.
|
||
format: uuid
|
||
Pagination:
|
||
type: object
|
||
properties:
|
||
offset:
|
||
type: number
|
||
example: 0
|
||
limit:
|
||
type: number
|
||
example: 25
|
||
Sorting:
|
||
type: object
|
||
properties:
|
||
sort:
|
||
type: string
|
||
example: updatedAt
|
||
direction:
|
||
type: string
|
||
example: DESC
|
||
enum:
|
||
- ASC
|
||
- DESC
|
||
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"
|
||
Auth:
|
||
type: object
|
||
properties:
|
||
user:
|
||
"$ref": "#/components/schemas/User"
|
||
team:
|
||
"$ref": "#/components/schemas/Team"
|
||
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
|
||
Comment:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
data:
|
||
type: object
|
||
description: The editor data representing this comment.
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the document this is related to.
|
||
format: uuid
|
||
parentCommentId:
|
||
type: string
|
||
description: Identifier for the comment this is a child of, if any.
|
||
format: uuid
|
||
createdAt:
|
||
type: string
|
||
description: The date and time that this object was created
|
||
readOnly: true
|
||
format: date-time
|
||
createdBy:
|
||
"$ref": "#/components/schemas/User"
|
||
createdById:
|
||
type: string
|
||
description: Identifier for the user who created this comment.
|
||
format: uuid
|
||
readOnly: true
|
||
updatedAt:
|
||
type: string
|
||
description: The date and time that this object was last changed
|
||
readOnly: true
|
||
format: date-time
|
||
resolvedAt:
|
||
type: string
|
||
description: The date and time that this comment was resolved, if it has been.
|
||
format: date-time
|
||
nullable: true
|
||
readOnly: true
|
||
resolvedBy:
|
||
allOf:
|
||
- nullable: true
|
||
- "$ref": "#/components/schemas/User"
|
||
resolvedById:
|
||
type: string
|
||
description: Identifier for the user who resolved this comment, if any.
|
||
format: uuid
|
||
nullable: true
|
||
readOnly: true
|
||
reactions:
|
||
type: array
|
||
description: List of emoji reactions on this comment.
|
||
items:
|
||
type: object
|
||
readOnly: true
|
||
anchorText:
|
||
type: string
|
||
description:
|
||
The document text that the comment is anchored to, only included
|
||
if includeAnchorText=true.
|
||
readOnly: true
|
||
DataAttribute:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: The name of this data attribute.
|
||
example: Status
|
||
description:
|
||
type: string
|
||
description: A description of the data attribute.
|
||
example: The current status of the document.
|
||
dataType:
|
||
"$ref": "#/components/schemas/DataAttributeDataType"
|
||
options:
|
||
"$ref": "#/components/schemas/DataAttributeOptions"
|
||
pinned:
|
||
type: boolean
|
||
description: Whether this data attribute is pinned to the top of documents.
|
||
default: false
|
||
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
|
||
DataAttributeDataType:
|
||
type: string
|
||
description: The data type of the attribute value.
|
||
enum:
|
||
- string
|
||
- number
|
||
- boolean
|
||
- list
|
||
DataAttributeOptions:
|
||
type: object
|
||
description: Additional options for certain data attribute types.
|
||
properties:
|
||
icon:
|
||
type: string
|
||
description: An icon representing the data attribute from the outline-icons package.
|
||
options:
|
||
type: array
|
||
description: Valid options for list data type.
|
||
items:
|
||
type: object
|
||
properties:
|
||
value:
|
||
type: string
|
||
description: The label/value of the option.
|
||
color:
|
||
type: string
|
||
description: Optional color for the option.
|
||
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
|
||
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: "\U0001F389"
|
||
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
|
||
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.
|
||
Event:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
example: documents.create
|
||
readOnly: true
|
||
modelId:
|
||
type: string
|
||
description: Identifier for the object this event is associated with when
|
||
it is not one of document, collection, or user.
|
||
format: uuid
|
||
readOnly: true
|
||
userId:
|
||
type: string
|
||
description: Identifier for the user associated with the event, if any.
|
||
format: uuid
|
||
readOnly: true
|
||
actorId:
|
||
type: string
|
||
description: The user that performed the action.
|
||
format: uuid
|
||
readOnly: true
|
||
authType:
|
||
type: string
|
||
description: The authentication method used to perform the action.
|
||
enum:
|
||
- api
|
||
- app
|
||
- mcp
|
||
- oauth
|
||
nullable: true
|
||
readOnly: true
|
||
actorIpAddress:
|
||
type: string
|
||
description: The ip address the action was performed from. This field is
|
||
only returned when the `auditLog` boolean is true.
|
||
example: 60.169.88.100
|
||
readOnly: true
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the associated collection, if any
|
||
readOnly: true
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier for the associated document, if any
|
||
readOnly: true
|
||
createdAt:
|
||
type: string
|
||
description: The date and time that this event was created
|
||
readOnly: true
|
||
format: date-time
|
||
data:
|
||
type: object
|
||
example:
|
||
name: Equipment list
|
||
description: Additional unstructured data associated with the event
|
||
readOnly: true
|
||
changes:
|
||
type: object
|
||
nullable: true
|
||
description: The set of changes made by this event. This field is only
|
||
returned when the `auditLog` boolean is true.
|
||
readOnly: true
|
||
actor:
|
||
"$ref": "#/components/schemas/User"
|
||
Error:
|
||
type: object
|
||
properties:
|
||
ok:
|
||
type: boolean
|
||
example: false
|
||
error:
|
||
type: string
|
||
message:
|
||
type: string
|
||
status:
|
||
type: number
|
||
data:
|
||
type: object
|
||
FileOperation:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
type:
|
||
type: string
|
||
example: export
|
||
description: The type of file operation.
|
||
readOnly: true
|
||
enum:
|
||
- import
|
||
- export
|
||
format:
|
||
type: string
|
||
description: The file format of the resulting file.
|
||
example: outline-markdown
|
||
readOnly: true
|
||
name:
|
||
type: string
|
||
description: >-
|
||
The name of the file operation, derived from the collection name,
|
||
document title, or file name.
|
||
readOnly: true
|
||
state:
|
||
type: string
|
||
description: The state of the file operation.
|
||
example: complete
|
||
readOnly: true
|
||
enum:
|
||
- creating
|
||
- uploading
|
||
- complete
|
||
- error
|
||
- expired
|
||
error:
|
||
type: string
|
||
nullable: true
|
||
description: An error message if the file operation failed.
|
||
readOnly: true
|
||
size:
|
||
type: string
|
||
description: >-
|
||
The size of the resulting file in bytes. Returned as a string as the
|
||
value may exceed the safe integer range.
|
||
readOnly: true
|
||
example: "2048"
|
||
collectionId:
|
||
type: string
|
||
nullable: true
|
||
description: >-
|
||
Identifier for the associated collection, if the file operation is
|
||
scoped to a single collection.
|
||
readOnly: true
|
||
format: uuid
|
||
documentId:
|
||
type: string
|
||
nullable: true
|
||
description: >-
|
||
Identifier for the associated document, if the file operation is
|
||
scoped to a single document.
|
||
readOnly: true
|
||
format: uuid
|
||
user:
|
||
"$ref": "#/components/schemas/User"
|
||
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
|
||
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
|
||
OAuthClient:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: The name of this OAuth client.
|
||
example: Acme Inc
|
||
description:
|
||
type: string
|
||
nullable: true
|
||
description: A short description of this OAuth client.
|
||
example: Integrate Acme Inc's services into Outline.
|
||
developerName:
|
||
type: string
|
||
nullable: true
|
||
description: The name of the developer who created this OAuth client.
|
||
example: Acme Inc
|
||
developerUrl:
|
||
type: string
|
||
nullable: true
|
||
description: The URL of the developer who created this OAuth client.
|
||
example: https://example.com
|
||
avatarUrl:
|
||
type: string
|
||
nullable: true
|
||
description: A URL pointing to an image representing the OAuth client.
|
||
clientId:
|
||
type: string
|
||
description: The client ID for the OAuth client.
|
||
readOnly: true
|
||
example: 2bquf8avrpdv31par42a
|
||
clientSecret:
|
||
type: string
|
||
description: The client secret for the OAuth client.
|
||
readOnly: true
|
||
example: ol_sk_rapdv31...
|
||
clientType:
|
||
type: string
|
||
description: The type of the OAuth client.
|
||
readOnly: true
|
||
enum:
|
||
- public
|
||
- confidential
|
||
redirectUris:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: The redirect URIs for the OAuth client.
|
||
example: ["https://example.com/callback"]
|
||
published:
|
||
type: boolean
|
||
description: Whether the OAuth client is available to other workspaces.
|
||
example: true
|
||
lastActiveAt:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: Date and time when this OAuth client was last used.
|
||
readOnly: true
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this OAuth client was created
|
||
readOnly: true
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this OAuth client was updated
|
||
readOnly: true
|
||
OAuthAuthentication:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
oauthClientId:
|
||
type: string
|
||
description: Identifier for the associated OAuthClient.
|
||
readOnly: true
|
||
format: uuid
|
||
oauthClient:
|
||
type: object
|
||
readOnly: true
|
||
description: A reduced, public representation of the associated OAuth client.
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
nullable: true
|
||
developerName:
|
||
type: string
|
||
nullable: true
|
||
developerUrl:
|
||
type: string
|
||
nullable: true
|
||
avatarUrl:
|
||
type: string
|
||
nullable: true
|
||
clientId:
|
||
type: string
|
||
published:
|
||
type: boolean
|
||
userId:
|
||
type: string
|
||
description: Identifier for the associated User.
|
||
readOnly: true
|
||
format: uuid
|
||
scope:
|
||
type: array
|
||
items:
|
||
type: string
|
||
lastActiveAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this authentication was last used
|
||
readOnly: true
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this authentication was created
|
||
readOnly: true
|
||
|
||
Revision:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the associated document.
|
||
readOnly: true
|
||
format: uuid
|
||
title:
|
||
type: string
|
||
description: Title of the document.
|
||
readOnly: true
|
||
name:
|
||
type: string
|
||
nullable: true
|
||
description: The name of the revision, if any.
|
||
readOnly: true
|
||
icon:
|
||
type: string
|
||
nullable: true
|
||
description: An emoji or icon associated with the revision.
|
||
readOnly: true
|
||
color:
|
||
type: string
|
||
nullable: true
|
||
description: The color of the revision icon in hex format.
|
||
readOnly: true
|
||
collaborators:
|
||
type: array
|
||
items:
|
||
"$ref": "#/components/schemas/User"
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this revision was created
|
||
readOnly: true
|
||
createdBy:
|
||
"$ref": "#/components/schemas/User"
|
||
createdById:
|
||
type: string
|
||
description: Identifier for the user who created this revision.
|
||
format: uuid
|
||
readOnly: true
|
||
deletedAt:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: Date and time when this revision was deleted, if applicable.
|
||
readOnly: true
|
||
sourceMetadata:
|
||
type: object
|
||
nullable: true
|
||
description: Metadata about how the revision was created, if any.
|
||
readOnly: true
|
||
properties:
|
||
authType:
|
||
type: string
|
||
description: The authentication method used to create the revision.
|
||
enum:
|
||
- api
|
||
- app
|
||
- mcp
|
||
- oauth
|
||
nullable: true
|
||
readOnly: true
|
||
RevisionDetail:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/Revision"
|
||
- type: object
|
||
properties:
|
||
data:
|
||
type: object
|
||
description: The body of the revision as a Prosemirror document.
|
||
readOnly: true
|
||
text:
|
||
type: string
|
||
description: Body of the document, may contain markdown formatting
|
||
readOnly: true
|
||
Share:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
documentTitle:
|
||
type: string
|
||
description: Title of the shared document.
|
||
example: React best practices
|
||
readOnly: true
|
||
documentUrl:
|
||
type: string
|
||
format: uri
|
||
description: URL of the original document.
|
||
readOnly: true
|
||
sourceTitle:
|
||
type: string
|
||
description: Title of the shared document or collection.
|
||
readOnly: true
|
||
sourcePath:
|
||
type: string
|
||
description: Path of the shared document or collection.
|
||
readOnly: true
|
||
documentId:
|
||
type: string
|
||
format: uuid
|
||
nullable: true
|
||
description: Identifier of the shared document, if any.
|
||
readOnly: true
|
||
collectionId:
|
||
type: string
|
||
format: uuid
|
||
nullable: true
|
||
description: Identifier of the shared collection, if any.
|
||
readOnly: true
|
||
urlId:
|
||
type: string
|
||
nullable: true
|
||
description: Short URL identifier for the share, if set.
|
||
readOnly: true
|
||
url:
|
||
type: string
|
||
format: uri
|
||
description: URL of the publicly shared document.
|
||
readOnly: true
|
||
domain:
|
||
type: string
|
||
nullable: true
|
||
description: Custom domain the share is served on, if any.
|
||
title:
|
||
type: string
|
||
maxLength: 255
|
||
nullable: true
|
||
description:
|
||
Override title displayed on the publicly shared page. If not set
|
||
the source document or collection title is used.
|
||
iconUrl:
|
||
type: string
|
||
format: uri
|
||
maxLength: 4096
|
||
nullable: true
|
||
description:
|
||
URL of an icon displayed on the publicly shared page, overriding
|
||
the workspace branding.
|
||
published:
|
||
type: boolean
|
||
example: false
|
||
description: If true the share can be loaded without a user account.
|
||
includeChildDocuments:
|
||
type: boolean
|
||
example: true
|
||
description: If to also give permission to view documents nested beneath
|
||
this one.
|
||
allowSubscriptions:
|
||
type: boolean
|
||
example: true
|
||
description: Whether visitors to the public share can subscribe to
|
||
receive email notifications when the document is updated. Requires
|
||
SMTP to be configured on the workspace.
|
||
allowIndexing:
|
||
type: boolean
|
||
description: Whether the shared page may be indexed by search engines.
|
||
showLastUpdated:
|
||
type: boolean
|
||
description: Whether to show the last-updated time on the shared page.
|
||
showTOC:
|
||
type: boolean
|
||
description: Whether to show a table of contents on the shared page.
|
||
views:
|
||
type: number
|
||
description: The number of times the shared page has been viewed.
|
||
readOnly: true
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this share was created
|
||
readOnly: true
|
||
createdBy:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/User"
|
||
nullable: true
|
||
description: The user that created the share. Only returned to viewers
|
||
with access to read the share; omitted from responses to
|
||
unauthenticated viewers of a published share, and when the creating
|
||
user has been deleted.
|
||
readOnly: true
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this share was edited
|
||
readOnly: true
|
||
lastAccessedAt:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
description: Date and time when this share was last viewed. Only returned
|
||
to workspace admins.
|
||
readOnly: true
|
||
Star:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
index:
|
||
type: string
|
||
description: Index of the star in the list of stars.
|
||
documentId:
|
||
type: string
|
||
description: Unique identifier for the starred document.
|
||
readOnly: true
|
||
format: uuid
|
||
nullable: true
|
||
collectionId:
|
||
type: string
|
||
description: Unique identifier for the starred collection.
|
||
readOnly: true
|
||
format: uuid
|
||
nullable: true
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this star was created
|
||
readOnly: true
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: Date and time when this star was last changed
|
||
readOnly: true
|
||
Team:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description:
|
||
The name of this workspace, it is usually auto-generated when the
|
||
first SSO connection is made but can be changed if necessary.
|
||
description:
|
||
type: string
|
||
nullable: true
|
||
description: A short description of this workspace.
|
||
avatarUrl:
|
||
type: string
|
||
format: uri
|
||
description:
|
||
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.
|
||
sharing:
|
||
type: boolean
|
||
description:
|
||
Whether this workspace has share links globally enabled. If this
|
||
value is false then all sharing UI and APIs are disabled.
|
||
defaultCollectionId:
|
||
type: string
|
||
description: If set then the referenced collection is where users will be
|
||
redirected to after signing in instead of the Home screen
|
||
format: uuid
|
||
defaultUserRole:
|
||
"$ref": "#/components/schemas/UserRole"
|
||
memberCollectionCreate:
|
||
type: boolean
|
||
description:
|
||
Whether members are allowed to create new collections. If false
|
||
then only admins can create collections.
|
||
memberTeamCreate:
|
||
type: boolean
|
||
description:
|
||
Whether members are allowed to create new groups. If false then only
|
||
admins can create groups.
|
||
documentEmbeds:
|
||
type: boolean
|
||
description:
|
||
Whether this workspace has embeds in documents globally enabled.
|
||
It can be disabled to reduce potential data leakage to third parties.
|
||
inviteRequired:
|
||
type: boolean
|
||
description:
|
||
Whether an invite is required to join this workspace, if false users
|
||
may join with a linked SSO provider.
|
||
allowedDomains:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: A hostname that user emails are restricted to
|
||
guestSignin:
|
||
type: boolean
|
||
description:
|
||
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.
|
||
subdomain:
|
||
type: string
|
||
description:
|
||
Represents the subdomain at which this workspace's knowledge base
|
||
can be accessed.
|
||
domain:
|
||
type: string
|
||
nullable: true
|
||
description: The custom domain configured for this workspace, if any.
|
||
url:
|
||
type: string
|
||
description:
|
||
The fully qualified URL at which this workspace's knowledge base
|
||
can be accessed.
|
||
readOnly: true
|
||
format: uri
|
||
passkeysEnabled:
|
||
type: boolean
|
||
description: Whether passkey authentication is enabled for this workspace.
|
||
preferences:
|
||
type: object
|
||
nullable: true
|
||
description: Workspace-level preference flags.
|
||
guidanceMCP:
|
||
type: string
|
||
nullable: true
|
||
description: Guidance text provided to MCP integrations.
|
||
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
|
||
invitedBy:
|
||
allOf:
|
||
- "$ref": "#/components/schemas/User"
|
||
nullable: true
|
||
description: The user that invited this user, if they were invited. Only
|
||
included in responses to admin users.
|
||
readOnly: true
|
||
Invite:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The full name of the user being invited
|
||
email:
|
||
type: string
|
||
description: The email address to invite
|
||
role:
|
||
"$ref": "#/components/schemas/UserRole"
|
||
UserRole:
|
||
type: string
|
||
enum:
|
||
- admin
|
||
- member
|
||
- viewer
|
||
- guest
|
||
CollectionStatus:
|
||
type: string
|
||
enum:
|
||
- archived
|
||
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
|
||
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
|
||
- mcp
|
||
createdAt:
|
||
type: string
|
||
description: The date and time that this object was created
|
||
readOnly: true
|
||
format: date-time
|
||
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
|
||
Ability:
|
||
description: A single permission granted by a policy
|
||
example: true
|
||
oneOf:
|
||
- type: array
|
||
items:
|
||
type: string
|
||
- type: boolean
|
||
GroupMembership:
|
||
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
|
||
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
|
||
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
|
||
View:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: Unique identifier for the object.
|
||
readOnly: true
|
||
documentId:
|
||
type: string
|
||
description: Identifier for the associated document.
|
||
readOnly: true
|
||
format: uuid
|
||
firstViewedAt:
|
||
type: string
|
||
description: When the document was first viewed by the user
|
||
readOnly: true
|
||
format: date-time
|
||
lastViewedAt:
|
||
type: string
|
||
description: When the document was last viewed by the user
|
||
readOnly: true
|
||
format: date-time
|
||
count:
|
||
type: number
|
||
description: The number of times the user has viewed the document.
|
||
example: 22
|
||
readOnly: true
|
||
userId:
|
||
type: string
|
||
format: uuid
|
||
description: Identifier of the user who viewed the document.
|
||
readOnly: true
|
||
user:
|
||
"$ref": "#/components/schemas/User"
|
||
responses:
|
||
NotFound:
|
||
description: The specified resource was not found.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
"$ref": "#/components/schemas/Error"
|
||
Validation:
|
||
description: The request failed one or more validations.
|
||
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"
|
||
Unauthenticated:
|
||
description: The API key is missing or otherwise invalid.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
"$ref": "#/components/schemas/Error"
|
||
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
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
description: Seconds in the future to retry the request, if rate limited.
|
||
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.
|
||
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
|