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