# ThinkBench API

[ThinkBench](https://thinkbench.com) is collaborative documents for humans and
agents. This site documents its API — and every surface of it is generated
from a single contract, so the [REST reference](/api), the
[TypeScript SDK](/sdk), the [CLI](/cli), and the [MCP server](/mcp) always
describe the same operations with the same inputs and outputs.

```text
Base URL: https://app.thinkbench.com/api/v1
```

## Quickstart

1. Create an API key in the [ThinkBench app](https://app.thinkbench.com) under **Settings →
   API keys**, and export it as `THINKBENCH_API_KEY`.
2. List the drives you can access:

```bash
curl "https://app.thinkbench.com/api/v1/drives" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

3. Read a document as Markdown — the same operation via the CLI:

```bash
npx thinkbench documents read --document-id "<documentId>" --pick markdown
```

See [Authentication](/authentication) for how keys and agent attribution
work.

## Pick a surface

| Surface                | Best for                                       |
| ---------------------- | ---------------------------------------------- |
| [REST API](/api)       | Any language, plain HTTP with JSON payloads    |
| [TypeScript SDK](/sdk) | Typed access from Node.js and edge runtimes    |
| [CLI](/cli)            | Terminals, shell scripts, and quick inspection |
| [MCP server](/mcp)     | Claude and other MCP-capable agents            |

All four speak the same API with the same credentials: an operation you find
in one surface exists in the others under a predictable name.

## Using these docs from an agent

These docs are built for programmatic consumption:

- Append `.md` to any page URL for its Markdown source, e.g.
  [`/api/documents/read.md`](/api/documents/read.md).
- Request any page with an `Accept: text/markdown` header to get Markdown
  back without changing the URL.
- [`/llms.txt`](/llms.txt) is a Markdown index of every page;
  [`/llms-full.txt`](/llms-full.txt) is the entire site in one document.
- Every page has a **Copy as Markdown** button.

---

# Authentication

Every surface — REST, SDK, CLI, and MCP — authenticates with the same API
keys. Create and revoke them in the [ThinkBench app](https://app.thinkbench.com) under
**Settings → API keys**. Keys are secrets: send them only in headers, never
in URLs, and rotate any key that leaks.

## API keys

Pass the key in the `x-api-key` header:

```bash
curl "https://app.thinkbench.com/api/v1/drives" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

A key acts as the user who created it: requests can reach exactly what that
user can reach, nothing more. Requests without a valid key receive a `401`
with a JSON error envelope.

Remote MCP clients can use OAuth 2.1 instead of a key — see
[MCP server](/mcp).

## Agent attribution

When software edits a document on your behalf, ThinkBench records **who**
(the user behind the credential) and **via what** (the agent). Attribution
changes who gets credited in version history — never what is authorized.

Two ways to declare an agent:

- Create an **agent key** in Settings, which carries its agent name in the
  key itself.
- Send an `x-thinkbench-agent: <name>` header (the SDK's `agent` config and
  the CLI's `THINKBENCH_AGENT` variable do this for you).

Remote MCP clients connected over OAuth are attributed automatically by
their registered client name.

---

# TypeScript SDK

The SDK is a fully typed client over the [REST API](/api): every method,
input, and output below is derived from the same contract that defines the
API itself.

```bash
npm install thinkbench
```

```ts
import { createThinkBench } from "thinkbench";

const tb = createThinkBench({ apiKey: process.env.THINKBENCH_API_KEY! });

const { item, markdown } = await tb.documents.read({
  documentId: "<documentId>",
});
```

## Configuration

| Option                 | Description                                                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`               | Required. An API key from **Settings → API keys**.                                                                         |
| `agent` _(optional)_   | Names the software making requests so its edits are attributed to it. Unnecessary for agent keys, which already carry one. |
| `baseUrl` _(optional)_ | Defaults to `https://app.thinkbench.com/api/v1`.                                                                                            |

## Behavior

- Payloads are plain JSON over the wire, so timestamps arrive as ISO
  strings.
- Failed calls throw an `ORPCError` carrying the API's
  [error envelope](/api#errors) — there are no silent empty results.

## Methods

| Method | Summary |
| --- | --- |
| [`tb.documents.read(input)`](/api/documents/read) | Read a ThinkBench document and return its current content as Markdown. |
| [`tb.driveItems.sharedWithMe(input)`](/api/drive-items/shared-with-me) | List items shared directly with the user via share grants. |
| [`tb.driveItems.get(input)`](/api/drive-items/get) | Read a drive item with its drive, children, visible ancestors, and shares. |
| [`tb.driveItems.rename(input)`](/api/drive-items/rename) | Rename a drive item. |
| [`tb.driveItems.move(input)`](/api/drive-items/move) | Move an item to another folder or drive. |
| [`tb.driveItems.createChild(input)`](/api/drive-items/create-child) | Create a folder or document inside a folder. |
| [`tb.driveItems.shareSuggestions(input)`](/api/drive-items/share-suggestions) | Organization members who could be given access to this item. |
| [`tb.driveItems.share(input)`](/api/drive-items/share) | Grant a person access to an item by email. |
| [`tb.driveItems.updateShare(input)`](/api/drive-items/update-share) | Change an existing share grant's permission. |
| [`tb.driveItems.removeShare(input)`](/api/drive-items/remove-share) | Revoke a share grant. |
| [`tb.driveItems.setPublication(input)`](/api/drive-items/set-publication) | Publish or unpublish a document to the web. |
| [`tb.drives.list(input)`](/api/drives/list) | List every drive the user can access, each with its items and members. |
| [`tb.drives.create(input)`](/api/drives/create) | Create a shared drive in the active organization. |
| [`tb.drives.rename(input)`](/api/drives/rename) | Rename a drive. |
| [`tb.drives.createItem(input)`](/api/drives/create-item) | Create a folder or document at the drive's root. |
| [`tb.drives.upsertMember(input)`](/api/drives/upsert-member) | Add an organization member to a shared drive or change their role. |
| [`tb.drives.removeMember(input)`](/api/drives/remove-member) | Remove a member from a shared drive. |

---

# CLI

The `thinkbench` CLI exposes every [API operation](/api) as a subcommand:
commands, flags, and help text are derived from the same contract as the
REST API, so the CLI is never missing an operation.

```bash
npx thinkbench drives list
```

## Configuration

| Variable                           | Description                                         |
| ---------------------------------- | --------------------------------------------------- |
| `THINKBENCH_API_KEY`               | Required. An API key from **Settings → API keys**.  |
| `THINKBENCH_AGENT` _(optional)_    | Names the software making requests for attribution. |
| `THINKBENCH_BASE_URL` _(optional)_ | Defaults to `https://app.thinkbench.com/api/v1`.                     |

## Output shaping

Every command accepts `--pick <field>` to print a single top-level field of
the response, raw:

```bash
npx thinkbench documents read --document-id "<documentId>" --pick markdown
```

Piping to `jq` works too — `--pick` just keeps the CLI self-sufficient.

## Commands

Flags for each command are the operation's input fields, kebab-cased
(`documentId` becomes `--document-id`); see each operation page for the full
list. `npx thinkbench --help` prints the same catalog.

| Command | Summary |
| --- | --- |
| [`thinkbench documents read`](/api/documents/read) | Read a ThinkBench document and return its current content as Markdown. |
| [`thinkbench drive-items shared-with-me`](/api/drive-items/shared-with-me) | List items shared directly with the user via share grants. |
| [`thinkbench drive-items get`](/api/drive-items/get) | Read a drive item with its drive, children, visible ancestors, and shares. |
| [`thinkbench drive-items rename`](/api/drive-items/rename) | Rename a drive item. |
| [`thinkbench drive-items move`](/api/drive-items/move) | Move an item to another folder or drive. |
| [`thinkbench drive-items create-child`](/api/drive-items/create-child) | Create a folder or document inside a folder. |
| [`thinkbench drive-items share-suggestions`](/api/drive-items/share-suggestions) | Organization members who could be given access to this item. |
| [`thinkbench drive-items share`](/api/drive-items/share) | Grant a person access to an item by email. |
| [`thinkbench drive-items update-share`](/api/drive-items/update-share) | Change an existing share grant's permission. |
| [`thinkbench drive-items remove-share`](/api/drive-items/remove-share) | Revoke a share grant. |
| [`thinkbench drive-items set-publication`](/api/drive-items/set-publication) | Publish or unpublish a document to the web. |
| [`thinkbench drives list`](/api/drives/list) | List every drive the user can access, each with its items and members. |
| [`thinkbench drives create`](/api/drives/create) | Create a shared drive in the active organization. |
| [`thinkbench drives rename`](/api/drives/rename) | Rename a drive. |
| [`thinkbench drives create-item`](/api/drives/create-item) | Create a folder or document at the drive's root. |
| [`thinkbench drives upsert-member`](/api/drives/upsert-member) | Add an organization member to a shared drive or change their role. |
| [`thinkbench drives remove-member`](/api/drives/remove-member) | Remove a member from a shared drive. |

---

# MCP server

ThinkBench self-hosts an MCP server at:

```text
https://app.thinkbench.com/api/v1/mcp
```

Its tools are the [API operations](/api) — the same contract that defines
REST, the SDK, and the CLI registers each operation as a tool, so an agent
connected over MCP can do exactly what the API can do, with the same
authorization.

## Connect

With an API key, from Claude Code:

```bash
claude mcp add --transport http thinkbench https://app.thinkbench.com/api/v1/mcp \
  --header "x-api-key: $THINKBENCH_API_KEY"
```

Or in a JSON MCP configuration:

```json
{
  "mcpServers": {
    "thinkbench": {
      "type": "http",
      "url": "https://app.thinkbench.com/api/v1/mcp",
      "headers": { "x-api-key": "<your API key>" }
    }
  }
}
```

## OAuth for remote clients

Clients that can't hold an API key can connect with no configuration at all:
the server speaks OAuth 2.1. An unauthenticated request is challenged, the
client registers itself, and you approve it once in the browser. Edits made
through such a client are attributed to its registered name — see
[Authentication](/authentication).

## Tools

Tools marked read-only carry the MCP `readOnlyHint` annotation, so cautious
clients can call them without confirmation prompts.

| Tool | Read-only | Summary |
| --- | --- | --- |
| [`documents_read`](/api/documents/read) | yes | Read a ThinkBench document and return its current content as Markdown. |
| [`drive_items_shared_with_me`](/api/drive-items/shared-with-me) | yes | List items shared directly with the user via share grants. |
| [`drive_items_get`](/api/drive-items/get) | yes | Read a drive item with its drive, children, visible ancestors, and shares. |
| [`drive_items_rename`](/api/drive-items/rename) | no | Rename a drive item. |
| [`drive_items_move`](/api/drive-items/move) | no | Move an item to another folder or drive. |
| [`drive_items_create_child`](/api/drive-items/create-child) | no | Create a folder or document inside a folder. |
| [`drive_items_share_suggestions`](/api/drive-items/share-suggestions) | yes | Organization members who could be given access to this item. |
| [`drive_items_share`](/api/drive-items/share) | no | Grant a person access to an item by email. |
| [`drive_items_update_share`](/api/drive-items/update-share) | no | Change an existing share grant's permission. |
| [`drive_items_remove_share`](/api/drive-items/remove-share) | no | Revoke a share grant. |
| [`drive_items_set_publication`](/api/drive-items/set-publication) | no | Publish or unpublish a document to the web. |
| [`drives_list`](/api/drives/list) | yes | List every drive the user can access, each with its items and members. |
| [`drives_create`](/api/drives/create) | no | Create a shared drive in the active organization. |
| [`drives_rename`](/api/drives/rename) | no | Rename a drive. |
| [`drives_create_item`](/api/drives/create-item) | no | Create a folder or document at the drive's root. |
| [`drives_upsert_member`](/api/drives/upsert-member) | no | Add an organization member to a shared drive or change their role. |
| [`drives_remove_member`](/api/drives/remove-member) | no | Remove a member from a shared drive. |

---

# REST API

```text
Base URL: https://app.thinkbench.com/api/v1
```

Authenticate with an API key in the `x-api-key` header — see
[Authentication](/authentication).

## Conventions

- Requests and responses are JSON (`content-type: application/json`);
  timestamps are ISO 8601 strings.
- Operations return whole canonical objects — a [DriveItem](/api/objects/drive-item)
  is the same shape everywhere it appears — rather than per-endpoint field
  subsets.
- Write operations with nothing to add return an empty `200` response.
- Ids you don't have access to and ids that don't exist are indistinguishable
  `404`s.

## Errors

Failures return a non-2xx status with a JSON envelope:

```json
{ "code": "UNAUTHORIZED", "message": "invalid API key" }
```

`code` is a stable machine-readable string; `message` is human-readable
detail.

## Operations

| Operation | Method | Path | Summary |
| --- | --- | --- | --- |
| [`documents.read`](/api/documents/read) | GET | `/documents/{documentId}` | Read a ThinkBench document and return its current content as Markdown. |
| [`driveItems.sharedWithMe`](/api/drive-items/shared-with-me) | GET | `/drive-items/shared-with-me` | List items shared directly with the user via share grants. |
| [`driveItems.get`](/api/drive-items/get) | GET | `/drive-items/{itemId}` | Read a drive item with its drive, children, visible ancestors, and shares. |
| [`driveItems.rename`](/api/drive-items/rename) | PATCH | `/drive-items/{itemId}` | Rename a drive item. |
| [`driveItems.move`](/api/drive-items/move) | POST | `/drive-items/{itemId}/move` | Move an item to another folder or drive. |
| [`driveItems.createChild`](/api/drive-items/create-child) | POST | `/drive-items/{itemId}/children` | Create a folder or document inside a folder. |
| [`driveItems.shareSuggestions`](/api/drive-items/share-suggestions) | GET | `/drive-items/{itemId}/share-suggestions` | Organization members who could be given access to this item. |
| [`driveItems.share`](/api/drive-items/share) | POST | `/drive-items/{itemId}/access` | Grant a person access to an item by email. |
| [`driveItems.updateShare`](/api/drive-items/update-share) | PATCH | `/drive-items/{itemId}/access/{email}` | Change an existing share grant's permission. |
| [`driveItems.removeShare`](/api/drive-items/remove-share) | DELETE | `/drive-items/{itemId}/access/{email}` | Revoke a share grant. |
| [`driveItems.setPublication`](/api/drive-items/set-publication) | PUT | `/drive-items/{itemId}/publication` | Publish or unpublish a document to the web. |
| [`driveItems.uploadImage`](/api/drive-items/upload-image) | POST | `/drive-items/{itemId}/images` | Upload an image used inside a document. |
| [`drives.list`](/api/drives/list) | GET | `/drives` | List every drive the user can access, each with its items and members. |
| [`drives.create`](/api/drives/create) | POST | `/drives` | Create a shared drive in the active organization. |
| [`drives.rename`](/api/drives/rename) | PATCH | `/drives/{driveId}` | Rename a drive. |
| [`drives.createItem`](/api/drives/create-item) | POST | `/drives/{driveId}/items` | Create a folder or document at the drive's root. |
| [`drives.upsertMember`](/api/drives/upsert-member) | PUT | `/drives/{driveId}/members/{userId}` | Add an organization member to a shared drive or change their role. |
| [`drives.removeMember`](/api/drives/remove-member) | DELETE | `/drives/{driveId}/members/{userId}` | Remove a member from a shared drive. |

---

# documents.read

Read a ThinkBench document and return its current content as Markdown.

`GET /api/v1/documents/{documentId}`

- SDK: [`tb.documents.read(input)`](/sdk)
- CLI: [`thinkbench documents read`](/cli)
- MCP tool: [`documents_read`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `documentId` | `string` | path | The document's id, from its URL or a listing. |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `item` | [DriveItem](/api/objects/drive-item) |  |
| `markdown` | `string` |  |
| `prosemirrorDoc` | `unknown` |  |
| `authors` | `object[]` | Who edited this most recently. |

## Examples

### curl

```bash
curl "https://app.thinkbench.com/api/v1/documents/<documentId>" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
const result = await tb.documents.read({ documentId: "<documentId>" });
```

### CLI

```bash
thinkbench documents read --document-id "<documentId>"
```

### MCP

```json
{
  "name": "documents_read",
  "arguments": {
    "documentId": "<documentId>"
  }
}
```

## Notes

The `markdown` and `prosemirrorDoc` projections come from one live snapshot
of the collaborative document, so they always agree — and both include edits
other people (or agents) are making right now, before they're saved to
version history.

To pull just the Markdown from the CLI:

```bash
npx thinkbench documents read --document-id "<documentId>" --pick markdown
```

---

# driveItems.sharedWithMe

List items shared directly with the user via share grants.

`GET /api/v1/drive-items/shared-with-me`

- SDK: [`tb.driveItems.sharedWithMe(input)`](/sdk)
- CLI: [`thinkbench drive-items shared-with-me`](/cli)
- MCP tool: [`drive_items_shared_with_me`](/mcp)

## Input

This operation takes no input.

## Output

| Field | Type | Description |
| --- | --- | --- |
| `items` | [DriveItem](/api/objects/drive-item)`[]` |  |

## Examples

### curl

```bash
curl "https://app.thinkbench.com/api/v1/drive-items/shared-with-me" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
const result = await tb.driveItems.sharedWithMe();
```

### CLI

```bash
thinkbench drive-items shared-with-me
```

### MCP

```json
{
  "name": "drive_items_shared_with_me",
  "arguments": {}
}
```

---

# driveItems.get

Read a drive item with its drive, children, visible ancestors, and shares.

`GET /api/v1/drive-items/{itemId}`

- SDK: [`tb.driveItems.get(input)`](/sdk)
- CLI: [`thinkbench drive-items get`](/cli)
- MCP tool: [`drive_items_get`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `item` | [DriveItem](/api/objects/drive-item) |  |

## Examples

### curl

```bash
curl "https://app.thinkbench.com/api/v1/drive-items/<itemId>" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
const result = await tb.driveItems.get({ itemId: "<itemId>" });
```

### CLI

```bash
thinkbench drive-items get --item-id "<itemId>"
```

### MCP

```json
{
  "name": "drive_items_get",
  "arguments": {
    "itemId": "<itemId>"
  }
}
```

---

# driveItems.rename

Rename a drive item.

`PATCH /api/v1/drive-items/{itemId}`

- SDK: [`tb.driveItems.rename(input)`](/sdk)
- CLI: [`thinkbench drive-items rename`](/cli)
- MCP tool: [`drive_items_rename`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `name` | `string` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X PATCH "https://app.thinkbench.com/api/v1/drive-items/<itemId>" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Q3 planning"}'
```

### TypeScript SDK

```ts
await tb.driveItems.rename({ itemId: "<itemId>", name: "Q3 planning" });
```

### CLI

```bash
thinkbench drive-items rename --item-id "<itemId>" --name "Q3 planning"
```

### MCP

```json
{
  "name": "drive_items_rename",
  "arguments": {
    "itemId": "<itemId>",
    "name": "Q3 planning"
  }
}
```

---

# driveItems.move

Move an item to another folder or drive.

`POST /api/v1/drive-items/{itemId}/move`

- SDK: [`tb.driveItems.move(input)`](/sdk)
- CLI: [`thinkbench drive-items move`](/cli)
- MCP tool: [`drive_items_move`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `driveId` | `string` | body |  |
| `parentId` | `string` \| `null` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drive-items/<itemId>/move" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"driveId":"<driveId>","parentId":"<parentId>"}'
```

### TypeScript SDK

```ts
await tb.driveItems.move({ itemId: "<itemId>", driveId: "<driveId>", parentId: "<parentId>" });
```

### CLI

```bash
thinkbench drive-items move --item-id "<itemId>" --drive-id "<driveId>" --parent-id "<parentId>"
```

### MCP

```json
{
  "name": "drive_items_move",
  "arguments": {
    "itemId": "<itemId>",
    "driveId": "<driveId>",
    "parentId": "<parentId>"
  }
}
```

---

# driveItems.createChild

Create a folder or document inside a folder.

`POST /api/v1/drive-items/{itemId}/children`

- SDK: [`tb.driveItems.createChild(input)`](/sdk)
- CLI: [`thinkbench drive-items create-child`](/cli)
- MCP tool: [`drive_items_create_child`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `name` | `string` | body |  |
| `driveItemType` | `"folder"` \| `"docs_workbook"` \| `"viz_workbook"` | body |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `item` | [DriveItem](/api/objects/drive-item) |  |

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drive-items/<itemId>/children" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Q3 planning","driveItemType":"folder"}'
```

### TypeScript SDK

```ts
const result = await tb.driveItems.createChild({ itemId: "<itemId>", name: "Q3 planning", driveItemType: "folder" });
```

### CLI

```bash
thinkbench drive-items create-child --item-id "<itemId>" --name "Q3 planning" --drive-item-type "folder"
```

### MCP

```json
{
  "name": "drive_items_create_child",
  "arguments": {
    "itemId": "<itemId>",
    "name": "Q3 planning",
    "driveItemType": "folder"
  }
}
```

---

# driveItems.shareSuggestions

Organization members who could be given access to this item.

`GET /api/v1/drive-items/{itemId}/share-suggestions`

- SDK: [`tb.driveItems.shareSuggestions(input)`](/sdk)
- CLI: [`thinkbench drive-items share-suggestions`](/cli)
- MCP tool: [`drive_items_share_suggestions`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `members` | `object[]` |  |

## Examples

### curl

```bash
curl "https://app.thinkbench.com/api/v1/drive-items/<itemId>/share-suggestions" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
const result = await tb.driveItems.shareSuggestions({ itemId: "<itemId>" });
```

### CLI

```bash
thinkbench drive-items share-suggestions --item-id "<itemId>"
```

### MCP

```json
{
  "name": "drive_items_share_suggestions",
  "arguments": {
    "itemId": "<itemId>"
  }
}
```

---

# driveItems.share

Grant a person access to an item by email.

`POST /api/v1/drive-items/{itemId}/access`

- SDK: [`tb.driveItems.share(input)`](/sdk)
- CLI: [`thinkbench drive-items share`](/cli)
- MCP tool: [`drive_items_share`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `email` | `string` | body |  |
| `permission` | `"read_write"` \| `"read_only"` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drive-items/<itemId>/access" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"email":"ada@example.com","permission":"read_write"}'
```

### TypeScript SDK

```ts
await tb.driveItems.share({ itemId: "<itemId>", email: "ada@example.com", permission: "read_write" });
```

### CLI

```bash
thinkbench drive-items share --item-id "<itemId>" --email "ada@example.com" --permission "read_write"
```

### MCP

```json
{
  "name": "drive_items_share",
  "arguments": {
    "itemId": "<itemId>",
    "email": "ada@example.com",
    "permission": "read_write"
  }
}
```

---

# driveItems.updateShare

Change an existing share grant's permission.

`PATCH /api/v1/drive-items/{itemId}/access/{email}`

- SDK: [`tb.driveItems.updateShare(input)`](/sdk)
- CLI: [`thinkbench drive-items update-share`](/cli)
- MCP tool: [`drive_items_update_share`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `email` | `string` | path |  |
| `permission` | `"read_write"` \| `"read_only"` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X PATCH "https://app.thinkbench.com/api/v1/drive-items/<itemId>/access/<email>" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"permission":"read_write"}'
```

### TypeScript SDK

```ts
await tb.driveItems.updateShare({ itemId: "<itemId>", email: "ada@example.com", permission: "read_write" });
```

### CLI

```bash
thinkbench drive-items update-share --item-id "<itemId>" --email "ada@example.com" --permission "read_write"
```

### MCP

```json
{
  "name": "drive_items_update_share",
  "arguments": {
    "itemId": "<itemId>",
    "email": "ada@example.com",
    "permission": "read_write"
  }
}
```

---

# driveItems.removeShare

Revoke a share grant.

`DELETE /api/v1/drive-items/{itemId}/access/{email}`

- SDK: [`tb.driveItems.removeShare(input)`](/sdk)
- CLI: [`thinkbench drive-items remove-share`](/cli)
- MCP tool: [`drive_items_remove_share`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `email` | `string` | path |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X DELETE "https://app.thinkbench.com/api/v1/drive-items/<itemId>/access/<email>" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
await tb.driveItems.removeShare({ itemId: "<itemId>", email: "ada@example.com" });
```

### CLI

```bash
thinkbench drive-items remove-share --item-id "<itemId>" --email "ada@example.com"
```

### MCP

```json
{
  "name": "drive_items_remove_share",
  "arguments": {
    "itemId": "<itemId>",
    "email": "ada@example.com"
  }
}
```

---

# driveItems.setPublication

Publish or unpublish a document to the web.

`PUT /api/v1/drive-items/{itemId}/publication`

- SDK: [`tb.driveItems.setPublication(input)`](/sdk)
- CLI: [`thinkbench drive-items set-publication`](/cli)
- MCP tool: [`drive_items_set_publication`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `published` | `boolean` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X PUT "https://app.thinkbench.com/api/v1/drive-items/<itemId>/publication" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"published":true}'
```

### TypeScript SDK

```ts
await tb.driveItems.setPublication({ itemId: "<itemId>", published: true });
```

### CLI

```bash
thinkbench drive-items set-publication --item-id "<itemId>" --published true
```

### MCP

```json
{
  "name": "drive_items_set_publication",
  "arguments": {
    "itemId": "<itemId>",
    "published": true
  }
}
```

---

# driveItems.uploadImage

Upload an image used inside a document.

`POST /api/v1/drive-items/{itemId}/images`

This operation uploads a file, so it is available over REST only — file inputs aren't representable as [CLI](/cli) flags or [MCP](/mcp) tool arguments.

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `itemId` | `string` | path |  |
| `filename` | `string` | body |  |
| `image` | `file` | body |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `url` | `string` |  |
| `name` | `string` |  |

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drive-items/<itemId>/images" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -F "filename=<filename>" \
  -F "image=@./photo.png"
```

### TypeScript SDK

```ts
const result = await tb.driveItems.uploadImage({ itemId: "<itemId>", filename: "<filename>", image: "<image>" });
```

---

# drives.list

List every drive the user can access, each with its items and members.

`GET /api/v1/drives`

- SDK: [`tb.drives.list(input)`](/sdk)
- CLI: [`thinkbench drives list`](/cli)
- MCP tool: [`drives_list`](/mcp)

## Input

This operation takes no input.

## Output

| Field | Type | Description |
| --- | --- | --- |
| `drives` | [Drive](/api/objects/drive)`[]` |  |

## Examples

### curl

```bash
curl "https://app.thinkbench.com/api/v1/drives" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
const result = await tb.drives.list();
```

### CLI

```bash
thinkbench drives list
```

### MCP

```json
{
  "name": "drives_list",
  "arguments": {}
}
```

---

# drives.create

Create a shared drive in the active organization.

`POST /api/v1/drives`

- SDK: [`tb.drives.create(input)`](/sdk)
- CLI: [`thinkbench drives create`](/cli)
- MCP tool: [`drives_create`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `name` | `string` | body |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `drive` | [Drive](/api/objects/drive) |  |

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drives" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Q3 planning"}'
```

### TypeScript SDK

```ts
const result = await tb.drives.create({ name: "Q3 planning" });
```

### CLI

```bash
thinkbench drives create --name "Q3 planning"
```

### MCP

```json
{
  "name": "drives_create",
  "arguments": {
    "name": "Q3 planning"
  }
}
```

---

# drives.rename

Rename a drive.

`PATCH /api/v1/drives/{driveId}`

- SDK: [`tb.drives.rename(input)`](/sdk)
- CLI: [`thinkbench drives rename`](/cli)
- MCP tool: [`drives_rename`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `driveId` | `string` | path |  |
| `name` | `string` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X PATCH "https://app.thinkbench.com/api/v1/drives/<driveId>" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Q3 planning"}'
```

### TypeScript SDK

```ts
await tb.drives.rename({ driveId: "<driveId>", name: "Q3 planning" });
```

### CLI

```bash
thinkbench drives rename --drive-id "<driveId>" --name "Q3 planning"
```

### MCP

```json
{
  "name": "drives_rename",
  "arguments": {
    "driveId": "<driveId>",
    "name": "Q3 planning"
  }
}
```

---

# drives.createItem

Create a folder or document at the drive's root.

`POST /api/v1/drives/{driveId}/items`

- SDK: [`tb.drives.createItem(input)`](/sdk)
- CLI: [`thinkbench drives create-item`](/cli)
- MCP tool: [`drives_create_item`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `driveId` | `string` | path |  |
| `name` | `string` | body |  |
| `driveItemType` | `"folder"` \| `"docs_workbook"` \| `"viz_workbook"` | body |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `item` | [DriveItem](/api/objects/drive-item) |  |

## Examples

### curl

```bash
curl -X POST "https://app.thinkbench.com/api/v1/drives/<driveId>/items" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Q3 planning","driveItemType":"folder"}'
```

### TypeScript SDK

```ts
const result = await tb.drives.createItem({ driveId: "<driveId>", name: "Q3 planning", driveItemType: "folder" });
```

### CLI

```bash
thinkbench drives create-item --drive-id "<driveId>" --name "Q3 planning" --drive-item-type "folder"
```

### MCP

```json
{
  "name": "drives_create_item",
  "arguments": {
    "driveId": "<driveId>",
    "name": "Q3 planning",
    "driveItemType": "folder"
  }
}
```

---

# drives.upsertMember

Add an organization member to a shared drive or change their role.

`PUT /api/v1/drives/{driveId}/members/{userId}`

- SDK: [`tb.drives.upsertMember(input)`](/sdk)
- CLI: [`thinkbench drives upsert-member`](/cli)
- MCP tool: [`drives_upsert_member`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `driveId` | `string` | path |  |
| `userId` | `string` | path |  |
| `role` | `"owner"` \| `"manager"` \| `"contributor"` | body |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X PUT "https://app.thinkbench.com/api/v1/drives/<driveId>/members/<userId>" \
  -H "x-api-key: $THINKBENCH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"role":"owner"}'
```

### TypeScript SDK

```ts
await tb.drives.upsertMember({ driveId: "<driveId>", userId: "<userId>", role: "owner" });
```

### CLI

```bash
thinkbench drives upsert-member --drive-id "<driveId>" --user-id "<userId>" --role "owner"
```

### MCP

```json
{
  "name": "drives_upsert_member",
  "arguments": {
    "driveId": "<driveId>",
    "userId": "<userId>",
    "role": "owner"
  }
}
```

---

# drives.removeMember

Remove a member from a shared drive.

`DELETE /api/v1/drives/{driveId}/members/{userId}`

- SDK: [`tb.drives.removeMember(input)`](/sdk)
- CLI: [`thinkbench drives remove-member`](/cli)
- MCP tool: [`drives_remove_member`](/mcp)

## Input

| Field | Type | In | Description |
| --- | --- | --- | --- |
| `driveId` | `string` | path |  |
| `userId` | `string` | path |  |

## Output

Returns an empty response on success.

## Examples

### curl

```bash
curl -X DELETE "https://app.thinkbench.com/api/v1/drives/<driveId>/members/<userId>" \
  -H "x-api-key: $THINKBENCH_API_KEY"
```

### TypeScript SDK

```ts
await tb.drives.removeMember({ driveId: "<driveId>", userId: "<userId>" });
```

### CLI

```bash
thinkbench drives remove-member --drive-id "<driveId>" --user-id "<userId>"
```

### MCP

```json
{
  "name": "drives_remove_member",
  "arguments": {
    "driveId": "<driveId>",
    "userId": "<userId>"
  }
}
```

---

# DriveItem

The canonical `DriveItem` object, returned whole by every operation that touches it. Fields marked optional are present when the returning operation loads them.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `driveId` | `string` |  |
| `driveItemType` | `"folder"` \| `"docs_workbook"` \| `"viz_workbook"` |  |
| `name` | `string` |  |
| `parentId` | `string` \| `null` |  |
| `ancestorIds` | `string[]` |  |
| `published` | `boolean` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `drive` | [Drive](/api/objects/drive) |  |
| `children` _(optional)_ | [DriveItem](/api/objects/drive-item)`[]` |  |
| `ancestors` _(optional)_ | [DriveItem](/api/objects/drive-item)`[]` |  |
| `sheets` _(optional)_ | `object[]` |  |
| `itemUsers` _(optional)_ | `object[]` |  |
| `access` _(optional)_ | `object` |  |

---

# Drive

The canonical `Drive` object, returned whole by every operation that touches it. Fields marked optional are present when the returning operation loads them.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string` \| `null` |  |
| `ownerId` | `string` |  |
| `ownerType` | `"user"` \| `"organization"` |  |
| `organizationId` | `string` \| `null` |  |
| `createdAt` | `string` |  |
| `updatedAt` | `string` |  |
| `viewerRole` _(optional)_ | `"owner"` \| `"manager"` \| `"contributor"` |  |
| `items` _(optional)_ | [DriveItem](/api/objects/drive-item)`[]` |  |
| `driveUsers` _(optional)_ | `object[]` |  |
| `ownerUser` _(optional)_ | `object` \| `null` |  |
| `ownerOrganization` _(optional)_ | `object` \| `null` |  |