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:

• A pre-existing Quip for Customer 360 product
• Quip Plus
• Quip Advanced
• Lightning Experience in Enterprise, Professional, Performance, Unlimited, or Developer editions

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:

• https://platform.acme.onquip.com/1/threads/edit-document or
• https://platform.quip-acme.com/1/threads/edit-document

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:

• 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

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

Which API should I use, the Automation API or the Admin API?

We 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.

Which systems can integrate with Quip's APIs?

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.

Can I create a non-human user account for my integrations?

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.

Is there a way for the API keys to be rotated every 90 days automatically or would this be a manual action?

Currently, there's no way for the API keys to change automatically. You can only create API keys manually.

Which API calls are included in rate limits?

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.

Can we raise our rate limits?

If you need to call APIs more frequently than allowed by the Admin and Automation API rate limits, contact Quip Customer Support for help.

How do we monitor our API usage?

The responses in Quip's Admin and Automation APIs contain headers that provide information about your API usage.

Is there an API that can run reports on Quip engagement?

Use the Events API to get information about Quip engagement. You can then feed that information into your engagement monitoring systems.

What tools are available for Quip eDiscovery and eArchiving?

Consult our trusted partner for eDiscovery and eArchiving solutions at onna.com/quip.

How do I export my Quip data?

You can export Quip documents or spreadsheets to PDF using the Create Export PDF Request API method.

How do I export comments from a Quip document?

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.

How do we deprovision users?

The Disable User v1.1 or v2.0 API method allows you to deactivate a user account.

Can we subscribe to news about changes to API documentation or feature updates?

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.

More questions?

Ask other Quip developers on Salesforce Stack Exchange.

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:

• Version 1: GET https://platform.quip.com/1/admin/sampleresource.
• Version 2: GET https://platform.quip.com/2/admin/sampleresource.

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:

• You have an integration that points to version 1 of an API method at this path: GET https://platform.quip.com/1/admin/sampleresource
• Version 2 of the API method is introduced and version 1 is deprecated.
• Before support for version 1 ends, you must update your integration to point to version 2 of the API method at this path: GET https://platform.quip.com/2/admin/sampleresource.

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.

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:

• Limit the scopes in your API keys to the ones needed for the features in your integrations. For example, if you create an application whose users edit but don't manage content, don't include the USER_MANAGE scope in the API key for that application.
• Tokens expire every 30 days. Use the Token Endpoint to refresh your tokens before their expiration. That way your users have uninterrupted access to your integrations.
• Use Verify Token to see if a token is expired or revoked and find out which scopes apply to the token.
• Revoke tokens for integrations that you're no longer using. Deleting a token in Postman (or your other chosen tool) doesn't revoke access. You can use the Admin Console to revoke an API key that you're no longer using (under Settings > Integrations > Action menu > Revoke).

Personal Authentication Process

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.

OAuth Process

Prerequisites

To access to the Quip Admin and Automation APIs:

• You must be an admin to create an API key.
• In addition, for access to the Admin API, your admin has to add you to the Admin API Users list in the Admin Console (under Settings > Site Settings).

Note: These Admin APIs are available only as add-on purchases: Events API and Governance API.

Process Overview

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.

Generate an OAuth Token

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:

• You can create additional API keys for your integrations with only the applicable scopes needed for the features in the integrations.
• You can create a maximum of 100 API keys for your company. We suggest that you keep this limit in mind when you create API keys for your integrations. You can see all the API keys your company has in the Quip Admin Console under Settings > Integrations.

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:

• Token Name: Give the token a short, descriptive name. When you create additional tokens for your integrations, use a name that easily identifies the integration.
• Callback URL: https://platform.quip.com
• Authorize using browser: Leave the box unchecked.
• Auth URL: 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 or
  • https://platform.quip-<customername>.com/1/oauth/login
• Access Token URL: 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 or
  • https://platform.quip-<customername>.com/1/oauth/access_token
• Client ID and Client Secret: Use the values that you copied from the API key in the Quip Admin Console.
• Scope and State: Leave blank.
• Client Authentication: Select Send client credentials in body.

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:

• Browse through the reference documentation to see what you can build with our APIs.
• Download our OpenAPI Specification (OAS) files to build your integrations.
• Check out our sample apps.
• Use a token associated with an API key together with domain authentication to build applications that integrate 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:

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.

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.

Add an Item at the End of a List

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:

Add a Paragraph before Other Content

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:

Add Multiple Paragraphs after Other Content

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:

Edit a Paragraph/Replace Content

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:

Delete a Document Range

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:

Add, Edit, or Replace Content in or Around a Document Range

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:

Add a Row to a Spreadsheet

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:

Edit a Cell in a Spreadsheet

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:

Add a Live App after Other Content

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.

Edit Content in a Live App

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

Summary of Additional Use Cases for Adding Live Apps

  <div data-live-app-id='XdJAjAN5Jbi' data-live-app-payload='{
    "record_id": "0013h00000C9tHJAAZ",
    "org_id": "00D3h000004XoQgEAK" }'>
  </div>

  <div data-live-app-id='QYUAjAGNxIo' data-live-app-payload='{
    "list_id": "00B3h000005lR7jEAE",
    "object_type": "Account",
    "org_id": "00D3h000004XoQgEAK" }'>
  </div>

  <div data-live-app-id='QYUAjAGNxIo' data-live-app-payload='{
    "record_id": "0013h00000Db6YAAAZ",
    "related_list_type": "Contact",
    "org_id": "00D3h000004XoQgEAK" }'>
  </div>

  <div data-live-app-id='KORAjAYHE50' data-live-app-payload='{
    "columns": [
        {
          "color": "RED",
          "headerContent": "To Do",
          "cards": [
              {
                "color": "RED",
                "content": "First Card"
              }
          ]
        },
        {
          "color": "YELLOW",
          "headerContent": "In Progress",
          "cards": [
              {
                "color": "YELLOW",
                "content": "Second Card"
              },
              {
                "color": "YELLOW",
                "content": "New Card"
              }
          ]
        },
        {
          "color": "BLUE",
          "headerContent": "Title",
          "cards": [
              {
                "color": "BLUE",
                "content": ""
              },
              {
                "color": "BLUE",
                "content": "Third Card"
              },
              {
                "color": "BLUE",
                "content": "New Card"
              }
          ]
        }
    ] }'>
  </div>

<div data-live-app-id='JdGAjAc35Es' data-live-app-payload='{
  "columns": [
      {
        "content": "Project\\n",
        "type": "TEXT",
        "id": "0"
      },
      {
        "content": "Owner\\n",
        "type": "PERSON",
        "id": "1"
      },
      {
        "content": "Status\\n",
        "type": "STATUS",
        "id": "2",
        "options": [
            {
              "label": "Upcoming",
              "devName": "upcoming",
              "color": "BLUE"
            },
            {
              "label": "In Progress",
              "devName": "in_progress",
              "color": "YELLOW"
            },
            {
              "label": "Complete",
              "devName": "complete",
              "color": "GREEN"
            }
        ]
      },
      {
        "content": "Deadline\\n",
        "type": "DATE",
        "id": "3"
      },
      {
        "content": "Attachment\\n",
        "type": "FILE",
        "id": "4"
      }
  ],
  "rows": [
      {
        "0": "Test\\n",
        "1": [
            "dFdAEAoma2c"
        ],
        "2": "upcoming",
        "3": 1605686400000,
        "4": null
      },
      {
        "0": "New Project\\n",
        "1": [],
        "2": null,
        "3": null,
        "4": null
      },
      {
        "0": "New Project\\n",
        "1": [],
        "2": null,
        "3": null,
        "4": null
      }
  ] }'>
</div>

See also

Edit a Document reference documentation

How Does Live Data Work in Quip?

Live Apps Developer Guide