Overview

Summary

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

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

Authentication

Generate an Access Token

https://quip.com/api/personal-token

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/api/personal-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 2.0 Authorization Endpoint

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

OAuth 2.0 Token Endpoint

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

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

Redirect end users to this URL to get an OAuth 2.0 verification code, which you can exchange for an access token. The standard arguments are required:

client_id
The client ID you created for your application.
redirect_uri
The URL we should redirect back to with the verification code.
state
If given, we include this argument in our redirect back to the redirect_uri. This is recommended to prevent a variety of security issues.
$ curl https://platform.quip.com/1/access_token \
-d "grant_type=authorization_code&code=HXAAUAgDmR2\
&redirect_uri=https://goo.gl/" 
client = quip.QuipClient()
client.get_access_token("https://goo.gl/", "HXAAUAgDmR2")
$ curl https://platform.quip.com/1/access_token \
    -d "grant_type=refresh_token&refresh_token=TmZ..." 
client = quip.QuipClient()
client.get_access_token(None, None, refresh_token="TmZ...",
  grant_type="refresh_token")
{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 2592000,
  "token_type": "Bearer"
}

Token Endpoint

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

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

client_id
The client ID you created for your application.
client_secret
The client secret for your client ID.
grant_type

The OAuth 2 grant type, defaults to authorization_code

With an authorization_code grant type (the default), exchanges a verification code obtained from the Authorization Endpoint for access and refresh tokens. Additional required arguments:

  • code - The verification code returned via the Authorization Endpoint redirect.
  • redirect_uri - The same redirect_uri you passed to the Authorization Endpoint.

With a refresh_token grant type, uses a refresh token to acquire a new access token. Additional required argument:

  • refresh_token - The refresh token to retrieve a new access token for.

Threads

$ curl https://platform.quip.com/1/threads/LeSAAAqaCfc \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_thread("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 Threads

GET https://platform.quip.com/1/threads/id
GET https://platform.quip.com/1/threads/?ids=id1,id2,id3

Returns the given threads. You may also pass in a 12 character URL suffix to get the permanent thread ID. If you use the multi-get variant of this method, we return data for each of the given threads in a dictionary by passed-in 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 or spreadsheet, 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.
$ curl https://platform.quip.com/1/threads/recent \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_recent_threads()
{
  "LeSAAAqaCfc": {
    "member_ids": ["KaDAEAinU0V", "UObAEAaHude"],
    "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

Returns the most recent threads to have received messages, similar to the inbox view in the Quip app. Results are returned in the format described above.

Arguments

count
The maximum number of results to return. Defaults to 10, with a maximum of 50.
max_updated_usec
If given, we return threads updated before the given max_updated_usec, which is a UNIX timestamp in microseconds. To use this argument for paging, you can use the updated_usec field in the returned thread objects.
$ curl https://platform.quip.com/1/threads/new-document \
    -d "content=<h1>Title</h1><p>First+paragraph</p>" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.new_document("<h1>Title</h1><p>First paragraph</p>")
{
  "user_ids": ["KaDAEAinU0V"],
  "html": "<h1 id='TfRACAbLTE9'>Title</h1><p id='TfRACAS2BO2'>First paragraph</p>"
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "Title"
  }
}
$ curl https://platform.quip.com/1/threads/new-document \
    -d "content=<p>First</p><p>Second</p>&type=spreadsheet" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.new_document("<p>First</p><p>Second</p>")
{
  "user_ids": ["KaDAEAinU0V"],
  "html": "<div data-section-style='13'><table id='YbMACAmuZsK' title='Table1' style='width: 6em;'><thead><tr><th id='YbMACAxY5uN' class='empty' style='width: 6em'>A<br/></th></tr></thead><tbody><tr id='YbMACAXu00S'><td id='YbMACAfGHI6' style=''><span id='YbMACAfGHI6'>hi</span>

<br/></td></tr><tr id='YbMACAq7W3j'><td id='YbMACAMNIZI' style=''><span id='YbMACAMNIZI'>how's</span>

<br/></td></tr></tbody></table></div>"
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "First"
  }
}

Create a Document or Spreadsheet

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

Creates a document or spreadsheet, returning the new thread in the format described above.

Arguments

content
The HTML or Markdown content of the new document
type
Either document or spreadsheet. Defaults to document.
format
Either html or markdown. Defaults to html.
title
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
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.
$ curl https://platform.quip.com/1/threads/edit-document \
    -d "thread_id=LeSAAAqaCfc&content=<p>New+section</p>" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.edit_document("LeSAAAqaCfc", "<p>New section</p>")
{
  "user_ids": ["KaDAEAinU0V"],
  "html": "<h1 id='TfRACAbLTE9'>Title</h1><p id='TfRACAS2BO2'>First section</p><p>New section</p>"
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "Title"
  }
}
$ curl https://platform.quip.com/1/threads/edit-document \
    -d "thread_id=LeSAAAqaCfc&content=<p>replaced</p>&"\
       "location=4&section_id=TfRACAS2BO2"
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.edit_document(
  "LeSAAAqaCfc", "<p>replaced</p>",
  REPLACE_SECTION, section_id="TfRACAS2BO2")
{
  "user_ids": ["KaDAEAinU0V"],
  "html": "<h1 id='TfRACAbLTE9'>Title</h1><p id='TfRACAS2BO2'>replaced</p><p>New section</p>"
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "Title"
  }
}

Edit a Document

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

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 described above.

Arguments

thread_id
The thread whose document you want to modify
content
The HTML or Markdown content of the new content
format
Either html or markdown. Defaults to html.
section_id
The id for the section you want to modify. Needed for some location values.
location
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).
$ curl https://platform.quip.com/1/threads/add-members \
    -d "thread_id=LeSAAAqaCfc&member_ids=HFCAEA8XZiw" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.add_thread_members("LeSAAAqaCfc", ["HFCAEA8XZiw"])
{
  "user_ids": ["KaDAEAinU0V", "UObAEAaHude", "HFCAEA8XZiw"],
  "html": "...",
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "Expense Reports"
  }
}

Add People to a Thread or Add a Thread to Folders

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

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 the format described above.

Arguments

thread_id
The thread to which you want to add folders and users.
member_ids
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.
$ curl https://platform.quip.com/1/threads/remove-members \
    -d "thread_id=LeSAAAqaCfc&member_ids=HFCAEA8XZiw" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.remove_thread_members("LeSAAAqaCfc", ["HFCAEA8XZiw"])
{
  "user_ids": ["KaDAEAinU0V", "UObAEAaHude"],
  "html": "...",
  "thread": {
    "created_usec": 1392021829698995,
    "updated_usec": 1394315318673846,
    "id": "LeSAAAqaCfc",
    "title": "Expense Reports"
  }
}

Remove People from a Thread or Remove a Thread from Folders

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

Removes the given individuals from the given thread and/or removes the thread from the given folders. We return the updated thread in the format described above.

Arguments

thread_id
The thread from which you want to remove folders and users.
member_ids
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.
$ curl https://platform.quip.com/1/blob/LeSAAAqaCfc/otcjUNr76yCvCMzyq0fXpg \
    -H "Authorization: Bearer {access_token}" -O -J
client = quip.QuipClient(access_token)
body = client.get_blob("LeSAAAqaCfc", "otcjUNr76yCvCMzyq0fXpg")
Raw image binary

Get a Blob from a Thread

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

Retrieves the binary representation of the given blob from the given thread if the user has access. The response is only JSON if an error occurs, otherwise the body is the requested blob.

$ curl https://platform.quip.com/1/blob/LeSAAAqaCfc \
    -H "Authorization: Bearer {access_token}" \
    -F blob=@filename.png
client = quip.QuipClient(access_token)
body = client.put_blob("LeSAAAqaCfc", open("filename.png", "rb"))
snippet = '<img src="%s"/>' % body["url"]
body = client.edit_document("LeSAAAqaCfc", snippet)
{
  "id": "DiPp1ZQyC8QUtvBT4vojzM",
  "url": "/blob/LeSAAAqaCfc/DiPp1ZQyC8QUtvBT4vojzM"
}

Add a Blob to a Thread

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

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 or an id that may be used in the attachment field of Add a Message.

Arguments

blob
The image or blob binary

Response Fields

id
The new blob ID.
url
The relative URL to reference the blob in document edits.

Messages

$ curl https://platform.quip.com/1/messages/LeSAAAqaCfc \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_messages("LeSAAAqaCfc")
[
  {
    "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>"
    ]]
  },
  ...
]

Get Recent Messages

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

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

Arguments

count
The number of messages to return.
max_created_usec
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.

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 max_created_usec 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
$ curl https://platform.quip.com/1/messages/new \
    -d "thread_id=LeSAAAqaCfc&content=Hello+world" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.new_message("LeSAAAqaCfc", "Hello world")
{
  "author_id": "HFCAEA8XZiw",
  "created_usec": 1394315318489097,
  "id": "LeSADAx0AI5",
  "text": "Hello world"
}

Add a Message

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

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

Arguments

thread_id
The thread to which you want to add a message
frame
One of bubble, card, or line
content
Plain text content of the new message (ignored if parts is supplied)
parts
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
A comma-separated list of blob IDs previously uploaded to this thread with Add a Blob.
silent
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.
annotation_id
Adds this message to the given document comment.
section_id
Adds this message as a comment on the given document section.

Folders

$ curl https://platform.quip.com/1/folders/LeSAAAqaCfc \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_folder("LeSAAAqaCfc")
{
  "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/id
GET https://platform.quip.com/1/folders/?ids=id1,id2,id3

Returns the given folders. If you use the multi-get variant of this method, we return data for each of the given folders in a dictionary by folder ID.

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

Response Fields

folder
A 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.
$ curl https://platform.quip.com/1/folders/new \
    -d "title=My+New+Folder" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.new_folder("My New Folder")
{
  "folder": {
    "created_usec": 1395815761359098,
    "updated_usec": 1395818386228824,
    "id": "FFJAOAcKhkX",
    "title": "My New Folder"
  },
  "member_ids": [],
  "children": []
}

Create a Folder

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

Creates a folder, returning the new folder in the format described above.

Arguments

title
The name of the folder
parent_id
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.
color
One of the color constants above. Defaults to manila.
member_ids
A comma-separated list of user IDs to add to this folder.
$ curl https://platform.quip.com/1/folders/update \
    -d "folder_id=FFJAOAcKhkX&title=A+Better+Title" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.update_folder("FFJAOAcKhkX", title="A Better Title")
{
  "folder": {
    "created_usec": 1395815761359098,
    "updated_usec": 1395818386228824,
    "id": "FFJAOAcKhkX",
    "title": "A Better Title"
  },
  "member_ids": [],
  "children": []
}

Change a Folder

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

Updates a folder, returning the updated folder in the format described above.

Arguments

folder_id
The folder to alter
title
If given, update the name of the folder
color
If given, update the color of the folder to one of the color constants described above.
$ curl https://platform.quip.com/1/folders/add-members \
    -d "folder_id=FFJAOAcKhkX&member_ids=HFCAEA8XZiw" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.add_folder_members("FFJAOAcKhkX", ["HFCAEA8XZiw"])
{
  "folder": {
    "color": "manila",
    "created_usec": 1395815761359098,
    "updated_usec": 1395818386228824,
    "id": "FFJAOAcKhkX",
    "title": "sasada"
  },
  "member_ids": ["KaDAEAinU0V", "HFCAEA8XZiw"],
  "children": [
    {"thread_id":"ULJAAAkvOHx"},
    {"folder_id":"LEMAOAQNQwb"}
  ]
}

Add People or Folders to a Folder

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

Shares the given folder with the given user IDs. We return the updated folder in the format described above.

Arguments

folder_id
The folder to which you want to add users.
member_ids
A comma-separated list of user IDs.
$ curl https://platform.quip.com/1/folders/remove-members \
    -d "folder_id=FFJAOAcKhkX&member_ids=HFCAEA8XZiw" \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.remove_folder_members("FFJAOAcKhkX", ["HFCAEA8XZiw"])
{
  "folder": {
    "color": "manila",
    "created_usec": 1395815761359098,
    "updated_usec": 1395818386228824,
    "id": "FFJAOAcKhkX",
    "title": "sasada"
  },
  "member_ids": ["KaDAEAinU0V"],
  "children": [
    {"thread_id":"ULJAAAkvOHx"},
    {"folder_id":"LEMAOAQNQwb"}
  ]
}

Remove People or Folders from a Folder

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

Removes the given users from the given folder. We return the updated folder in the format described above.

Arguments

folder_id
The folder from which you want to remove users.
member_ids
A comma-separated list of user IDs.

Users

$ curl https://platform.quip.com/1/users/KaDAEAinU0V \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_user("KaDAEAinU0V")
{
  "affinity": 0,
  "id": "KaDAEAinU0V",
  "name": "Bret Taylor"
}

Get Users

GET https://platform.quip.com/1/users/id
GET https://platform.quip.com/1/users/?ids=id1,id2,id3

Returns the given users. If you use the multi-get variant of this method, we return data for each of the given users in a dictionary. You can provide either email addresses or user IDs in the "id" field; if you provide multiple email addresses for the same user we return multiple dictionary entries with the same user information for each.

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.
$ curl https://platform.quip.com/1/users/current \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_authenticated_user()
{
  "starred_folder_id": "fffAOAhkwR5",
  "affinity": 0,
  "id": "bdOAEAJ6VBT",
  "name": "Bret Taylor",
  "private_folder_id":"TDHAOAJimIg"
}

Get Authenticated User

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

Returns the currently authenticated user in the format documented above. The response always returns the user's starred_folder_id and private_folder_id.

$ curl https://platform.quip.com/1/users/contacts \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.get_contacts()
[
  {
    "affinity": 0.0,
    "name": "Samantha Stevens",
    "id": "bdOAEAJ6VBT"
  }, {
    "affinity": 0.0,
    "name": "Matthew Cahill",
    "id": "CLXAEAbFxMb"
  },
  ...
]

Get Contacts

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

Returns a list of the contacts for the authenticated user in the format documented above.

Realtime

$ curl https://platform.quip.com/1/websockets/new \
    -H "Authorization: Bearer {access_token}" 
client = quip.QuipClient(access_token)
client.new_websocket()
{
  "url": "wss://listen0.quip.com:443/platform/listen/0?t=1",
  "id": "KaDAEAinU0V",
}

New Websocket

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

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

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