The Superhuman Docs API is a RESTful API that lets you programmatically interact with Docs. Here you will find basic info about the API, along with instructions for generating API tokens.
Superhuman Docs has a public API available to all users. The API allows you to get data in and out of tables in Docs as well as access computed values from formulas and user-selected values from controls.
API actions in Docs
The Superhuman Docs REST API allows users to programmatically interact with docs in a number of ways, including:
List and search Superhuman Docs
Listing docs
Creating and copying docs
Listing tables within a doc
Retrieving rows
Inserting and updating rows
Listing pages in a doc
Updating page title/image/icon
Publishing a doc
To see examples of the Superhuman Docs API in action, take a look at this doc.
Check out our full API documentation here.
Enterprise customers wanting to learn about our Admin Audit API, check out this article.
Generate an API token
To use the API, you’ll first need an API token. You create and manage your tokens in your Superhuman Docs account settings. A token is tied to your account, so it can never do more than you can in Docs.
Create a token
Scroll down to the API connections section
Click the Generate API token button
Give your token a name
Choose a permission level: Read only (the default), Write only, or Read and write. Your choice applies to every resource you select below.
-
Choose what your token can access. All content is selected by default. This will grant access to all docs and their content.
You can narrow the accessible content by choosing Selected content. Then select up to 10 docs or tables.
Add other resources, such as Packs, the Docs MCP, or your organization (Enterprise org admins only)
Click Generate API token to confirm
Your new token will appear at the top of the list. Click the Copy token button to copy and use.
Tip: Choose the most restrictive access that meets your needs. If your integration only needs to read data from your docs, keep the default Read only permission.
Understand token access
A default token can read, but not write. It can read your docs, but it can’t make changes, and it has no access to Packs, your organization, or the MCP.
Read + write is a deliberate choice. To let a token make changes, switch the permission level to Read and write when you create it.
One permission level per token. The permission level applies to all of the resources you select. If you need different permission levels for different resources, create separate tokens.
A token can’t exceed your own access. Your token can only access what your account can access, and your organization’s policies still apply.
The MCP is opt-in. The MCP is only included if you select it. Note that choosing specific docs limits what the token can do through the API only. It doesn’t restrict the MCP to those docs. To learn more, see Control what the Docs MCP can access.
Token expiration
Note: This section applies only to members of a Docs Enterprise org. Enterprise org admins can view all of the API tokens in their org, set the org’s token expiration limit, and revoke tokens via admin settings. If you’re an org admin, you can learn more here.
Org admins can set an expiration limit for API tokens across their org. If your org has a limit, your tokens will expire after that period, and the expiration date will show next to each token in your API connections list.
When a token is about to expire, you’ll get an email notification starting 14 days before the expiration date, with reminder emails after that. Once a token expires, any apps, scripts, or services using it will lose access to the API.
You can refresh an expiring token by following the steps below. Note that once the token expires, it cannot be refreshed - you will need to create a new token instead.
Click the link in the notification email, or go to docs.superhuman.com/account and scroll to API connections
Click the three-dot menu, and select Refresh token
Copy the new token, then update your apps and scripts to use it. Note: The old token value stops working as soon as you refresh.
Your token keeps its place in the list, with an updated creation date and expiration date. Each token also shows a status: Active, Expiring soon (14 days or fewer until it expires), or Expired.
If you no longer need a token, you don’t need to regenerate it. You can ignore the email, or delete the token from your API connections list (three-dot menu > Revoke).
FAQs
Are there API size limits on requests?
The limit for requests is 2 MB, but there is also a limit of 85 KB for any given row. See this community post for more details.
Are API limits per workspace, user, or token?
Limits are attached to a user/IP.
Why can’t my token make changes to my docs?
If you’re unable to make edits to your docs via your API token, this could be because the API token is limited to only certain docs or because the token is read-only. You can check the token details in the API connections section of your account settings and, if needed, create a new, more permissive token.
Why am I getting a 429 rate limit error?
If you’re getting a 429 error when trying to use Superhuman Docs’ API, you are running into the API rate limit. Superhuman Docs sets a limit on the number of requests that can be made per minute. For the latest info on the specific rate limits, check out this resource.
The API is returning a date and time stamp different than I’d expect. Why is that?
The API returns dates in Pacific time. The user can write code to offset from there.
How do I send an image to the API?
Right now our API doesn’t accept image files. Instead, the closest we can come is passing an Image URL to an Image URL column.
For Cross-doc, does the API limit of 125Mb count the source doc or the destination doc?
Only the source doc.
Why do I get a 401 error when trying to connect Superhuman Docs to Zapier?
Go to docs.superhuman.com/account and check that there aren’t any restrictions on the API token for Zapier. Zapier can’t connect to Docs with anything less than a full-access Read and write API token.
How do I use the Zapier upsert action? Why can’t I upsert using the row’s ID?
The Zapier Docs integration’s upsert action is a bit confusing to set up. You have to specify the column you want to look for a match on as well as specify the value of that and any other columns you want to update.
However, you can’t update a column that’s based on a formula. Since upsert combines search, update, and create steps, this also effectively prevents you from upserting based on something like a rowID column that is filled by a formula.
One way around this is to add a column to your table and fill it with the row’s ID via automation instead of using a formula. (Note that default value settings won’t work to capture the row ID.)
To learn more about connecting Docs and Zapier, check out this article.