Automation API (Current)

License: Proprietary

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.

Summary

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.

Core Concepts

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.

Rate Limits

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.

Per-user Rate Limits

The Automation API is rate limited by number of requests per minute per user - with defaults of:

  • 50 requests per minute per user
  • 750 requests per hour per user

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 make
  • X-Ratelimit-Remaining: The number of requests remaining this user can make within the minute/hour. This number changes with each request
  • X-Ratelimit-Reset: The UTC timestamp for when the rate limit resets

Per-company Rate Limit

Quip’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 make
  • X-Company-RateLimit-Remaining: The number of requests remaining for your company within the minute
  • X-Company-RateLimit-Reset: The UTC timestamp for when the rate limit resets
  • X-Company-Retry-After: The number of seconds after which your company can make API calls again

REST API Versioning FAQ

Why do API methods get versioned?

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

  • Renaming an API method; or
  • Adding a required input field; or
  • Removing or renaming an input field; or
  • Removing an output field.

How do I know which version of an API method I’m using?

Versions are identified in the path for each API method. Examples:

How will I know when an API method is deprecated?

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:

  • Current: Describes the functionality available only in the current versions of methods in a REST API.
  • All: Describes the functionality available in both current and deprecated versions of methods in a REST API.

What should I do when an API method is deprecated?

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.

Authentication

OAuth2

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:
  • USER_MANAGE -
  • USER_READ -
  • USER_WRITE -

Personal Authentication

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

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:

  1. Create an OAuth 2.0 token for the application you want to integrate. You will typically create a separate token for each app you want to integrate and name it after the app, which enables easy revocation when your company is no longer using the service.
  2. Configure the application with the OAuth 2.0 authorization endpoint /oauth/login and the OAuth 2.0 token endpoint /oauth/access_token.
  3. When a member of your company uses the application to access Quip, the authorization redirects will happen automatically and will not ask for any additional approval.

Token Endpoint

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.

query Parameters
grant_type
required
string
Enum: "refresh_token" "authorization_code"

Either refresh_token or authorization_code.

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 grant_type is refresh_token.

code
string

Required if grant_type is authorization_code.

redirect_uri
string

Required if grant_type is authorization_code. Must match the redirect_uri supplied when requesting that authorization code.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "scope": "string",
  • "token_type": "Bearer"
}

Authorization Endpoint

Redirect end users to this URL to get an OAuth 2.0 verification code, which you can exchange for an access token.

query Parameters
client_id
required
string

The client ID you created for your application.

client_secret
required
string

The client secret you created for your application.

redirect_uri
required
string
Example: redirect_uri=https://app.postman.com/oauth2/callback

The URL we should redirect back to with the verification code.

state
integer
Example: state=1234

If given, we include this argument in our redirect back to the redirect_uri. This is recommended to prevent a variety of security issues.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": 400,
  • "error_description": "string"
}

Revoke a Token

Revoke an access_token or a refresh_token.

query Parameters
client_id
required
string

The client ID you created for your application.

</