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": "..."
}

Delete a Thread

Deletes the thread with the specified ID or secret.

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

The ID or secret path of the thread to delete.

wipeout
boolean
Default: false

Whether to permanently delete the thread.

Responses

Response samples

Content type
application/json
{ }

Edit A Document

Incrementally modifies the content of a document.

To get the IDs of sections in an existing document, parse the HTML returned. Every paragraph, list item, and table cell will have an HTML id attribute you can use in this method.

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

The ID or secret path of the thread whose document you want to edit:

format
string
Default: "html"
Enum: "html" "markdown"

Format of the content field. Required unless location is 5 (DELETE_SECTION).

content
string

The HTML or Markdown for the content that you want to add. There's a maximum limit of 1 MB of content per request. You can add a live app by using a <div> tag containing these values in the content field:

  • data-live-app-id: ID of the type of live app you want to add. For your company, this ID is always the same for the same type of live app. For a live app currently in a document, you can find this ID in the html field returned by the Get Thread API method. For example, for a calendar, you can call the Get Thread API and the html field returns something similar to: data-live-app-id='AbNBjAC13no'. Pass 'AbNBjAC13no' into the content field every time you want to add a calendar to a document.
  • data-live-app-payload: A JSON string containing the data that you want to include in the live app.

Note: We support most of the Markdown tags. The exceptions are described in the differences in the Python-Markdown implementation.

section_id
string

The ID of the part of the thread where you want to add content. Each of these types of content has its own section_id: paragraph, list item, graphic, spreadsheet row, spreadsheet or live app cell, and live app. This field is required if the location is AFTER_SECTION, BEFORE_SECTION, REPLACE_SECTION, or DELETE_SECTION. Provide either a section_id or a document_range.

  • To find a section_id for all content except live app and spreadsheet data:

    • Select content in a thread and use this keyboard shortcut to copy a link to the content:
      • Windows: Ctrl + Shift + A
      • Mac: Command + Shift + A

    Paste the link into a text editor. The section_id is after the "#". For example, in this link: "https://quip.com/vXYlZwL8Ul35/CustomerFeedback#temp:C:UHA3342fed2be3f401fb513dc0cf", the section_id is temp:C:UHA3342fed2be3f401fb513dc0cf.

  • To find a section_id for all content including live app and spreadsheet data (for embedded and standalone spreadsheets):

    • Call the Get Thread API method and locate the ID for each HTML element in the html response field. For example:
      • In this HTML data: <div id='temp:C:HcD011418d4e25fe057d98300b99'>, the section_id for the corresponding live app is temp:C:HcD011418d4e25fe057d98300b99.
      • In this HTML data: <span id='temp:C:HcDe1a29801dd43ce5b7d68c43f3'>, the section_id for the corresponding live app cell is temp:C:HcDe1a29801dd43ce5b7d68c43f3.
      • In this HTML data: <span id='temp:s:HcDABA078jM_temp:C:HcD5aa735cfd0dd58e3eee0e5ef0'>, the section_id for the corresponding spreadsheet row is temp:s:HcDABA078jM.
      • In this HTML data: <span id='temp:s:HcDABA078jM_temp:C:HcD5aa735cfd0dd58e3eee0e5ef0'>, the section_id for the corresponding spreadsheet cell is temp:s:HcDABA078jM_temp:C:HcD5aa735cfd0dd58e3eee0e5ef0.
document_range
string

The text of the heading of the document range you want to modify. The document range includes the heading and all subheadings below it up to the next heading of the same size or larger. Required if the location is AFTER_DOCUMENT_RANGE, BEFORE_DOCUMENT_RANGE, REPLACE_DOCUMENT_RANGE, or DELETE_DOCUMENT_RANGE. This parameter supports only documents and not spreadsheets. Provide either a section_id or a document_range. For example:

  • If you have content in this heading structure:
    • Topic 1
    • Topic 2
      • Subtopic 2.1
        • Subtopic 2.1.1
    • Topic 3
  • Then you delete document_range Topic 2:
    • All of the content from Topic 2 to Subtopic 2.1.1 and the text under those headings are deleted.
    • Only Topic 1 and Topic 3 are left in the document.
location
integer
Default: 0
Enum: 1 2 3 4 5 6 7 8 9

Where we should insert the new content.

  • 0: APPEND - Add to the end of the document. This isn't supported for a standalone spreadsheet. To add a row at the end of a standalone spreadsheet, pass in the section_id of the last row in the spreadsheet and use location 2.
  • 1: PREPEND - Add to the beginning of the document. This isn't supported for a standalone spreadsheet. To add a row at the beginning of a standalone spreadsheet, pass in the section_id of the first row in the spreadsheet and use location 3.
  • 2: AFTER_SECTION - Insert after the section specified by section_id.
  • 3: BEFORE_SECTION - Insert before the section specified by section_id.
  • 4: REPLACE_SECTION - Delete the section specified by section_id and insert the new content at that location. This isn't supported for live apps. You can delete a live app and add another one with your chosen content.
  • 5: DELETE_SECTION - Delete the section specified by section_id (no content required).
  • 6: AFTER_DOCUMENT_RANGE - Insert after the document range specified by document_range.
  • 7: BEFORE_DOCUMENT_RANGE - Insert before the document range specified by document_range.
  • 8: REPLACE_DOCUMENT_RANGE - Delete the document range specified by document_range and insert the new content at that location.
  • 9: DELETE_DOCUMENT_RANGE - Delete the document range specified by document_range (no content required).

Responses

Response samples

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

Edit Thread Share Link Settings

Changes share link settings on a thread.

At least one of the following must be included in the request:

  • allow_external_access
  • mode
  • enable_request_access
  • show_conversation
  • show_edit_history
  • allow_messages
  • allow_comments
Authorizations:
OAuth2 (ADMIN_MANAGE)
Request Body schema: application/x-www-form-urlencoded
thread_id
required
string

The ID or secret path of the thread whose share link settings you want to edit.

allow_external_access
boolean

Determines whether users outside your company can access the Quip thread. If true, users outside your company can access the Quip thread. If false, users outside your company can't access the Quip thread.

mode
string
Enum: "edit" "view" "none"

Indicates the access that users will have to the thread.

enable_request_access
boolean

Allow users to request access to the document. When a user tries to access a document that they don't have access to, they are presented with a dialog informing them they do not have access to this document. If enable_request_access is true, this dialog will contain a "Request Access" button.

show_conversation
boolean

Determines whether users can see the conversation pane in a Quip thread. If true, users can see the conversation pane. If false, users can't see the conversation pane.

show_edit_history
boolean

Determines whether users can see a Quip thread's edit history in the conversation pane. If true, users can see the edit history. If false, users can't see the edit history.

allow_messages
boolean

Determines whether users can add comments to an existing conversation in a Quip thread. If true, users can add comments to an existing conversation. If false, users can't add comments to an existing conversation.

allow_comments
boolean

Determines whether users can add new comments to a Quip thread. If true, users can add new comments. If false, users can't add new comments.

Responses

Response samples

Content type
application/json
{
  • "property1": "success",
  • "property2": "success"
}

Export Document to .docx

Exports your specified Quip document to a DOCX file.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
thread_id
required
string

The ID or secret path of the thread for the document you want to export.

query Parameters
company_id
required
string

The ID of the company to use.

Responses

Response samples

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

Export Slides to .pdf

Exports your specified Quip slide deck to PDF.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
thread_id
required
string

The ID or secret path of the thread for the document you want to export.

query Parameters
company_id
required
string

The ID of the company to use.

Responses

Response samples

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

Export Spreadsheet to .xlsx

Exports your specified Quip spreadsheet to an XLSX file.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
thread_id
required
string

The ID or secret path of the thread for the document you want to export.

query Parameters
company_id
string

The ID of the company to use.

Responses

Response samples

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

Get Externally Shared Threads

Retrieve details on a list of threads, as specified by external and link_shared parameters. One of those parameters must be true.

Authorizations:
OAuth2 (ADMIN_READ)
Request Body schema: application/x-www-form-urlencoded
company_id
required
string

The ID of the company to use.

external
boolean
Default: false

If true, returns company documents with external users.

link_shared
boolean
Default: false

If true, returns company documents with external link sharing enabled.

offset
integer >= 0
Default: 0

Number of threads to skip before returning results.

max_size
integer
Default: 1000

Maximum number of threads to return.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Thread V2

Returns basic information about a Quip thread (document, spreadsheet, or chat). This information includes things such as the ID, title, last time the thread was edited and the thread's link sharing settings.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
id
required
string

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

  • ID: You can find this in the "id" response field of this API method.

  • secret path: You can find this in the URL of a thread. For example, in this URL: "https://quip.com/3fs7B2leat8/TrackingDocument", the secret path is 3fs7B2leat8. You can also find this ID in the secret_path response field of this API method.

query Parameters
company_id
required
string
Example: company_id={{admin_company_id}}

ID of the company that owns the thread you want to get information about.

Responses

Response samples

Content type
application/json
{
  • "thread": {
    }
}

Get a Thread

Retrieve information about a specific thread.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
id
required
string

The ID or secret path of the thread to inspect.

query Parameters
company_id
required
string
Example: company_id={{admin_company_id}}

The ID of the company to use.

Responses

Response samples

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

List Threads

Returns a list of all threads in the company along with a timestamp when they were last modified. Results will be ordered by the last overall activity in the thread.

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

The ID of the company to use.

page
integer
Default: 0

Number used for pagination.

since_timestamp
integer <int64>

Minimum last modified timestamp (in seconds since UNIX epoch) for fetched threads.

until_timestamp
integer <int64>

Maximum last modified timestamp (in seconds since UNIX epoch) for fetched threads.

sorted_by
string
Default: "ASC"
Enum: "ASC" "DESC"

Results will be sorted in this direction.

include_deleted
boolean
Default: false

If true, includes deleted threads.

Responses

Response samples

Content type
application/json
{
  • "company_id": "string",
  • "last_timestamp": 0,
  • "thread_ids": [
    ],
  • "sorted_by": "ASC",
  • "next_page": 0
}

Retrieve Bulk Export PDF Response

Returns the statuses and PDF URLs after a request you made to export multiple Quip threads to PDF using the Create Bulk Export PDFs Request API method. You can export multiple Quip threads to PDF to fulfill eDiscovery and other regulatory requirements and archive threads in other systems. You can also use one of your other systems to search all PDF thread data, including comments, and export the matching results.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string
Example: company_id=IMbAcASGu56

Identifier of the company whose Quip threads you want to export to PDF. Threads include: documents and spreadsheets, chats (2-person and group), and Slack channel conversations linked to Quip (also called "channels").

request_id
required
string
Example: request_id=AMXAEA8lSEj:1644470492776

Identifier returned by the Create Export PDF Request API method.

Responses

Response samples

Content type
application/json
{}

Create Bulk Export PDFs Request

Submits a request to asynchronously export multiple Quip threads to PDF. This call returns a request_id. Pass that request_id into the Retrieve Bulk Export PDF Response call to get the PDF URL and request status for each PDF.

Sample use cases: You can export Quip threads to PDF to fulfill eDiscovery and other regulatory requirements and archive threads in other systems. You can also use one of your other systems to search all PDF thread data, including comments, and export the matching results.

Note:

  • The appearance of the PDFs created using this API method is typically the same as threads exported to PDF in the Quip application. Sometimes there are minor formatting variations when you export via API. Example: fonts sometimes look different in a PDF exported via API.
  • Charts in spreadsheets are excluded from the exported PDF.
Authorizations:
OAuth2 (ADMIN_READ)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

Identifier of the company whose Quip threads you want to export to PDF. Threads include: documents and spreadsheets, chats (2-person and group), and Slack channel conversations linked to Quip (also called "channels").

ids
required
Array of strings

A comma-separated list of identifiers (thread_ids) of the Quip threads to export to PDF. If you're exporting a Quip spreadsheet with multiple tabs, all tabs are exported into one PDF. Each chat or channel is exported as a separate PDF.

You can get the thread_ids by calling the List Threads Admin API method.

include_conversations
boolean

Determines whether to include the conversation history associated with each Quip document or spreadsheet that you want to export to PDF. The conversation history appears at the end of each PDF. Allowable values for this field:

  • true: Include the conversation history.
  • false: Don't include the conversation history.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "ids": [
    ],
  • "include_conversations": true
}

Response samples

Content type
application/json
{
  • "request_id": "AMXAEA8lSEj:1644470492776"
}

Get Threads V2

Bulk variant of the Get Thread endpoint.

Returns basic information about multiple Quip threads (documents, spreadsheets, or chats). This information for each thread includes things such as the ID, title, last time the thread was edited and the thread's link sharing settings.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
ids
required
string

The IDs or secret paths of the threads to get information about. You can pass in a maximum of 1000 of either of these identifiers:

  • ID: You can find this in the "id" response field of the Get Thread API method.

  • secret path: You can find this in the URL of a thread. For example, in this URL: "https://quip.com/3fs7B2leat8/TrackingDocument", the secret path is 3fs7B2leat8. You can also find this ID in the secret_path response field of this API method.

query Parameters
company_id
required
string
Example: company_id={{admin_company_id}}

ID of the company that owns the thread you want to get information about.

Responses

Response samples

Content type
application/json
{
  • "klUsAqWxr8Ne": {
    },
  • "abcAAA78901": {
    }
}

Get Threads by ID

Retrieve details on a list of threads

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string
Example: company_id=DYTAcAiIFUr

The ID of the company to use.

ids
required
string
Example: ids=UcZ9AAhvqrc,AVN9AAeqq5w

A comma separated list of thread IDs.

Responses

Response samples

Content type
application/json
{
  • "AVN9AAeqq5w": {
    },
  • "UcZ9AAhvqrc": {
    }
}

Create a Document, Spreadsheet or Slides

Creates a document, spreadsheet, or slides, returning the new thread in the same format as Get Thread.

Note that for slides threads, this endpoint currently only supports creating a bare-bones, one-slide deck with a given title. Copy a Document or Template provides fuller slides functionality, allowing automatic creation of a new slide deck adapted from an existing one.

Authorizations:
OAuth2 (ADMIN_WRITE)
Request Body schema: application/x-www-form-urlencoded
content
required
string

The HTML or Markdown content of the new document. The content length must not exceed 1MB.

NOTE: When creating a spreadsheet, the content must be surrounded by an HTML <table> tag.

NOTE: In the current implementation, the parser treats <th> tags as <td> tags. When more than one <tr> tag is supplied, then the first row is automatically interpreted as the column header. If you want to create a table with more than one row and have default headers, then provide the first row with empty <td> tags.

company_id
required
string

The ID of the company to use.

format
string
Default: "html"
Enum: "html" "markdown"

Format of the supplied document content.

title
string

The title of the new document. If not specified, we infer the title from the first content of the document, for example, the first heading. The title must not exceed 10 KB.

member_ids
string

A comma-separated list of folder IDs or user IDs. The document will be placed in the specified folders, and any individual users listed will be granted individual access to the document. If this argument is not given, the document is created in the authenticated user's Private folder.

type
string
Default: "document"
Enum: "document" "spreadsheet"

The type of document to create.

Responses

Response samples

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

Remove All External Users from a Thread

All external users will be removed from the thread.

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

The ID of the company to use.

thread_id
required
string

The ID of the thread from which you want to remove all external users from.

Responses

Response samples

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

Remove People from a Thread or Remove a Thread from Folders

The member_ids parameter must contain a list of folder IDs and user IDS. Specified users will be removed from the thread and the thread will be removed from specified folders.

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

The ID or secret path of the thread from which you want to remove folders and users.

member_ids
required
string

A comma-separated list of folder IDs and user IDs. We remove each user ID individually from the thread. We remove the thread from each of the specified folder IDs.

company_id
required
string

The ID of the company to use.

Responses

Response samples

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

Search for Threads V2

Returns all documents that contain words specified in the "query" parameter that belong to the company specified with company_id.

Additional rate limits, separate from overall Admin API Rate Limit, are imposed for paginating over admin search results.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string
Example: company_id=DYTAcAiIFUr

The unique ID of the company to use.

query
required
string
Example: query=report

A text string containing words delimited by spaces used to match thread content or titles.

cursor
string

A pointer to the next page of data to return. Use a cursor to incrementally get additional pages of data. When you call this API method for the first time, leave the cursor field blank. For all calls after that first one, pass in the next_cursor value returned by your previous call. Continue to call this API method with each new cursor value until the next_cursor field returns empty.

limit
number

The maximum number of items to return in the same call.

Responses

Response samples

Content type
application/json
{
  • "company_id": "string",
  • "thread_ids": [
    ]
}

Search for Threads

Returns all documents that contain words specified in the "query" parameter that belong to users in the company specified by company_id.

Additional rate limits, separate from overall Admin API Rate Limit, are imposed for paginating over admin search results.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string
Example: company_id=DYTAcAiIFUr

The unique ID of the company to use.

query
required
string
Example: query=report

A text string containing words delimited by spaces used to match thread content or titles.

page
integer
Default: 0

Number used for pagination.

Responses

Response samples

Content type
application/json
{
  • "company_id": "string",
  • "thread_ids": [
    ],
  • "more_to_read": true,
  • "next_page": 1
}

Messages

Delete a Message

Delete a single message.

Authorizations:
OAuth2 (ADMIN_WRITE)
query Parameters
company_id
required
string

The ID of the company to use.

message_id
required
string

The ID of the message to delete.

Responses

Response samples

Content type
application/json
{ }

Get a Message

Returns a message with the given message ID.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
message_id
required
string

The message ID to view the message for.

query Parameters
company_id
required
string

The ID of the company to use.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Messages for a Thread

Returns a list of the most recent messages for the given thread, ordered reverse-chronologically. Can also be used to get edit history for a document.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
thread_id
required
string

The thread ID to view messages for.

query Parameters
company_id
required
string

The ID of the company to use.

count
integer [ 1 .. 100 ]
Default: 25

Number of messages to return.

max_created_usec
integer <int64>

If given, we return messages updated before the given max_created_usec, which is a UNIX timestamp in microseconds. To use this argument for paging, you can use the created_usec field in the returned message objects.

sorted_by
string
Default: "DESC"
Enum: "ASC" "DESC"

ASC or DESC. Changes the order of the returned messages.

sort_by
string
Default: "DESC"
Enum: "ASC" "DESC"

Alias for sorted_by

message_type
string
Default: "message"
Enum: "message" "edit"

Determines what will be returned by this call.

  • message: text messages and document comments will be returned. * edit: Document edit records will be returned.
include_deleted
boolean
Default: false

If true, response includes deleted messages.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Users

Get Information about a User V2

Returns information about the specified user. You can use that information for eDiscovery and eArchiving purposes. For example, you can export the returned user data to your archiving system.

See also: Folders (Quip)

Sample Call

In this example, we're getting information about a user with ID ABCEAmpgev at a company with ID DEFCAcAV4DT7. We're also sorting the returned shared_folder_ids and group_folder_ids lists in ascending order by created_usec (timestamp for when the folder was created).

GET https://platform.quip.com/2/admin/users/ABCEAmpgev
Content-Type: application/json
Authorization: Bearer {{ABCSampleAccessToken}}

{
    "company_id": "DEFAcAV4DT7",
    "sort_by": "created_usec",
    "sort_order": "asc"
}
Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
id
required
string

ID of the user whose information you want to get.

query Parameters
company_id
required
string

ID of the company that the specified user works for. For your own company, you can find the company_id in the Quip Admin Console under Settings > Site Settings.

shared_thread_id
string

ID of a thread that's either shared with a user at another company or shared by a user at another company. Pass in the ID of that user as a path parameter in your API call. For an external user, this API method returns only the name, emails, id, and company_id fields in the response. You can pass in either of these thread identifiers:

sort_by
string
Enum: "title" "created_usec" "updated_usec"

Determines which field to sort the shared_folder_ids and group_folder_ids lists by, if they're included in the response.

sort_order
string
Default: "asc"
Enum: "asc" "desc"

Determines what order to sort the shared_folder_ids and group_folder_ids lists in, if they're included in the response. asc sorts the lists in ascending order. desc sorts the lists in descending order.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "UTUAEAiZl6B",
  • "name": "Jane Doe",
  • "company_id": "IMbAcASGu56",
  • "emails": [
    ],
  • "disabled": false,
  • "created_usec": 1632022665732239,
  • "is_robot": false,
  • "affinity": 0.43,
  • "chat_thread_id": "adHAAAKik9A",
  • "desktop_folder_id": "AGWAOAhT3qk",
  • "archive_folder_id": "BGWAOAhT3qk",
  • "starred_folder_id": "CGWAOAhT3qk",
  • "private_folder_id": "DGWAOAhT3qk",
  • "trash_folder_id": "EGWAOAhT3qk",
  • "shared_folder_ids": [
    ],
  • "group_folder_ids": [
    ]
}

Get User's Threads V2

Returns information about Quip threads owned by the specified user. Threads include: documents and spreadsheets, chats (2-person and group), Slack channel conversations linked to Quip (also called "channels"), and slides. You can use the returned information for eDiscovery and eArchiving purposes. For example, you can pass the returned thread IDs into another API call to export the threads to .docx or PDF files. Then you can save the exported files in your archiving system.

Sample Calls

In this first example, we're getting a list of the first 50 threads owned by a user with ID ABCEAmpgev at a company with ID DEFAcAV4DT7. Since the user owns more that 50 threads, we'll get a next_cursor value in the response and pass that value into the next call in step 2.

GET https://platform.quip.com/2/admin/users/ABCEAmpgev/threads?company_id=DEFAcAV4DT7&limit=50
Authorization: Bearer {{ABCSampleAccessToken}}

In this example, we're getting a list of the next 50 threads owned by a user with ID ABCEAmpgev at a company with ID DEFAcAV4DT7. We're passing in the next_cursor value returned by the previous call from step 1.

GET https://platform.quip.com/2/admin/users/ABCEAmpgev/threads?company_id=DEFAcAV4DT7&limit=50&cursor=bmV4dCBjdXJzb3I
Authorization: Bearer {{ABCSampleAccessToken}}
Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
id
required
string

ID of the user whose information you want to get.

query Parameters
company_id
required
string

ID of the company that the specified user works for. For your own company, you can find the company_id in the Quip Admin Console under Settings > Site Settings.

threads_meta
boolean
Default: false

Determines whether to include basic thread data in the response. Allowable values for this field are:

  • true: Return thread_id, updated_usec, link, and is_deleted on each thread.

  • false: Return thread_id on each thread.

include_deleted
boolean
Default: false

Determines whether to return threads that the specified user has been removed from. Allowable values for this field are:

  • true: Return threads that the user has been removed from.

  • false: Don't return threads that the user has been removed from.

thread_ids
string
Example: thread_ids=UcZ9AAhvqrc,AVN9AAeqq5w

Comma-separated list of thread IDs owned by the specified user. You can pass in either of these identifiers:

limit
integer

The maximum number of threads to return. You can pass in a maximum limit of 1,000. If you leave the limit field blank, this call returns a maximum of 1,000 threads.

cursor
string

A pointer to the next page of thread data to return. Use a cursor to incrementally get the next set of thread data. When you call this API method for the first time, leave the cursor field blank. For all calls after that first one, pass in the next_cursor value returned by your previous Get User's Threads call. Continue to call Get User's Threads with each new cursor value until the next_cursor field returns empty.

Note: Each next_cursor value returned by this API method expires 30 minutes after creation. After a cursor expires, you can call Get User's Threads again to get a new cursor.

Responses

Response samples

Content type
application/json
Example
{
  • "threads": {
    },
  • "response_metadata": {
    }
}

List Users at a Company

Returns a map from user IDs to user objects for users in the company. User objects contain the name, emails, and ID of each user.

Authorizations:
OAuth2 (ADMIN_READ)
Request Body schema: application/x-www-form-urlencoded
company_id
required
string

The ID of the company to use.

count
integer [ 1 .. 25000 ]
Default: 5000

Maximum number of users to return.

offset
integer
Default: 0

Number of users to skip before returning results. Used for pagination.

Responses

Response samples

Content type
application/json
{
  • "UTUAEAiZl6B": {
    },
  • "BTAAEAiGl7B": {
    }
}

Get Users Read Only

Gets the read-only status of users.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
user_ids
Array of strings [ 1 .. 1000 ] items
Example: user_ids=SSSAEAOPHIA,QUEAEAENBEY

A comma separated list of user IDs.

Responses

Response samples

Content type
application/json
{
  • "read_only": [
    ],
  • "non_read_only": [
    ],
  • "not_found": [
    ]
}

Mark Users Read Only

Marks users as read-only.

Authorizations:
OAuth2 (ADMIN_MANAGE)
Request Body schema: application/json
user_ids
required
Array of strings [ 1 .. 1000 ] items

A list of user IDs.

read_only
required
boolean

If true, all users in user_ids are read-only. If false, all users in user_ids are non-read-only.

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ],
  • "read_only": true
}

Response samples

Content type
application/json
[
  • {
    }
]

Folders

Get a Folder

Get information about any folder.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
id
required
string
Example: RKH9OAELPKV

The ID of the folder to get information for.

query Parameters
company_id
required
string
Example: company_id=LbdAcAwVVIA

The ID of the company to use.

include_chats
boolean

If true, the children list in the response will include chat and channel thread IDs.

Responses

Response samples

Content type
application/json
{
  • "folder": {
    },
  • "member_ids": [
    ],
  • "children": [
    ]
}

Get Folders

Bulk variant of the Get Folder endpoint. Returns an object mapping IDs to folder objects.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
ids
required
string
Example: ids=BULAOADdLWL,CULAOADdLWL

A comma-separated list of folder IDs.

company_id
required
string
Example: company_id=LbdAcAwVVIA

The ID of the company to use.

include_chats
boolean

If true, the children list in the response will include chat and channel thread IDs.

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Events

The Events API allows you to get information about your company’s Quip activity such as the creation or modification of content. This helps you to:

  • Monitor for malicious, unauthorized, or unusual activity. Use this information to create and enforce security policies.
  • Identify performance bottlenecks.
  • Get engagement data about Quip threads. You can then feed the data into your engagement monitoring systems.
  • Find out when activities happen so you can initiate workflows. For example, you can start an automated process when a document is created.
  • Access information that you can integrate with your data analysis or visualization systems.

These four API methods are available in the Events API and they’re described in detail in the reference documentation:

  • Get an Event Cursor (historical monitoring)
  • Get Next Batch of Events (historical monitoring)
  • Get a Cursor for Near Real-Time Events
  • Get Next Batch of Near Real-Time Events

Prerequisites

To use the Events API, you must:

  • Purchase it as an add-on product.
  • Set up access to the Admin API as described in the Admin API Requirements.

Best Practices

For best results when you use the Events API, we recommend that you:

  • Use either the historical or near real-time API methods and not both. That way, you can optimize performance and avoid processing the same event information multiple times. Choose the type of API method that works best based on your systems and business needs.
  • Use the Events API for historical or near real-time activity monitoring across your Quip site. This API doesn’t automatically generate notifications. If you want to subscribe to notifications about Quip activity, use the New Websocket API method within the Automation API instead.

Process Summary

To use the Events API, follow these steps:

Step Historical Events Near Real-time Events
1 Call the Get an Event Cursor API method. Call the Get a Cursor for Near Real-Time Events API method.
2 Call Get Next Batch of Events and pass in the next_cursor value returned in step 1. Call Get Next Batch of Near Real-Time Events and pass in the next_cursor value returned in step 1.
3 Call Get Next Batch of Events again and pass in the next_cursor value returned by step 2. Call Get Next Batch of Near Real-Time Events again and pass in the next_cursor value returned by step 2.
4 Repeat step 3 until the more_to_read field returns a value of false. Repeat step 3 until the more_to_read field returns a value of false.
5 Repeat the process from step 1 every two hours (or at your desired interval longer than two hours). After a short duration (more or less than one minute), repeat step 3 with the most recently retrieved cursor to get any new events.

Repeat in an ongoing loop to stay current with events being generated by your Quip site.

Event Types

Event Type Description
create-thread A thread was created. Additional data on the type of creation can be found in sub_action; the options are: create-new, create-import, create-copy
open-thread A thread was opened
delete-thread A thread was deleted
share-thread Additional members were added to a thread. Additional data on the type of sharing can be found in sub_action
unshare-thread Members of a thread were removed
move-thread A thread was moved from one folder into another folder, a thread is deleted and moved to trash, or a thread is restored from trash and moved back to a folder
rename-thread A thread was renamed
delete-message A message was deleted
edit-message A message was edited
create-message A message was created and sent. Additional data on the type of message can be found in sub_action. The options are: annotation, sending message in conversation pane, sending a direct message, and ending an edit session, which sends edits to the conversation pane
create-folder A folder was created
delete-folder A folder was deleted
open-folder A folder was opened
move-folder A folder was moved
copy-folder A folder was copied
share-folder A folder was shared
unshare-folder Members of a folder were removed
rename-folder A folder was renamed
login A site member logged in
print-document A thread was printed
export-thread A thread was exported
upload_blob-thread A file was uploaded to a thread
create-user A site member was created
disable-user A site member was disabled
admin_edit An admin took an action in the admin console
admin_api_call An admin API endpoint was accessed
create-admin_api_access A user was granted access to the Admin API
delete-admin_api_access A user had Admin API access revoked
restore-thread Thread removed from the trash by a user, restoring access
create-policy A data retention or data hold policy was created
retire-policy A data retention or data hold policy was retired
attach-policy A data retention or data hold policy was attached to a thread
execute-policy The policy action on a data hold or data retention was executed
create-link A shareable link for a thread or folder was created
edit-link A shareable link's access to a thread or folder was changed
delete-link A shareable link for a thread was or folder disabled
download_blob-thread A file attachment of a thread downloaded by user
search_threads A search query across multiple threads.
receive-invite A site member was added to a thread
receive_in_folder-thread A thread was added to a folder your company owns
receive-folder A site member was added to a folder
joined_by_link-thread A member joined a thread your company owns by link share
join-thread A site member joins a thread by link thread
create-link A link for a thread or folder your company was created
joined_by_link-folder A member joined a folder your company owns by link share
join-folder A site member joins a folder by link thread

Get an Event Cursor

Gets a starting cursor that you can use to search for historical events that happened between two hours and 30 days ago. The cursor is a pointer to a particular time interval. Pass the next_cursor value returned by this API method into a Get Next Batch of Events API call to obtain the historical events for your specified time interval.

For better performance, we recommend that you:

  • Filter your request by either user_id or event_types or both.
  • Use a short time interval between the since_timestamp and until_timestamp.
Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string
Example: company_id=IMbAcASGu56

The ID of the company associated with the events. You can find the company_id in the Admin Console under Settings > Site Settings.

since_timestamp
required
integer <int64>
Example: since_timestamp=1554241192914801

The Unix timestamp in microseconds for the start date and time of the interval in which to search for events. This timestamp must be earlier than two hours before the current time. You can use this epoch converter to change a human-readable date and time to a Unix timestamp. Add six zeros to the end of the Unix timestamp to convert the timestamp to microseconds. For example, if the Unix timestamp is 1636573582, that's 1636573582000000 in microseconds.

until_timestamp
required
integer <int64>
Example: until_timestamp=1554244792914801

The Unix timestamp in microseconds for the end date and time of the interval in which to search for events. This timestamp must be no more than 30 days before the current date. See the description of the since_timestamp field for the steps to change a human-readable date and time to a Unix timestamp.

user_id
string
Example: user_id=UTUAEAiZl6B

The ID of the user whose activities you want to retrieve. If you leave this field blank, then activities for all users are returned when you call the Get Next Batch of Events API method.

event_types
string
Example: event_types=create_thread,open-thread

A comma-separated list of event types to retrieve. Event types are defined in the Event Types table. If you leave this field blank, then all supported event types are returned when you call the Get Next Batch of Events API method.

count
integer
Default: 100

Maximum number of events to retrieve. You can request a maximum of 500 events.

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "eyJjdXJzb3JfdmVyc2lvbiI6MSwic..."
}

Get a Cursor for Near Real-Time Events

Gets a starting cursor that you can use to search for near real-time events that happened within the past two hours. The cursor is a pointer to a particular time interval. Pass the next_cursor value returned by this API method into a Get Next Batch of Near Real-Time Events API call to obtain the events that happened within the past two hours.

For better performance, we recommend that you filter your request by user_id, event_types, or both.

Note: The next_cursor values returned by these API methods expire 24 hours after creation:

  • Get a Cursor for Near Real-Time Events
  • Get Next Batch of Near Real-Time Events
Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string

The ID of the company to get events for. You can find the company_id in the Admin Console under Settings > Site Settings.

user_id
string

The ID of the user whose activities you want to search for. If you leave this field blank, then activities for all users are returned when you call the Get Next Batch of Near Real-Time Events API method.

event_types
string
Example: event_types=create_thread,open-thread

A comma-separated list of event types to search for. Event types are defined in the Event Types table. If you leave this field blank, then all supported event types are returned when you call the Get Next Batch of Near Real-Time Events API method.

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "eyJjdXJzb3JfdmVyc2lvbiI6MSwic..."
}

Get Next Batch of Events

Returns historical events based on the query parameters you passed in when you called the Get an Event Cursor API method.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string

The ID of the company associated with the events. You can find the company_id in the Admin Console under Settings > Site Settings.

cursor
required
string
Example: cursor=eyJjdXJzb3JfdmVyc2lvbiI6MSwic...

A cursor you can use to retrieve historical events. When you call this API method for the first time after calling Get an Event Cursor, pass in the next_cursor value returned by the Get an Event Cursor API method. For all calls after that first one, pass in the next_cursor value returned by your previous Get Next Batch of Events call.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "more_to_read": true,
  • "next_cursor": "fyJjdXJzb3JfdmVyc2lvbiI6MSwic..."
}

Get Next Batch of Near Real-Time Events

Returns near real-time events based on the query parameters you passed in when you called the Get a Cursor for Near Real-Time Events API method.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string

The ID of the company to get events for. You can find the company_id in the Admin Console under Settings > Site Settings.

cursor
required
string
Example: cursor=eyJjdXJzb3JfdmVyc2lvbiI6MSwic...

A cursor you can use to retrieve near real-time events that happened within the past two hours. When you call this API method for the first time after calling Get a Cursor for Near Real-Time Events, pass in the next_cursor value returned by the Get a Cursor for Near Real-Time Events API method. For all calls after that first one, pass in the next_cursor value returned by your previous Get Next Batch of Near Real-Time Events call.

Note: This next_cursor value expires 24 hours after creation.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "more_to_read": true,
  • "next_cursor": "fyJjdXJzb3JfdmVyc2lvbiI6MSwic..."
}

Quarantine

Add Quarantine

Quarantine a given object, either a message, document, or blob. Quarantining a document hides all document content behind a quarantine notice and blocks all edits. Quarantining a message hides all message content behind a quarantine notice. Quarantining a blob hides the blob from its thread.

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

The ID of the company to use.

object_id
required
string

The ID of the thread (for a document), message, or blob to quarantine.

blob_thread_id
string

If quarantining a blob, this is the ID of the thread the blob belongs to.

Responses

Response samples

Content type
application/json
{
  • "object_id": "AuINVs2WcPGAzNG04GDu8Q"
}

Remove Quarantine

Remove a document or message from quarantine. This will restore its content to its pre-quarantine state.

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
company_id
required
string
Example: company_id=IMbAcASGu56

The company to use

object_id
required
string
Example: object_id=AuINVs2WcPGAzNG04GDu8Q

The ID of the thread (for a document), message, or blob to remove from quarantine.

blob_thread_id
string
Example: blob_thread_id=LDOAAAHxvUo

If removing a blob from quarantine, this is the ID of the thread the blob belongs to.

Responses

Response samples

Content type
application/json
{
  • "object_id": "AuINVs2WcPGAzNG04GDu8Q"
}

Company

Get Collaborating Company

Returns information about a company you are collaborating with, including the threads you are collaborating on.

Authorizations:
OAuth2 (ADMIN_READ)
path Parameters
external_company_id
required
string

The ID company to get information for.

query Parameters
company_id
required
string

The ID of the company to use.

offset
integer
Default: 0

The number of shared threads to skip before returning results. Used for pagination.

count
integer
Default: 1000

The maximum amount of shared thread IDs to return.

Responses

Response samples

Content type
application/json
{
  • "company_name": "Salesforce",
  • "type": "External",
  • "shared_thread_count": 5,
  • "shared_thread_ids": [
    ],
  • "new_offset": 2
}

Get Collaborating Companies

Returns all companies you are collaborating with

Authorizations:
OAuth2 (ADMIN_READ)
Request Body schema: application/x-www-form-urlencoded
company_id
required
string

The company to use.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Managed Sites

Returns a list of all managed site IDs for the admin's company.

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
company_id
required
string

The ID of the company to use.

Responses

Response samples

Content type
application/json
[
  • "MMeAcAoWgkU",
  • "AMeAcAoWgkU"
]

Create Managed Sites

Creates a batch of new managed sites for the admin's company. The request body should consist of either one site object or a list of site objects in JSON format.

Authorizations:
OAuth2 (ADMIN_MANAGE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
Array
company_id
required
string

The ID of the parent company.

name
required
string

The name of the new managed site.

subdomain
required
string

The subdomain of the new managed site.

site_type
required
string
Enum: "partner" "testing"

Determines whether the new site will be for testing.

add_site_to_external_sharing_allowlist
boolean
Default: true

If true, restricts external sharing to only your managed site's parent company.

only_able_to_share_with_main_site
boolean
Default: true

If true, this site will be added to its parent company's external sharing allowlist.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "fYaAcA9bnZm": {
    },
  • "EUeAcABSe7a": {
    }
}

Delete Managed Sites

Disables a batch of managed sites.

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
managed_company_ids
required
string
Example: managed_company_ids=fYaAcA9bnZm,EUeAcABSe7a

A comma-separated list of managed companies to disable.

parent_company_id
required
string

The ID of the managed sites' parent company.

Responses

Response samples

Content type
application/json
{
  • "disabled_company_ids": [
    ]
}

Admin Roles

Get Admin Role for a User

Returns the admin role ID and admin role name for a user.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string

The ID of the company to use.

user_id
required
string

The ID of the user whose admin role to inspect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set Admin Role for a User

Updates a given user's admin role.

Authorizations:
OAuth2 (ADMIN_WRITE)
query Parameters
company_id
required
string

The ID of the company to use.

user_id
required
string

The ID of user whose admin role will be set.

admin_role_id
required
string

The ID of the admin role to set the user to. "1" is the ID for the Site Admin role and "2" is the ID for the Super Admin role. Any other ID will be considered a custom admin role.

Responses

Response samples

Content type
application/json
{ }

Delete Admin Role for a User

Removes a given user's admin role and removes them as an admin.

Authorizations:
OAuth2 (ADMIN_WRITE)
query Parameters
company_id
required
string

The ID of the company to use.

user_id
required
string

The ID of the user whose admin role will be removed.

Responses

Response samples

Content type
application/json
{ }

Get Admin Roles for a Company

Returns a list of all the admin role ids and admin role names.

Authorizations:
OAuth2 (ADMIN_READ)
query Parameters
company_id
required
string

The ID of the company to list admin roles for.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Governance (requires subscription)

Data hold policies prevent company content from being deleted on a per-user basis. Data holds apply to all threads accessed by the users specified in the policy during the policy's active period.

Data retention policies enable an admin to control how long data is retained within a Quip site. Using various settings, admins can either retain content for a set amount of time prior to enabling users to delete it, or they can use data retention rules to automatically remove stale content from their Quip site.

Get Data Hold

Returns the data hold policy.

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
company_id
required
string
Example: company_id=IMbAcASGu56

The ID of the company the data hold policy belongs to.

policy_id
required
string
Example: policy_id=2

The ID of the policy to get.

Responses

Response samples

Content type
application/json
{
  • "id": "1",
  • "name": "PLT3 Hold",
  • "start_date": "2021-09-23",
  • "end_date": "2021-10-23",
  • "apply_to": [
    ],
  • "state": "PENDING"
}

Create Data Hold

Creates a data hold policy.

Authorizations:
OAuth2 (ADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

The ID of the company to create the data hold policy for.

name
required
string

The name of the data hold policy.

start_date
required
string

The start date of the data hold in YYYY-MM-DD format.

end_date
required
string

The end date of the data hold in YYYY-MM-DD format.

member_emails
required
Array of strings

A list of the emails of the users the data hold will apply to.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "name": "PLT3 Hold",
  • "start_date": "2021-09-23",
  • "end_date": "2021-10-23",
  • "member_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "1",
  • "name": "PLT3 Hold",
  • "start_date": "2021-09-23",
  • "end_date": "2021-10-23",
  • "apply_to": [
    ],
  • "state": "PENDING"
}

Retire Data Hold

Retires a data hold policy.

Authorizations:
OAuth2 (ADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

The ID of the company to the data hold policy belongs to.

policy_id
required
string

The ID of the data hold policy to retire.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "policy_id": "2"
}

Response samples

Content type
application/json
{
  • "id": "1",
  • "name": "PLT3 Hold",
  • "start_date": "2021-09-23",
  • "end_date": "2021-10-23",
  • "apply_to": [
    ],
  • "state": "PENDING"
}

Add Users to Data Hold

Adds users to a data hold policy.

Authorizations:
OAuth2 (ADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

The ID of the company the data hold policy belongs to.

policy_id
required
string

The ID of the data hold policy the users will be added to.

member_emails
required
Array of strings

A list of emails of the users that will be added to the data hold policy.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "policy_id": "string",
  • "member_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "member_emails": [
    ]
}

Remove Users from Data Hold

Removes users from a data hold policy.

Authorizations:
OAuth2 (ADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

The ID of the company the data hold policy belongs to.

policy_id
required
string

The ID of the data hold policy the users will be removed from.

member_emails
required
Array of strings

A list of emails of the users that will be removed from the data hold policy.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "policy_id": "string",
  • "member_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "member_emails": [
    ]
}

Get Data Retention

Returns the data retention policy.

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
company_id
required
string
Example: company_id=IMbAcASGu56

The ID of the company the data retention policy belongs to.

policy_id
required
string
Example: policy_id=1

The ID of the policy to get.

Responses

Response samples

Content type
application/json
{
  • "id": "1",
  • "name": "PLT3 Retention",
  • "retention_period": 30,
  • "action": "Delete immediately",
  • "retired": false,
  • "apply_to_threads_created_after_usec": 1630454400000000,
  • "modification_updates_expiry": false,
  • "retain_until_expiration": true,
  • "apply_to_thread_ids": [
    ]
}

Add a Thread to Data Retention

Adds a thread to a data retention policy.

Authorizations:
OAuth2 (ADMIN_WRITE)
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
company_id
required
string

The ID of the company the data retention policy belongs to.

policy_id
required
string

The ID of the data retention policy the thread will be added to.

thread_id
required
string

The ID of the thread that will be added to the data retention policy.

Responses

Request samples

Content type
application/json
{
  • "company_id": "IMbAcASGu56",
  • "policy_id": "2",
  • "thread_id": "TVdAAASxBZz"
}

Response samples

Content type
application/json
{
  • "thread_id": "TVdAAASxBZz"
}

API Key

Get API Keys

Looks up the specified API keys. See also: Authentication

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
filter
Array of strings
Example: filter=client_id_1,client_id_2

A comma-separated list of client IDs of the corresponding API keys. If this parameter is left blank, all API keys are returned.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add API Key

Adds an API key that you can use to generate an OAuth token. Use the token in your integrations or applications that call Quip’s API endpoints. To get an OAuth token, use the returned client_id and client_secret. You can create a maximum of 100 API keys for your company.

Authorizations:
OAuth2 (ADMIN_MANAGE)
Request Body schema: application/json
app_name
required
string

Name of your application that integrates with Quip.

api_scopes
required
Array of strings
Items Enum: "USER_READ" "USER_WRITE" "USER_MANAGE" "ADMIN_READ" "ADMIN_WRITE" "ADMIN_MANAGE"

A list of API scopes that you need for the features in your application. Limit the scopes in your API key to the ones needed for the features in your application.

allowed_redirect_uris
Array of strings

A list of redirect URIs allowed for OAuth authentication. Quip doesn't validate redirect_uri if this is not set.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "app_name": "string",
  • "client_id": "string",
  • "client_secret": "string"
}

Revoke API Key

Revokes an API key corresponding to a specified client_id. It’s recommended that you revoke tokens for integrations that you’re no longer using. See also: Authentication

Authorizations:
OAuth2 (ADMIN_MANAGE)
query Parameters
client_id
required
string

The client_id that corresponds to the API key that you want to revoke.

Responses

Response samples

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