Documentation Powered by ReDoc

Admin API (Current)

License: Proprietary

Welcome to the documentation for the Admin 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

For governance and security purposes, Quip makes available a set of APIs to enable specific users to see all content within a Quip site and to take actions against that content.

Requirements

This API requires that you have first followed the setup instructions for the Quip Automation API.

To call this API, the access token you use must be for a user who is an admin.

You must also have the admin API enabled for your quip instance. Ask your support representative if you would like this functionality enabled.

License Requirements

You can access Quip's APIs if your company uses any of these products:

  • A pre-existing Quip for Customer 360 product
  • 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.

VPC Customers

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:

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 Admin API is rate limited by number of requests per minute per user - with defaults of:

  • 100 requests per minute per user
  • 1500 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

FAQs

Quip Developer FAQ

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.

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

Overview

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.

OAuth2

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 Admin 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:
  • ADMIN_READ -

    Provides access to GET calls that read data.

  • ADMIN_WRITE -

    Provides access to POST, DELETE, and PATCH calls that edit data.

  • ADMIN_MANAGE -

    Provides access to API calls that perform admin actions. Examples: add or remove users, quarantine data, manage data hold policies.

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.

Best Practices

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

Get Access to Quip's APIs


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.

Next Steps

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

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.

Threads

Get a Blob from a Thread

Returns the contents of specified blob from the thread.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
thread_id
required
string

The ID of the thread that contains the desired blob.

blob_id
required
string

The ID of the blob to return.

query Parameters
company_id
required
string

The ID of the company to use.

header Parameters
If-None-Match
string

Header containing a 'blob_id'. If this ID matches the path parameter 'blob_id' and the blob exists, an HTTP status code 304 is returned.

Responses

Response samples

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

Add a Blob to a Thread

Uploads an image or other blob to the given thread. Returns a url that may be used in the content field of Edit Document requests and an id that may be used in the attachment field of Add a Message.

Authorizations:
OAuth2 (ADMIN_WRITE)
path Parameters
thread_id
required
string

The ID of the thread to add the blob to.

Request Body schema: application/x-www-form-urlencoded
blob
required
string <binary>

The image or blob binary.

company_id
required
string

The ID of the company to use.

Responses

Response samples

Content type
application/json
{
  • "id": "DiPp1ZQyC8QUtvBT4vojzM",
  • "url": "/blob/LeSAAAqaCfc/DiPp1ZQyC8QUtvBT4vojzM"
}

Add People to a Thread or Add a Thread to Folders

The member_ids parameter must contain a list of folder IDs and user IDs. Specified users will be added to the document and the thread will be added to the specified folders.

Authorizations:
OAuth2 (ADMIN_MANAGE)
Request Body schema: application/x-www-form-urlencoded
One of
thread_id
required
string

The ID or secret path of the thread to get information about. You can pass in either of these identifiers:

member_ids
required
string

A comma-separated list of folder IDs and user IDs. We add each user individually to the thread. We add the thread to each of the specified folder IDs. If you pass in a folder ID, use either of these folder identifiers:

  • Folder id: Identifier returned in the id field when you call the Get Folder API method.
  • Secret path: 12-character identifier that you can find in the URL of the folder. For example, in the URL "https://quip.com/N5aaOTih0VYy/TeamFolder", the secret path is N5aaOTih0VYy.

The member_ids field is required if you didn't pass in a member_ids_by_access_level value. If you pass in a member_ids value instead of a member_ids_by_access_level, the access level defaults to Full Access.

Note: For better performance, it’s recommended that you add no more than 1,000 items to a folder. There’s a maximum limit of 4,000 items per folder. Items include documents, spreadsheets, and subfolders. When your API call exceeds the suggested limit of 1,000 items, a warning message is returned in the API response. When your API call exceeds the maximum limit of 4,000 items, the request isn’t executed and the 400 error code is returned. For more information, see Folder Limits.

Responses

Response samples

Content type
application/json
{
  • "thread": {
    },
  • "user_ids": [
    ],
  • "shared_folder_ids": [
    ],
  • "expanded_user_ids": [
    ],
  • "invited_user_emails": [ ],
  • "access_levels": {
    },
  • "html": "..."
}

Copy a Document or Template

Makes a copy of the document specified by the thread_id argument. The source document can also be treated as a template. To use the source document as a template, the values query argument must contain a valid JSON dictionary that consists of string keys and whose values are either string, numbers or other dictionaries. The endpoint will scan the document for a text pattern like:

[[varname]]

where varname consists of a series of alphanumeric characters and underscores (_). It will then look up 'varname' in the values dictionary and replace the pattern with its value.

In addition, patterns can contain one or more dots (.) like:

[[varname1.varname2]]

In this case, the endpoint will separate the string into 'varname1' and 'varname2'. If it finds varname1 in the first dictionary, it will expect that value to be another dictionary and will then use varname2 to look for another value. For example, if values has the following JSON representation:

{ "user": { "name": "Arnie", "age": "34" }}

The template variable [[user.name]] will be substituted with 'Arnie'.

If the key specified in the template variable can't be found in the values dictionary, then the template variable pattern is left unchanged in the document.

Authorizations:
OAuth2 (ADMIN_READADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/x-www-form-urlencoded
Request Body schema: application/x-www-form-urlencoded
thread_id
required
string

The ID or secret path of the document to be copied:

values
string

If you want to make a copy of a template and fill it in with your specified content, pass a JSON dictionary into this field. In the JSON dictionary, the keys must be strings and the values must be either strings or dictionaries. Keys can contain only the characters A-Z, a-z, 0-9, .(period) and _(underscore). For example:

  1. You have a document you want to copy that's a template containing these fields:

    Name = [[Customer.Name]]

    Age = [[Customer.Age]]

    [[Greeting]], [[Customer.Name]]!

  2. You pass this JSON dictionary into the values field:

    {"Customer": {"Age": 34, "Name": "Arnie"}, "Greeting": "Hello"}

  3. The copy of the document displays this content:

    Name = Arnie

    Age = 34

    Hello, Arnie!

member_ids
string

Comma-separated list of user IDs of people who can access the new thread. If you don't pass in member_ids, only the user who called this API method has access to the new thread. There's a maximum limit of 100 member_ids per request. The default access level is Full Access, which means that added users can edit, comment on, and share the thread.

folder_ids
string

Comma-separated list of identifiers of the folders you want to add the new thread to. If you don't pass in folder_ids, the new thread is added to the private folder of the user who called this API method. There's a maximum limit of 100 folder_ids per request. You can pass in either of these identifiers:

  • folder_id: Identifier returned in the id field when you call the Get Folder API method.
  • secret path: 12-character identifier that you can find in the URL of the folder. For example, in this URL: "https://quip.com/N5aaOTih0VYy/TeamFolder", the secret path is N5aaOTih0VYy.

Note: For better performance, it’s recommended that you add no more than 1,000 items to a folder. There’s a maximum limit of 4,000 items per folder. Items include documents, spreadsheets, and subfolders. When your API call exceeds the suggested limit of 1,000 items, a warning message is returned in the API response. When your API call exceeds the maximum limit of 4,000 items, the request isn’t executed and the 400 error code is returned. For more information, see Folder Limits.

title
string

The name of the new thread. The title is used as the first line of a document. We recommend that you pass in a title to clearly identify the new thread. If you don't pass in a title, the names of the original and new threads are the same.

copy_annotations
boolean
Default: false

Determines whether to copy comments in the original thread to the new thread. Possible values are:

  • true: Comments in the original thread are copied to the new thread.
  • false: Comments in the original thread aren't copied to the new thread.

Responses

Response samples

Content type
application/json
{
  • "thread": {
    },
  • "user_ids": [
    ],
  • "shared_folder_ids": [
    ],
  • "expanded_user_ids": [
    ],
  • "invited_user_emails": [ ],
  • "access_levels": {
    },
  • "html": "..."
}