Overview

Summary

The Quip Automation API provides read/write access to Quip, enabling you to automate processes and integrate Quip with other products you or your company uses.

The Automation API is REST-based. Responses are JSON, and errors are reported via standard HTTP codes in addition to JSON-formatted error information in the HTTP response bodies of relevant requests. We use OAuth 2 for authentication and authorization.

Core Concepts

Quip integrates documents and messages into a single unit that we call a thread. Most of the operations in the Quip Automation API operate on threads. Threads can simply be a list of messages, i.e., a chat thread, or they may have a document in addition to a list of messages. Each thread has a permanent 11 character id and a similar 12 character URL suffix that can be expired by the user. Apps receiving URLs should convert them to permanent ids using Get Thread before being used.

Quip documents are broken down into smaller units we call sections. Every paragraph in a document is a separate section, as is every item in a list or cell in a table. The Quip Automation API outputs documents as HTML for convenience, and the elements in the HTML have id attributes specifying their internal section ID. When you want to perform advanced transforms on a document, like modifying a checklist, you will need to use the section IDs. The official Python library contains a number of examples of parsing the HTML to get section IDs and using that data for edit operations.

Quip folders are not traditional file system folders. Quip folders are more like tags, i.e., a thread can be in multiple folders. When a thread is in a folder, it inherits the permissions of the folder, e.g., if you add a thread to a folder shared with three people, those three people will have access to the thread. Each user has special desktop and archive folders that cannot be deleted, shared, or renamed.

A Quip thread can be shared with a list of folders and individual users. A user can access the thread if they have access to any of the folders or if they are individually added to the thread.

We refer to the people in threads and folders as members throughout the API.

Setup

GET https://platform.quip.com/1/users/current

Description

Start here:

  • make sure you have imported the Quip environment provided with this collection

  • visit admin.quip.com and add a new integration (under "Settings" on the left)

  • copy the client_id and client_secret to the respective fields in your environment

  • open the Authorization tab of this endpoint click "Get New Access Token"

  • Fill in with the following values:

    | Fields          | Value                                          |
    | --------------- |------------------------------------------------|
    | Token Name      | Quip API Token (or some other name)            |
    | Grant Type      | Authorization Code                             |
    | Callback URL    | {{callback_url}}                               |
    | Auth URL        | {{auth_url}}                                  |
    | Access Token URL| {{access_token_url}}                           |
    | Client ID       | {{client_id}}                                  |
    | Client Secret   | {{client_secret}}                              |
    | Scope           | <leave blank>                                  |
    | State           | 1234 (or any random value)                     |
    | Client Auth...  | Send client credentials in body                |
    
  • click "Request Token"

  • log in to Quip, which should show you a dialog.

  • click "Use Token" to close the dialog

  • hit "Send" on this endpoint

  • the rest of the endpoints in this collection will now be authorized

Source Code

Python Client Library

node.js Client Library

Sample Code

API Endpoint

https://platform.quip.com/1


Authentication

Personal Authentication

You can generate an access token that provides API access to your own, personal Quip account. This is useful for testing the API, automating tasks, or integrating with other services you use individually.

To generate a personal access token, visit this page:

https://quip.com/dev/token

Whenever you generate a new token, all previous tokens are automatically invalidated.

Once you have a token, the easiest way to use it is via the Python Client Library, which makes most tasks a single line of code. All of the documentation below contains copy-and-paste Python code snippets to make it easier to get started.

Domain Authentication

Domain authentication is only available for Quip Enterprise administrators. To enable this for your company, contact us.

Domain authentication enables seamless integration for internal or pre-approved services at your company. Domain authentication is simply OAuth 2.0, but instead of end users individually approving access to each application, domain administrators pre-approve applications, and end users do not see additional authorization prompts during the OAuth authorization process.

To enable domain authentication for a third-party application:

  1. Create an OAuth 2.0 token for the application you want to integrate. You will typically create a separate token for each app you want to integrate and name it after the app, which enables easy revokation when your company is no longer using the service.
  2. Configure the application with the OAuth 2.0 authorization endpoint https://platform.quip.com/1/oauth/login and the OAuth 2.0 token endpoint https://platform.quip.com/1/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.

Authorization Endpoint

GET https://platform.quip.com/1/oauth/login

Query Params

client_id

The client ID you created for your application.

client_secret

The client secret you created for your application.

redirect_uri

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

state Optional

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

Description

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

OAuth 2.0 Authorization Endpoint

https://platform.quip.com/1/oauth/login

OAuth 2.0 Token Endpoint

https://platform.quip.com/1/oauth/access_token

Example Response

{
    "access_token": "...",
    "refresh_token": "...",
    "expires_in": 2592000,
    "token_type": "Bearer"
}

Token Endpoint

POST https://platform.quip.com/1/oauth/access_token

Query Params

grant_type Optional

Either refresh_token or authorization_code

client_id

The client ID you created for your application.

client_secret

The client secret you created for your application.

refresh_token Optional

Required if grant_type is refresh_token

code Optional

Required if grant_type is authorization_code

Description

After you have obtained a verification code or refresh token, you can exchange it for an access token via a POST request to this endpoint.

Revoke a Token

POST https://platform.quip.com/1/oauth/revoke

Query Params

client_id

The client ID you created for your application.

client_secret

The client secret you created for your application.

token

The token to revoke

Description

Revoke an access_token or a refresh_token.

Verify Token

GET https://platform.quip.com/1/oauth/verify_token

Required Scopes

ANY

Headers

Authorization:Bearer {{access_token}}

Description

Verifies the validity of access_token

Response Headers

200 - Token is valid

401 - Token is invalid.

Example Response

{
}

Threads

Get Thread

GET https://platform.quip.com/1/threads/:id

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

id

A thread ID to get requests for

Description

Get information about a thread. You may also pass in a 12 character URL suffix to get the permanent thread ID.

Response Fields

thread

A dictionary with the thread metadata:

  • id - The thread ID
  • link - The public URL of the thread
  • title - The title of the thread
  • created_usec - The UNIX epoch in microseconds when the thread was created
  • updated_usec - The UNIX epoch in microseconds when the thread last changed
  • author_id - The ID of the thread's author
  • sharing - Information about public sharing of the thread.
  • type - document spreadsheet slides or channel, depending on the type of the thread.

shared_folder_ids

The IDs of the shared folders that contain this thread.

user_ids

The IDs of the users with whom this thread is shared individually.

expanded_user_ids

The IDs of every user who has access to this thread. This is the expansion of all user_ids and the members of all shared folders.

html

If the thread has a document, this field will be a string with the HTML representation of the document.

Example Response

{
    "expanded_user_ids": ["KaDAEAinU0V", "UObAEAaHude"],
    "user_ids": ["KaDAEAinU0V"],
    "shared_folder_ids": ["LEMAOAQNQwb"],
    "html": "...",
    "thread": {
        "created_usec": 1392021829698995,
        "updated_usec": 1394315318673846,
        "id": "LeSAAAqaCfc",
        "title": "Expense Reports",
        "link": "https://quip.com/e4V7AeaKCVmq"
    }
}

Get Threads

GET https://platform.quip.com/1/threads/

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Query Params

ids

A list of thread IDs

Description

Bulk variant of the Get Thread endpoint.

Returns an object mapping IDs to thread responses.

Example Response

{
	"LeSAAAqaCfc": {
	    "expanded_user_ids": ["KaDAEAinU0V", "UObAEAaHude"],
	    "user_ids": ["KaDAEAinU0V"],
	    "shared_folder_ids": ["LEMAOAQNQwb"],
	    "html": "...",
	    "thread": {
	        "created_usec": 1392021829698995,
	        "updated_usec": 1394315318673846,
	        "id": "LeSAAAqaCfc",
	        "title": "Expense Reports",
	        "link": "https://quip.com/e4V7AeaKCVmq"
	    }
	},
	...
}

Get Recent Threads

GET https://platform.quip.com/1/threads/recent

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Description

Returns the most recent threads to have received messages, similar to the updates view in the Quip app. Results are returned in the same format as Get Thread.

Search for Threads

GET https://platform.quip.com/1/threads/search

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Query Params

query

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

count Optional

The maximum number of results to return. Defaults to 10, with a maximum of 50.

only_match_titles Optional

If set to true, the search will match words in document titles rather than content. Typically much faster if you only want to get documents with a certain title.

Description

Returns threads whose content matches words in the given query.

Response Fields

Returns an array of dictionaries in order from most to least relevant. Each entry in the array is a dictionary that contains a "thread" key whose value is the same as a Get Thread response.

Example Response

[
    {
        "thread": {
            "updated_usec": 1497546190102488,
            "author_id": "QGPAEAHhrEM",
            "created_usec": 1497545872752906,
            "id": "NCSAAAVEZZE",
            "link": "https://quip.com/Tr4lAymRMVeX",
            "thread_class": "document",
            "type": "document",
            "title": "Expense Report Q2 FY18"
        }
    },
    {
        "thread": {
            "updated_usec": 1498163965704797,
            "author_id": "QGPAEAHhrEM",
            "created_usec": 1497545838650473,
            "id": "cRLAAA665U4",
            "link": "https://quip.com/BDZdAyQlcDnb",
            "thread_class": "document",
            "type": "document",
            "title": "Dreamforce expense report"
        }
    },
    {
        "thread": {
            "updated_usec": 1498507612435964,
            "author_id": "QGPAEAHhrEM",
            "created_usec": 1497545924280456,
            "sharing": {
                "company_mode": "VIEW",
                "company_id": "LbdAcAwVVIA"
            },
            "id": "LFUAAAJTGNZ",
            "link": "https://quip.com/3J84AoiBA7gY",
            "thread_class": "document",
            "type": "document",
            "title": "Expense reports for 2018 off-sites"
        }
    }
]

Create a Document, Spreadsheet or Slides

POST https://platform.quip.com/1/threads/new-document

Required Scopes

USER_WRITE

Headers

Content-Type:application/x-www-form-urlencoded
Authorization:Bearer {{access_token}}

Request Body

format Optional

Either html or markdown. Defaults to html.

content

The html or markdown content of the new document.

title Optional

The title of the new document. If not specified, we infer the title from the first content of the document, e.g., the first heading.

member_ids Optional

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 Optional

Either document, spreadsheet or slides. Defaults to document.

Description

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.

Create a Chat Room

POST https://platform.quip.com/1/threads/new-chat

Required Scopes

USER_WRITE

Headers

Authorization:Bearer {{access_token}}
Content-Type:application/x-www-form-urlencoded

Request Body

message Optional

Plain text content of the new message that is posted by the author of the chat room.

title

The title of the new chat room.

member_ids Optional

A comma-separated list of user IDs.

Description

Creates a chat room, returning the new thread in the same format as Get Thread.

Edit a Document

POST https://platform.quip.com/1/threads/edit-document

Required Scopes

USER_READ , USER_WRITE

Headers

Content-Type:application/x-www-form-urlencoded
Authorization:Bearer {{access_token}}

Request Body

thread_id

The thread whose document you want to modify

format Optional

Either html or markdown. Defaults to html.

content

The html or markdown content of the new document.

section_id Optional

The id for the section you want to modify. Required for some location values.

location Optional

Where we should insert the new content. Defaults to 0: APPEND.

  • 0: APPEND - Append to the end of the document.
  • 1: PREPEND - Prepend to the beginning of the document.
  • 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.
  • 5: DELETE_SECTION - Delete the section specified by section_id (no content required).

Description

Incrementally modifies the content of a document.

We determine where to insert the new content based on the location argument. Some location values are relative to another section, which is specified by section_id, enabling fine-grained editing. For example, to add an item to the end of a checklist, you would send the ID of the last list item in the list as the section_id and send 2: AFTER_SECTION as the location.

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

content is required for all calls unless the location is 5: DELETE_SECTION, which indicates we should simply delete the specified section_id. Any images referenced must have been previously uploaded separately.

We return the updated thread in the format specified in Get Thread

Copy a Document or Template

POST https://platform.quip.com/1/threads/copy-document

Required Scopes

USER_READ , USER_WRITE

Headers

Content-Type:application/x-www-form-urlencoded

Request Body

thread_id

The id or secret of the document to be copied

values Optional

A string or file containing a valid JSON dictionary whose keys are strings and whose values are either strings or dictionaries. Keys can only contain the characters A-Z, a-z, 0-9, .(dot) and _(underscore). If not supplied, the source document will not be treated as a template. Any valid JSON dictionary is acceptable. It can contain arrays but the key syntax does not provide any way to navigate through them or print them.

member_ids Optional

List of member ids that will be added to the new document

folder_ids Optional

A list of folder ids the new document will be added to

title Optional

A string value to be the title of the new document. If this isn't the same string as the first section in the doc, it will get overwritten with the first section when the document is saved.

Description

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.

Response Fields

thread

A dictionary that contains an id field with the thread_id of the new document

Example Response

{
    "thread": {
        "id": "AbFAAALoIx9"
    }
}

Delete a Thread

POST https://platform.quip.com/1/threads/delete

Required Scopes

USER_WRITE

Headers

Authorization:Bearer {{access_token}}

Request Body

thread_id

The id or secret of the thread to delete.

Description

Deletes the thread with the specified id or secret.

Response Fields

No JSON is returned by this endpoint when successful. On an error, there are three fields returned:

error

The type of error

error_code

The status code of the http request

error_description

A short description of why the request failed

Add People to a Thread or Add a Thread to Folders

POST https://platform.quip.com/1/threads/add-members

Required Scopes

USER_MANAGE

Headers

Content-Type:application/x-www-form-urlencoded
Authorization:Bearer {{access_token}}

Request Body

thread_id

The thread to which you want to add folders and users.

member_ids Optional

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

Description

Shares the given thread with the given user IDs and/or adds the given thread to the given folder IDs. We return the updated thread in same format as Get Thread.

POST https://platform.quip.com/1/threads/edit-share-link-settings

Headers

Authorization:Bearer {{access_token}}

Request Body

allow_external_access Optional

show_conversation Optional

show_edit_history Optional

allow_messages Optional

allow_comments Optional

enable_request_access Optional

mode Optional

Description

Changes share link settings on a thread.

Remove People from a Thread or Remove a Thread from Folders

POST https://platform.quip.com/1/threads/remove-members

Required Scopes

USER_MANAGE

Headers

Content-Type:application/x-www-form-urlencoded
Authorization:Bearer {{access_token}}

Request Body

thread_id

The thread from which you want to remove folders and users.

member_ids Optional

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.

Description

Removes the given individuals from the given thread and/or removes the thread from the given folders. We return the updated thread in same format as Get Thread.

Get a Blob from a Thread

GET https://platform.quip.com/1/blob/:thread_id/:blob_id

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

thread_id

blob_id

Description

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.

Response

In the case of success, the response is raw binary, so this endpoint can be used to display images.

In the case of failure, the response will return an object with an error field.

Add a Blob to a Thread

POST https://platform.quip.com/1/blob/:thread_id

Required Scopes

USER_WRITE

Headers

Authorization:Bearer {{access_token}}

Path Variables

thread_id

Request Body

blob

The image or blob binary

Description

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.

Response Fields

id

The new blob ID.

url

The relative URL to reference the blob in document edits.

Example Response

{
    "id": "DiPp1ZQyC8QUtvBT4vojzM",
    "url": "/blob/LeSAAAqaCfc/DiPp1ZQyC8QUtvBT4vojzM"
}

Export Document to .docx

GET https://platform.quip.com/1/threads/:thread_id/export/docx

Path Variables

thread_id

Export Spreadsheet to .xlsx

GET https://platform.quip.com/1/threads/:thread_id/export/xlsx

Path Variables

thread_id

Export Slides to .pdf

GET https://platform.quip.com/1/threads/:thread_id/export/pdf

Path Variables

thread_id


Messages

Get Recent Messages

GET https://platform.quip.com/1/messages/:thread_id

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

thread_id

The thread ID to return recent messages in.

Query Params

count Optional

The number of messages to return.

max_created_usec Optional

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.

Description

Returns a list of the most recent messages for the given thread, ordered reverse-chronologically.

Response Fields

id

The message ID.

author_id

The user ID of the message author.

created_usec

The time in microseconds since the Unix epoch when the message was sent. You can use this for paging with the maxcreatedusec argument

text

The text of the message

parts

If the message was created through the platform with the parts argument, this contains the original rich HTML representation.

annotation

If the message is attached to a document section, a dictionary of annotation metadata:

  • id - The annotation ID, referenced by a control tag in the document if not section-level
  • highlight_section_ids (optional) - A list of attached section IDs, only present if section-level

Example Response

[
    {
        "author_id": "HFCAEA8XZiw",
        "created_usec": 1394315318489097,
        "id": "LeSADAx0AI5",
        "text": "Do you mind uploading your receipt?"
    },
    {
        "author_id": "ASTAEAVennq",
        "created_usec": 1421282559582972,
        "id": "ABeADAavbzR",
        "text": "Not again, CNN",
        "parts": [[
            "monospace",
            "Not <b>again</b>, <a href=\"https://cnn.com\">CNN</a>"
        ]]
    },
    ...
]

Add a Message

POST https://platform.quip.com/1/messages/new

Required Scopes

USER_WRITE

Headers

Content-Type:application/x-www-form-urlencoded

Request Body

thread_id

The thread to which you want to add a message

frame Optional

One of bubble, card, or line - adjusts the display of the message

content Optional

Plain text content of the new message (ignored if parts is supplied)

silent Optional

If set to True, we do not send any push notifications or emails for the message. If set to False or not provided, we use the default notifications for users on the thread.

parts Optional

Rich content of the new message as a JSON-encoded array of [[style1, HTML1], [style2, HTML2], ...] where style can be system, body, monospace, or status.

attachments Optional

A comma-separated list of blob IDs previously uploaded to this thread with Add a Blob.

annotation_id Optional

Adds this message to the given document comment.

section_id Optional

Adds this message as a comment on the given document section.

Description

Adds a chat message to the given thread, posted as the authenticated user. Returns the new message in the message format described in Get Recent Messages.

Example Response

{
    "author_id": "HFCAEA8XZiw",
    "created_usec": 1394315318489097,
    "id": "LeSADAx0AI5",
    "text": "Hello world"
}

Folders

Get Folder

GET https://platform.quip.com/1/folders/:id

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

id

Description

Returns the given folder.

To find your desktop or archive folder ID, see Get Authenticated User.

Response Fields

folderA dictionary with the folder metadata:

  • id - The folder ID
  • title - The title of the folder
  • created_usec - The UNIX epoch in microseconds when the folder was created
  • updated_usec - The UNIX epoch in microseconds when the folder last changed
  • creator_id - The ID of the folder's creator
  • color - The color of the folder
  • manila
  • red
  • orange
  • green
  • blue
  • purple
  • yellow
  • light_red
  • light_orange
  • light_green
  • light_blue
  • light_purple
  • parent_id - The ID of this folders parent, from which it inherits permissions, if any.

member_ids

A list of the user IDs that have access to the folder. If the folder has a parent_id, then the members of that folder can also access this folder, and they will not necessarily be listed individually here. You need to walk up the folder hierarchy to get the full list of users who have access.

children

A list of all of the threads and sub-folders inside of this folder. Threads are a dictionary with a single thread_id field. Folders are a dictionary with a single folder_id field.

Example Response

{
    "folder": {
        "color": "manila",
        "created_usec": 1395815761359098,
        "updated_usec": 1395818386228824,
        "id": "FFJAOAcKhkX",
        "title": "sasada"
    },
    "member_ids": [
        "KaDAEAinU0V",
        "HFCAEA8XZiw"
    ],
    "children": [
        {
            "thread_id": "ULJAAAkvOHx"
        },
        {
            "folder_id": "LEMAOAQNQwb"
        }
    ]
}

Get Folders

GET https://platform.quip.com/1/folders/

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Query Params

ids Optional

Description

Bulk variant of the Get Folder endpoint.

Returns an object mapping IDs to folder responses.

Example Response

{
	"FFJAOAcKhkX": {
	    "folder": {
	        "color": "manila",
	        "created_usec": 1395815761359098,
	        "updated_usec": 1395818386228824,
	        "id": "FFJAOAcKhkX",
	        "title": "sasada"
	    },
	    "member_ids": [
	        "KaDAEAinU0V",
	        "HFCAEA8XZiw"
	    ],
	    "children": [
	        {
	            "thread_id": "ULJAAAkvOHx"
	        },
	        {
	            "folder_id": "LEMAOAQNQwb"
	        }
	    ]
	}
	...
}

Create a Folder

POST https://platform.quip.com/1/folders/new

Required Scopes

USER_MANAGE

Headers

Authorization:Bearer {{access_token}}

Request Body

title Optional

The name of the folder

color Optional

One of the color constants above. Defaults to manila.

member_ids Optional

A comma-separated list of user_ids to add as members of this folder

parent_id Optional

If given, we make the folder a child of the given folder. If not given, we create the folder on the authenticated user's Private folder.

Description

Creates a folder, returning the new folder in the format described in Get Folder.

Update a Folder

POST https://platform.quip.com/1/folders/update

Required Scopes

USER_MANAGE

Headers

Authorization:Bearer {{access_token}}

Query Params

folder_id

The folder to alter

title Optional

If given, update the name of the folder

color Optional

If given, update the color of the folder to one of the color constants described in Get Folder

Scopes: USER_MANAGE

Description

Updates a folder, returning the updated folder in the format described in Get Folder

Add People to a Folder

POST https://platform.quip.com/1/folders/add-members

Required Scopes

USER_MANAGE

Headers

Authorization:Bearer {{access_token}}
Content-Type:application/x-www-form-urlencoded

Request Body

folder_id

The folder to update.

member_ids

A comma-separated list of user IDs.

Description

Shares the given folder with the given user IDs.

We return the updated folder in the format described in Get Folder

Remove People from a Folder

POST https://platform.quip.com/1/folders/remove-members

Required Scopes

USER_MANAGE

Headers

Authorization:Bearer {{access_token}}

Request Body

folder_id

The folder to modify.

member_ids

A comma-separated list of User or Folder IDs.

Description

Removes the given User IDs from the given folder.

We return the updated folder in the format described in Get Folder


Users

Get User

GET https://platform.quip.com/1/users/:id

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

id

Description

Returns the user with the specified ID.

Response Fields

id

The user ID.

name

The user's full name.

affinity

A floating point number between 0 and 1 indicating the authenticated user's affinity to this user. Quip generally presents contacts in affinity order throughout the app.

profile_picture_url

A URL for the user's profile picture, if any.

chat_thread_id

The ID of the chat thread between the authenticated user and this user, if any.

desktop_folder_id

Only for the authenticated user. The ID of the user's desktop folder.

archive_folder_id

Only for the authenticated user. The ID of the user's archive folder.

starred_folder_id

Only for the authenticated user. The ID of the user's starred folder.

private_folder_id

Only for the authenticated user. The ID of the user's private folder.

group_folder_ids

Only for the authenticated user. The IDs of the user's group folders.

shared_folder_ids

Only for the authenticated user. The IDs of the user's shared folders.

disabled

Only for the authenticated admin. Whether the user is disabled.

created_usec

Only for the authenticated admin. The creation timestamp of the user.

emails

Only for the authenticated admin. A list of emails associated with the user.

error

Indicates an email address is not found.

Example Response

{
    "affinity": 0,
    "id": "KaDAEAinU0V",
    "name": "Bret Taylor"
}

Get User by Email

GET https://platform.quip.com/1/users/:email

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Path Variables

email

An email address

Description

Returns information about a user with the specified email.

If the user exists, it will be returned in the same format as Get User

If the user is not found, returns an error key with a description.

Get Users

GET https://platform.quip.com/1/users/

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Query Params

ids

A comma-separated list of either emails or user IDs.

Description

Bulk variant of the Get User endpoint.

You can provide either email addresses or user IDs in the "ids" field; if you provide multiple email addresses for the same user we return multiple dictionary entries with the same user information for each.

If an email address is not found then the email address will be added to the dictionary along with a bad entry indictor.

Example Response

{
	"KaDAEAinU0V": {
	    "affinity": 0,
	    "id": "KaDAEAinU0V",
	    "name": "Bret Taylor"
	},
	...
}

Get Current User

GET https://platform.quip.com/1/users/current

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Description

Returns information about the user who created the OAuth token used in this call, in the format described in Get User.

The response always returns the user's starred_folder_id and private_folder_id.

Example Response

{
    "starred_folder_id": "fffAOAhkwR5",
    "affinity": 0,
    "id": "bdOAEAJ6VBT",
    "name": "Bret Taylor",
    "private_folder_id": "TDHAOAJimIg"
}

Get Contacts

GET https://platform.quip.com/1/users/contacts

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Description

Returns a list of the contacts for the authenticated user in the format described in Get User.

Example Response

[
    {
        "affinity": 0.0,
        "name": "Samantha Stevens",
        "id": "bdOAEAJ6VBT"
    }, {
        "affinity": 0.0,
        "name": "Matthew Cahill",
        "id": "CLXAEAbFxMb"
    },
    ...
]

Update User

POST https://platform.quip.com/1/users/update

Required Scopes

USER_MANAGE

Headers

Content-Type:application/x-www-form-urlencoded
Authorization:Bearer {{access_token}}

Request Body

user_id Optional

picture Optional

picture_url Optional

Description

Updates the currently logged in user. Only supports updating the users' profile picture.

Returns the updated user in the format described by Get User.

Example Response

{
    "name": "Friggle Fragate",
    "id": "VFDAEAVaNMD",
    "is_robot": false,
    "affinity": 0,
    "desktop_folder_id": "OWZAOAiK3Nn",
    "archive_folder_id": "OWZAOAjRZ9S",
    "starred_folder_id": "OWZAOAMU4ss",
    "private_folder_id": "OWZAOAZZOi9",
    "shared_folder_ids": [
        "NJbAOAZEyLA",
        "OUEAOAoiVSJ",
        "OVRAOAtrL5s",
        "eNEAOANDXtV"
    ],
    "group_folder_ids": [
        "ASWAOAIcoUs"
    ],
    "profile_picture_url": "https://public.docker.qa:443/yT_sjuRveOYB-HIc4YKTdQ"
}

Realtime

New Websocket

GET https://platform.quip.com/1/websockets/new

Required Scopes

USER_READ

Headers

Authorization:Bearer {{access_token}}

Description

Returns a websocket URL to connect to. The URL may expire if no connection is initiated within 60 seconds.

Response Fields

url

The Websocket URL to connect to for updates.

user_id

The user's ID.

Websocket Events:

Each event sent through the websocket is a json dict with a type indicating what happened.

type

What type of event this packet represents.

  • message - A new message was sent, includes message, user, and thread.
  • heartbeat - Periodically sent to keep the connection open.
  • alive - Reply sent if the client sends {"type": "heartbeat"}.
  • error - Sent in response to any unrecognized command, includes debug.

message

A Quip message in the format described in Get Message.

user

A dict containing the ID and name of the user who sent the message.

thread

A dict containing the ID and title (if any) of the thread the message was sent on.

debug

A string with additional debug information.

Example New Websocket Response

{
    "url": "wss://listen0.quip.com:443/platform/listen/0?t=1",
    "id": "KaDAEAinU0V",
}

Example Websocket Events

{
    "type": "message",
    "message": {
        "author_id": "HFCAEA8XZiw",
        "created_usec": 1394315318489097,
        "id": "LeSADAx0AI5",
        "text": "Hello world"
    },
    "user": {
        "id": "HFCAEA8XZiw",
        "name": "Casey Muller"
    },
    "thread": {
        "id": "ULJAAAkvOHx",
        "title": "Platform Tidbits"
    }
}

{
    "type": "heartbeat"
}

{
    "type": "alive"
}

{
    "type": "error",
    "debug": "Unsupported command."
}