Welcome to the documentation for the Automation API. This documentation describes the functionality available only in the current versions of API methods. You can also review the documentation for all API methods for information about both current and deprecated API methods.
The Quip Automation API provides read/write access to Quip, enabling you to automate processes and integrate Quip with other products you or your company uses.
The Automation API is REST-based. Responses are JSON, and errors are reported via standard HTTP codes in addition to JSON-formatted error information in the HTTP response bodies of relevant requests. We use OAuth 2 for authentication and authorization.
Quip integrates documents and messages into a single unit that we call a thread. Most of the operations in the Quip Automation API operate on threads. Threads can simply be a list of messages, i.e., a chat thread, or they may have a document in addition to a list of messages. Each thread has a permanent 11 character id and a similar 12 character URL suffix that can be expired by the user. Apps receiving URLs should convert them to permanent ids using Get Thread before being used.
Quip documents are broken down into smaller units we call sections. Every paragraph in a document is a separate section, as is every item in a list or cell in a table. The Quip Automation API outputs documents as HTML for convenience, and the elements in the HTML have id attributes specifying their internal section ID. When you want to perform advanced transforms on a document, like modifying a checklist, you will need to use the section IDs. The official Python library contains a number of examples of parsing the HTML to get section IDs and using that data for edit operations.
Quip folders are not traditional file system folders. Quip folders are more like tags, i.e., a thread can be in multiple folders. When a thread is in a folder, it inherits the permissions of the folder, e.g., if you add a thread to a folder shared with three people, those three people will have access to the thread. Each user has special desktop and archive folders that cannot be deleted, shared, or renamed.
A Quip thread can be shared with a list of folders and individual users. A user can access the thread if they have access to any of the folders or if they are individually added to the thread.
We refer to the people in threads and folders as members throughout the API.
Quip’s APIs have rate limits to help ensure fair and reliable access to APIs for all of our customers.
When you call our APIs via integrations you build (including integrations using Process Builder and Flow), those calls are subject to our rate limits.
The Automation API is rate limited by number of requests per minute per user - with defaults of:
API responses include a few custom headers to help developers implement backoffs in their code. These headers are:
X-Ratelimit-Limit: The number of requests per minute/hour the user can makeX-Ratelimit-Remaining: The number of requests remaining this user can
make within the minute/hour. This number changes with each requestX-Ratelimit-Reset: The UTC timestamp for when the rate limit resetsQuip’s APIs are also subject to a per-company rate limit with a default of 600 requests per minute. The API responses include these custom headers to help developers implement backoffs in their code:
X-Company-RateLimit-Limit: The number of requests per minute that your company can makeX-Company-RateLimit-Remaining: The number of requests remaining for your company within the minuteX-Company-RateLimit-Reset: The UTC timestamp for when the rate limit resetsX-Company-Retry-After: The number of seconds after which your company can make API calls againTo improve the quality and performance of API methods, Quip periodically releases new versions and deprecates older versions. Examples of changes that sometimes require creating new versions are:
Versions are identified in the path for each API method. Examples:
We inform you in a release note at least one year before support for an API method ends. In addition, we update the reference documentation to identify the current and deprecated versions of an API method. Our REST APIs have two versions of reference documentation:
Update your integrations so that they point to the current version instead of a deprecated version before support for an API method ends. Example scenario:
As needed, for your integrations, you can download the OpenAPI Specification (OAS) files for current and all versions of each REST API.
Use an OAuth2 compatible mechanism for authentication. This approach follows RFC 6749.
API endpoints decorated with this security scheme accept authentication tokens as described in RFC 6750. In most cases, this means that they will accept an Authorization header with content "Bearer <token>", where <token> is the value of an access token obtained through the OAuth flow.
| Security Scheme Type | OAuth2 |
|---|---|
| authorizationCode OAuth Flow | Authorization URL: https://platform.quip.com/1/oauth/login Token URL: https://platform.quip.com/1/oauth/access_token Refresh URL: https://platform.quip.com/1/oauth/access_token Scopes:
|
You can generate an access token that provides API access to your own, personal Quip account. This is useful for testing the API, automating tasks, or integrating with other services you use individually.
To generate a personal access token, visit this page: https://quip.com/dev/token
Whenever you generate a new token, all previous tokens are automatically invalidated.
Once you have a token, the easiest way to use it is via the Python Client Library, which makes most tasks a single line of code. All of the documentation below contains copy-and-paste Python code snippets to make it easier to get started.
Domain authentication is only available for Quip Enterprise administrators. To enable this for your company, contact us.
Domain authentication enables seamless integration for internal or pre-approved services at your company. Domain authentication is simply OAuth 2.0, but instead of end users individually approving access to each application, domain administrators pre-approve applications, and end users do not see additional authorization prompts during the OAuth authorization process.
To enable domain authentication for a third-party application:
/oauth/login and the OAuth 2.0 token endpoint /oauth/access_token.After you have obtained a verification code or refresh token, you can exchange it for an access token via a POST request to this endpoint.
| grant_type required | string Enum: "refresh_token" "authorization_code" Either |
| client_id required | string The client ID you created for your application. |
| client_secret required | string The client secret you created for your application. |
| refresh_token | string Required if |
| code | string Required if |
| redirect_uri | string Required if |
{- "access_token": "string",
- "expires_in": 0,
- "refresh_token": "string",
- "scope": "string",
- "token_type": "Bearer"
}