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.
You can access Quip's APIs if your company uses any of these products:
Note: These Admin APIs are available only as add-on purchases: Events API and Governance API.
If you're a Virtual Private Cloud (VPC) customer, you can call Quip's APIs using URIs in which you replace: quip.com with customername.onquip.com or quip-customername.com.
For example, if your company is Acme and the URI is https://platform.quip.com/1/threads/edit-document, as a VPC customer, use one of these URIs instead depending on your company's assigned VPC URL:
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 againWe recommend that you use the Automation API to automate user-level processes such as document copying and editing and to integrate Quip with your other systems. Use the Admin API for admin-level site-wide or security workflows such as activity monitoring or quarantining documents.
Quip's APIs integrate with Salesforce, Slack, Google Workspace, Github, Jira, Stripe, Dropbox, Box, Zendesk and more. You can connect nearly any application to Quip using our APIs, including your company's proprietary applications or systems. Browse our sample apps or download prebuilt apps on Salesforce AppExchange.
In the Quip Admin Console, create a placeholder user (not associated with an employee) or bot user for your integrations. That way, when you deprovision an employee's user account, the integration isn't affected. Additionally, this allows for a more clear separation of duties between an employee and an integration user.
Currently, there's no way for the API keys to change automatically. You can only create API keys manually.
All of your company's Admin and Automation API calls are counted in your rate limits, including calls you make via Process Builder and Flow. There are per-user and per-company rate limits for the Admin and Automation APIs.
If you need to call APIs more frequently than allowed by the Admin and Automation API rate limits, contact Quip Customer Support for help.
The responses in Quip's Admin and Automation APIs contain headers that provide information about your API usage.
Use the Events API to get information about Quip engagement. You can then feed that information into your engagement monitoring systems.
Consult our trusted partner for eDiscovery and eArchiving solutions at onna.com/quip.
You can export Quip documents or spreadsheets to PDF using the Create Export PDF Request API method.
Use the Get Recent Messages API method to retrieve the 25 most-recent comments in a Quip document. You can then export the response of your API call to your other systems.
The Disable User v1.1 or v2.0 API method allows you to deactivate a user account.
Read the release notes to find out about new Quip developer features. Subscribe to the Salesforce Developer newsletter to get developer news, tips, and best practices. You can also follow these social media channels: SalesforceDevs Twitter feed, SalesforceDevs LinkedIn page, SalesforceDevs Facebook page.
Ask other Quip developers on Salesforce Stack Exchange.
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:
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.
Authentication gives you access to the Quip Admin and Automation APIs. You can build integrations that call our APIs. To access Quip's APIs, first create an API key. Then get an access token using the API key as described in Get Access to Quip's APIs. You can create additional API keys for your other integrations with the applicable scopes needed for the features in a specific integration. You can also get a personal access token to test our APIs.
Use an OAuth2-compatible mechanism for authentication. Quip's approach follows RFC 6749.
Our API endpoints accept authentication tokens as described in
RFC 6750.
In most cases, this means that when you call our API endpoints, you
can pass in an Authorization
header with content
"Bearer {{token}}". {{token}} is the value of an access token obtained
by following the steps described in
Get Access to Quip's APIs.
The only endpoints that don't require an Authorization header are these
Authentication endpoints:
Token Endpoint,
Authorization Endpoint,
Revoke a Token.
This table lists the URLs for Quip's Authentication endpoints that you can call when you build your integrations. In addition, this table describes available scopes for the Automation API. See the Domain Authentication section and the reference documentation linked to in this table for information about using the authentication endpoints.
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:
|
Note: Before building applications, you must select your required scopes when you create the API keys. And ensure that your application users have the correct access to the content they'll use in your applications. For example, if users need to edit a Quip document using your application, they must have edit access on that document.
Here are some recommended practices to follow to protect your Quip data and improve your user experience:
USER_MANAGE
scope in the API key for that application.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.
To access to the Quip Admin and Automation APIs:
Note: These Admin APIs are available only as add-on purchases: Events API and Governance API.
To get access to the Quip Admin and Automation APIs, follow the process summarized in the diagram below. The process is described in detail in the Generate an OAuth Token section.
1. Create an API Key
a. In the Quip Admin Console create an API key and select the scopes that you need for the features in your integration.
b. Copy the client ID and client secret so you can use them to get an access token.
Note:
2. Get an Access Token
Use your preferred tool such as Postman or SoapUI to get an access token. This example uses Postman:
a. Create a request in Postman.
b. Click the Authorization tab.
c. From the Type dropdown list, select Oauth 2.0.
d. In the Configure New Token section, fill in the fields as described here:
https://platform.quip.com
https://platform.quip.com/1/oauth/login
If you're a
Virtual Private Cloud
(VPC) customer, use one of these URLs instead, depending on your
company's assigned VPC URL:https://platform.<customername>.onquip.com/1/oauth/login
orhttps://platform.quip-<customername>.com/1/oauth/login
https://platform.quip.com/1/oauth/access_token
If you're a VPC customer, use one of these URLs instead, depending
on your company's assigned VPC URL:https://platform.<customername>.onquip.com/1/oauth/access_token
orhttps://platform.quip-<customername>.com/1/oauth/access_token
e. Click Get New Access Token.
3. Get authorization from Quip
When prompted, use your admin email address and password to log into your Quip site and get an authorization token. This is required only the first time you get an access token.
4. Save the Token
In Postman, the token details are displayed. Click Use Token to save the provided token in your request and use it in your next API call.
Congratulations! You can now make Admin and Automation API calls. Follow these same instructions to get additional access tokens using API keys with the scopes required for the integrations you're building.
Note: Tokens expire every 30 days. Use the Token Endpoint to refresh your tokens before the 30-day expiration. That way your users have uninterrupted access to your integrations.
Now that you have access to our APIs, you can start building your integrations with Quip:
Questions? Ask the Quip developer community on Salesforce Stack Exchange.
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"
}
Revoke an access_token
or a refresh_token
.
client_id required | string The client ID you created for your application. |
client_secret required | string The client secret you created for your application. |
token required | string The token to revoke. |
{ }
This document provides sample calls for some common use cases for the Edit
a Document API method. In the examples below, we use the HTML format for
the document content. You can mix and match the examples based on your
business needs. See the Edit a Document
reference documentation for more details including a sample response and
information about the section_id
, location
, data-live-app-id
, and
document_range
fields.
Note: If you're a Virtual Private Cloud (VPC) customer, see the Access Rules for more information about URIs to use for your API calls.
In this example, the section_id
belongs to an item at the end (location
2) of a bulleted or numbered list or checklist.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "<li>Expert recommendations</li>",
"section_id": "HcDACAX1iOK",
"location": 2
}
Here's how the list looks before and after the API call:
Before the call | After the call |
---|---|
|
|
In this example, the section_id
belongs to a paragraph before (location
3) which another paragraph is added.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "XerkArZUfekP",
"format": "html",
"content": "<p>Here's the account information for Acme Company:</p>",
"section_id": "HcDACAwByNQ",
"location": 3
}
Here's how the paragraph looks before and after the API call:
Before the call | After the call |
---|---|
This customer is on the west coast. |
Here's the account information for Acme Company: This customer is on the west coast. |
In this example, the section_id
belongs to a paragraph after (location
2) which multiple paragraphs are added.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "<p>Customers like Acme want more options.</p><p>They like personalized service.</p>",
"section_id": "HcDACAJZEQf",
"location": 2
}
Here's how the content looks before and after the API call:
Before the call | After the call |
---|---|
Here's the account information for Acme Company: This customer is on the west coast. |
Here's the account information for Acme Company: This customer is on the west coast. Customers like Acme want more options. They like personalized service. |
In this example, the section_id
belongs to the paragraph that's
edited/replaced (location 4). You can edit/replace a document range
instead, by passing 8 into the location field. See the Edit a
Document reference documentation for more
information about the document_range
field.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "<p>Customers like Acme want more choices. They want a buffet experience.</p>",
"section_id": "HcDABAJZEQf",
"location": 4
}
Here's how the paragraph looks before and after the API call:
Before the call | After the call |
---|---|
Customers like Acme want more options. |
Customers like Acme want more choices. They want a buffet experience. |
In this example, the document_range
belongs to the content (heading title
Topic 2 - Prerequisites and content under that heading and its
subheadings) that's deleted (location 9).
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"location": 9,
"document_range": "Topic 2 - Prerequisites"
}
Here's how the content looks before and after the API call:
Before the call | After the call |
---|---|
Topic 1 - IntroductionContent under Topic 1. Topic 2 - PrerequisitesContent under Topic 2. Subtopic 2.1Content under Subtopic 2.1. Subtopic 2.1.1Content under Subtopic 2.1.1. Topic 3 - Acceptance CriteriaContent under Topic 3. |
Topic 1 - IntroductionContent under Topic 1. Topic 3 - Acceptance CriteriaContent under Topic 3. |
In this example, the document_range
belongs to the content (heading title
Topic 4 - Important Notes and content under that heading and its
subheadings) that's edited/replaced (location 8). You can add content
before or after a document range by passing 7 (before) or 6 (after) into
the location
field. See the Edit a
Document reference documentation for
more information about the document_range
field.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"content": "<h2>Topic 4 - Considerations</h2><p>Our beta launch requires training users who speak multiple languages.</p>",
"location": 8,
"document_range": "Topic 4 - Important Notes"
}
Here's how the content looks before and after the API call:
Before the call | After the call |
---|---|
Topic 4 - Important NotesOur beta launch requires user training.
|
Topic 4 - ConsiderationsOur beta launch requires training users who speak multiple languages. |
In this example, the section_id
belongs to the row after (location 2)
which another row is added.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "<tr><td>7</td><td>4,581</td><td>570</td></tr>",
"section_id": "temp:C:dabc38cb2d6f789b426a14f31946",
"location": 2
}
Here's how the spreadsheet looks before and after the API call:
Before the call | After the call | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
In this example, the section_id
belongs to the cell that's edited/replaced
(location 4).
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "98",
"section_id": "temp:s:HcDACAFj25V_temp:C:HcD5aa735cfd0dd58e3eee0e5ef0",
"location": 4
}
The table below shows how the spreadsheet looks before and after the API call. In this example, the first cell in the spreadsheet is edited:
Before the call | After the call | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
The data-live-app-id
mentioned in the content
field applies to the type of
live app that's added. In this example, the live app is a calendar and the
section_id
belongs to a paragraph after (location 2) which the calendar is
added. This scenario adds a calendar containing two events scheduled for 4
October 2021 and 18 October 2021.
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "<div data-live-app-id='AbNBjAC13no' \
data-live-app-payload='{\
\"events\":[\
{\
\"color\":\"GREEN\",\
\"dateRange\":{\"start\":\"2021-10-04\",\"end\":\"2021-10-04\"},\
\"content\":\"Kickoff Meeting\"\
},\
{\
\"color\":\"RED\",\
\"dateRange\":{\"start\":\"2021-10-18\",\"end\":\"2021-10-18\"},\
\"content\":\"Project Status\"\
}],\
\"displayMonth\":\"2021-10\"\
}'>\
</div>",
"section_id": "HcDACAxeuYo",
"location": 2
}
Here's how the content looks before and after the API call:
Before the call | After the call |
---|---|
Let's start a customer satisfaction project.
|
|
In this example, the section_id
belongs to the cell in the live app that's
edited/replaced (location 4). This scenario replaces the name of the
calendar event "Kickoff Meeting" with "Project Kickoff".
POST https://platform.quip.com/1/threads/edit-document
Content-Type: application/json
Authorization: Bearer ABCSampleAccessToken
{
"thread_id": "vTYlBwL8UT85",
"format": "html",
"content": "Project Kickoff",
"section_id": "temp:C:HcDe5a29801dd43ce5b7d68c43f3",
"location": 4
}
Here's how the content looks before and after the API call:
Before the call | After the call |
---|---|
|
|
Live App Type | Summary of Use Case | Sample HTML for Content Field |
---|---|---|
Salesforce Record | Add a Salesforce record |
|
Salesforce List | Add a Salesforce record list |
|
Salesforce List | Add a Salesforce related list |
|
Kanban Board | Add a Kanban board with three columns:
|
|
Project Tracker | Add a project tracker with five columns::
|
|