# The tool catalog

This page lists the [toolkits](/glossary#glossary-term-toolkit) of SambungAPI, the tools of each toolkit, and the arguments that each tool takes. Read it to plan a call before you sign up.

A project key is the credential your software uses to run tools for one project. A tool executes with a project key, against a connected account of its toolkit: [The SambungAPI API](/docs/api) shows the call and its envelope.

## The toolkits

| Toolkit | Offered | Connects | Tools |
| --- | --- | --- | --- |
| Gmail | Offered | One account for each application user | 5 |
| Google Calendar | Offered | One account for each application user | 5 |
| Google Sheets | Offered | One account for each application user | 9 |
| Google Drive | Offered | One account for each application user | 10 |
| Google Docs | Offered | One account for each application user | 4 |
| Google Slides | Offered | One account for each application user | 4 |
| Google Meet | Offered | One account for each application user | 2 |
| Google Super | Offered | One account for each application user | 0 |
| Outlook | Not offered | One account for each application user | 3 |
| OneDrive | Not offered | One account for each application user | 7 |
| GitHub | Not offered | One account for each application user | 4 |
| Notion | Not offered | One account for each application user | 4 |
| Linear | Not offered | One account for each application user | 13 |
| Jira | Not offered | One account for each application user | 3 |

## Gmail

### Fetch Emails

`GMAIL_FETCH_EMAILS`

Fetch emails from the connected Gmail account, optionally filtered by a query.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `max_results` | number | No | Maximum number of emails to return. Default: `10`. |
| `query` | string | No | Gmail search query (e.g. 'from:alice is:unread') |

### Fetch Message by ID

`GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID`

Fetch a single Gmail message by its message id.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `format` | string, one of `full`, `metadata`, `minimal`, `raw` | No | Message format. Default: `full`. |
| `message_id` | string | Yes | Gmail message id |

### Get Attachment

`GMAIL_GET_ATTACHMENT`

Fetch a Gmail message attachment by message id and attachment id.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `attachment_id` | string | Yes | Attachment id |
| `message_id` | string | Yes | Gmail message id |

### Send Email

`GMAIL_SEND_EMAIL`

Send an email from the connected Gmail account.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | Yes | Email body |
| `extra_recipients` | array of string | No | Additional recipient email addresses |
| `is_html` | boolean | No | Whether the body is HTML. Default: `false`. |
| `recipient_email` | string | Yes | Recipient email address |
| `subject` | string | Yes | Email subject |

### Modify Email Labels

`GMAIL_ADD_LABEL_TO_EMAIL`

Add labels to one Gmail message, remove labels from it, or both. System label ids work as they are: UNREAD, STARRED, IMPORTANT, INBOX, SPAM, TRASH and CATEGORY_*. Mark a message read: remove UNREAD. Star it: add STARRED. Archive it: remove INBOX. Needs the gmail.modify scope (https://www.googleapis.com/auth/gmail.modify).

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `add_label_ids` | array of string | No | Label ids to add, for example ["STARRED"] |
| `message_id` | string | Yes | Gmail message id |
| `remove_label_ids` | array of string | No | Label ids to remove, for example ["UNREAD"] to mark the message read |
| `user_id` | string | No | The Gmail user: me for the connected account, or its email address. Not the user_id of the execute body. Default: `me`. |

## Google Calendar

### Find Event

`GOOGLECALENDAR_FIND_EVENT`

Find events on a Google Calendar within an optional time range.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `calendar_id` | string | Yes | Calendar id. Default: `primary`. |
| `max_results` | number | Yes | Maximum number of events to return. Default: `100`. |
| `order_by` | string, one of `startTime`, `updated` | Yes | Order of the results |
| `page_token` | string | No | Pagination token |
| `q` | string | No | Free-text search query |
| `single_events` | boolean | Yes | Expand recurring events into single instances. Default: `true`. |
| `time_max` | string | Yes | End of the query window (RFC3339) |
| `time_min` | string | Yes | Start of the query window (RFC3339) |

### Create Event

`GOOGLECALENDAR_CREATE_EVENT`

Create a new event on a Google Calendar.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `attendees` | array of string | No | Attendee email addresses |
| `calendar_id` | string | No | Calendar id. Default: `primary`. |
| `create_meeting_room` | boolean | No | Attach a Google Meet conference. Default: `false`. |
| `description` | string | No | Event description |
| `end_datetime` | string | Yes | End date-time (RFC3339) |
| `location` | string | No | Event location |
| `start_datetime` | string | Yes | Start date-time (RFC3339) |
| `summary` | string | Yes | Event title |
| `timezone` | string | No | IANA timezone for the event |

### Patch Event

`GOOGLECALENDAR_PATCH_EVENT`

Update fields of an existing Google Calendar event.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `attendees` | array of string | No | Attendee email addresses |
| `calendar_id` | string | No | Calendar id. Default: `primary`. |
| `description` | string | No | New event description |
| `end_datetime` | string | No | New end date-time (RFC3339) |
| `event_id` | string | Yes | Event id |
| `location` | string | No | New event location |
| `start_datetime` | string | No | New start date-time (RFC3339) |
| `summary` | string | No | New event title |

### Delete Event

`GOOGLECALENDAR_DELETE_EVENT`

Delete a Google Calendar event by id.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `calendar_id` | string | No | Calendar id. Default: `primary`. |
| `event_id` | string | Yes | Event id |

### Find Free Slots

`GOOGLECALENDAR_FIND_FREE_SLOTS`

Find free time slots across one or more calendars in a time window.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of string | Yes | Calendar ids to check |
| `time_max` | string | Yes | End of the window (RFC3339) |
| `time_min` | string | Yes | Start of the window (RFC3339) |
| `timezone` | string | No | IANA timezone |

## Google Sheets

### Batch Get Values

`GOOGLESHEETS_BATCH_GET`

Read values from multiple ranges of a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `ranges` | array of string | Yes | A1 ranges to read |
| `spreadsheet_id` | string | Yes | Spreadsheet id |

### Update Values

`GOOGLESHEETS_VALUES_UPDATE`

Write values into a range of a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `range` | string | Yes | A1 range to write |
| `spreadsheet_id` | string | Yes | Spreadsheet id |
| `value_input_option` | string, one of `USER_ENTERED`, `RAW` | Yes | How input should be interpreted. Default: `USER_ENTERED`. |
| `values` | array of array | Yes | Rows of values |

### Append Values

`GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND`

Append rows of values to a range of a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `range` | string | Yes | A1 range to append after |
| `spreadsheetId` | string | Yes | Spreadsheet id |
| `valueInputOption` | string, one of `USER_ENTERED`, `RAW` | No | How input should be interpreted. Default: `USER_ENTERED`. |
| `values` | array of array | Yes | Rows of values |

### Sort Range

`GOOGLESHEETS_SORT_RANGE`

Sort a range of a Google Spreadsheet by a sort specification.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `range` | object | Yes | GridRange to sort |
| `sortSpec` | object | No | SortSpec (dimensionIndex, sortOrder) |
| `spreadsheet_id` | string | Yes | Spreadsheet id |

### Add Sheet

`GOOGLESHEETS_ADD_SHEET`

Add a new sheet (tab) to a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `spreadsheet_id` | string | Yes | Spreadsheet id |
| `title` | string | Yes | Title of the new sheet |

### Batch Update

`GOOGLESHEETS_BATCH_UPDATE`

Write a batch of values into a sheet starting at a cell location.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `first_cell_location` | string | No | Starting cell (e.g. A1). Default: `A1`. |
| `sheet_name` | string | Yes | Name of the sheet to write into |
| `spreadsheet_id` | string | Yes | Spreadsheet id |
| `value_input_option` | string, one of `USER_ENTERED`, `RAW` | No | How input should be interpreted. Default: `USER_ENTERED`. |
| `values` | array of array | Yes | Rows of values |

### Get Sheet Names

`GOOGLESHEETS_GET_SHEET_NAMES`

List the names of all sheets in a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `spreadsheet_id` | string | Yes | Spreadsheet id |

### Get Batch Values

`GOOGLESHEETS_GET_BATCH_VALUES`

Read values from multiple ranges of a Google Spreadsheet.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `ranges` | array of string | Yes | A1 ranges to read |
| `spreadsheet_id` | string | Yes | Spreadsheet id |

### Create Google Sheet

`GOOGLESHEETS_CREATE_GOOGLE_SHEET1`

Create a new Google Spreadsheet with an optional title.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | No | Optional initial text content |
| `title` | string | No | Title of the new spreadsheet |

## Google Drive

### Find File

`GOOGLEDRIVE_FIND_FILE`

Search for files in Google Drive by query or folder.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `folder_id` | string | No | Restrict results to this folder |
| `pageSize` | number | No | Max results. Default: `10`. |
| `q` | string | No | Drive search query |

### Get File Metadata

`GOOGLEDRIVE_GET_FILE_METADATA`

Get metadata for a single Google Drive file.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `fileId` | string | Yes | Drive file id |
| `supportsAllDrives` | boolean | No | Whether the request applies to all drives. Default: `false`. |

### Move File

`GOOGLEDRIVE_MOVE_FILE`

Move a Google Drive file between folders.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `add_parents` | string | No | Comma-separated folder ids to add |
| `file_id` | string | Yes | Drive file id |
| `remove_parents` | string | No | Comma-separated folder ids to remove |
| `supports_all_drives` | boolean | No | Whether the request applies to all drives. Default: `false`. |

### Delete File

`GOOGLEDRIVE_DELETE_FILE`

Delete a Google Drive file by id.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `fileId` | string | Yes | Drive file id |
| `supportsAllDrives` | boolean | No | Whether the request applies to all drives. Default: `false`. |

### Copy File

`GOOGLEDRIVE_COPY_FILE`

Copy a Google Drive file, optionally with a new title.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | Yes | Drive file id |
| `new_title` | string | No | Title for the copy |

### Add File Sharing Preference

`GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE`

Add a sharing permission (role + type) to a Google Drive file.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | No | Domain for domain-type permissions |
| `email_address` | string | No | Email for user/group-type permissions |
| `file_id` | string | Yes | Drive file id |
| `role` | string, one of `owner`, `organizer`, `fileOrganizer`, `writer`, `commenter`, `reader` | Yes | Permission role |
| `type` | string, one of `user`, `group`, `domain`, `anyone` | Yes | Permission type |

### Upload File

`GOOGLEDRIVE_UPLOAD_FILE`

Upload a file to Google Drive from a previously uploaded blob.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `file_to_upload` | object | Yes | Uploaded file descriptor |
| `parent_id` | string | No | Parent folder id |

### Create Folder

`GOOGLEDRIVE_CREATE_FOLDER`

Create a new folder in Google Drive.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `folder_name` | string | Yes | Name of the new folder |
| `parent_id` | string | No | Parent folder id |

### Create File From Text

`GOOGLEDRIVE_CREATE_FILE_FROM_TEXT`

Create a new text file in Google Drive with the given content.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `file_name` | string | Yes | Name of the new file |
| `text_content` | string | Yes | Text content of the file |

### Export Google Workspace File

`GOOGLEDRIVE_EXPORT_GOOGLE_WORKSPACE_FILE`

Export a Google Workspace file (Docs/Sheets/Slides) to another format.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `fileId` | string | Yes | Drive file id |
| `mimeType` | string | Yes | Target MIME type (e.g. application/pdf) |

## Google Docs

### Get Document Plaintext

`GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT`

Get the plaintext content of a Google Doc.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string | Yes | Google Docs document id |

### Insert Text

`GOOGLEDOCS_INSERT_TEXT_ACTION`

Insert text into a Google Doc, optionally appending to the end.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `append_to_end` | boolean | No | Append at the end of the document. Default: `true`. |
| `document_id` | string | Yes | Google Docs document id |
| `text_to_insert` | string | Yes | Text to insert |

### Replace All Text

`GOOGLEDOCS_REPLACE_ALL_TEXT`

Replace all occurrences of a string in a Google Doc.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string | Yes | Google Docs document id |
| `find_text` | string | Yes | Text to find |
| `match_case` | boolean | No | Case-sensitive match. Default: `false`. |
| `replace_text` | string | Yes | Replacement text |

### Create Document

`GOOGLEDOCS_CREATE_DOCUMENT`

Create a new Google Doc with an optional initial text.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | No | Optional initial text content |
| `title` | string | Yes | Title of the new document |

## Google Slides

### Create Presentation

`GOOGLESLIDES_CREATE_PRESENTATION`

Create a new Google Slides presentation.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes | Title of the new presentation |

### Get Presentation

`GOOGLESLIDES_PRESENTATIONS_GET`

Get a Google Slides presentation by id.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `presentationId` | string | Yes | Presentation id |

### Copy From Template

`GOOGLESLIDES_PRESENTATIONS_COPY_FROM_TEMPLATE`

Copy a Google Slides presentation from a template.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `new_title` | string | No | Title for the copy |
| `parent_folder_id` | string | No | Destination folder id |
| `template_presentation_id` | string | Yes | Template presentation (Drive file) id |

### Batch Update Presentation

`GOOGLESLIDES_PRESENTATIONS_BATCH_UPDATE`

Apply a batch of update requests to a Google Slides presentation.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `presentationId` | string | Yes | Presentation id |
| `requests` | array of object | Yes | Slides batchUpdate requests |

## Google Meet

### Get Meet

`GOOGLEMEET_GET_MEET`

Get a Google Meet space by name.

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Meet space name (e.g. spaces/ABC or ABC) |

### Update Meet Space

`GOOGLEMEET_UPDATE_SPACE`

Update a Google Meet space (e.g. access type).

**Arguments**

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `access_type` | string, one of `TRUSTED`, `OPEN`, `RESTRICTED` | No | New access type |
| `space_id` | string | Yes | Meet space id |

## Google Super

Google Super has no tools of its own. It is a connection that the tools of other toolkits run through.

## Not offered here

This deployment does not offer these toolkits. Each one gives the reason, and the slugs of its tools.

### Outlook

Microsoft's OAuth application is registered but has only been verified against a mocked Graph. A credentialed smoke verification is required before it is offered.

Tools: `OUTLOOK_SEND_EMAIL`, `OUTLOOK_FETCH_EMAILS`, `OUTLOOK_FETCH_MESSAGE_BY_MESSAGE_ID`.

### OneDrive

Microsoft's OAuth application is registered but has only been verified against a mocked Graph. A credentialed smoke verification is required before it is offered.

Tools: `ONE_DRIVE_MOVE_ITEM`, `ONE_DRIVE_GET_ITEM`, `ONE_DRIVE_LIST_FOLDER_CHILDREN`, `ONE_DRIVE_DELETE_ITEM`, `ONE_DRIVE_SEARCH_ITEMS`, `ONE_DRIVE_ONEDRIVE_CREATE_FOLDER`, `ONE_DRIVE_ONEDRIVE_CREATE_TEXT_FILE`.

### GitHub

No OAuth application is registered for this provider yet, so a managed connect flow cannot complete.

Tools: `GITHUB_CREATE_AN_ISSUE`, `GITHUB_GET_ISSUE`, `GITHUB_LIST_ISSUES`, `GITHUB_CREATE_AN_ISSUE_COMMENT`.

### Notion

No OAuth application is registered for this provider yet, so a managed connect flow cannot complete.

Tools: `NOTION_CREATE_PAGE`, `NOTION_GET_PAGE`, `NOTION_SEARCH`, `NOTION_UPDATE_PAGE`.

### Linear

No OAuth application is registered for this provider yet, so a managed connect flow cannot complete.

Tools: `LINEAR_CREATE_ISSUE`, `LINEAR_GET_ISSUE`, `LINEAR_LIST_ISSUES`, `LINEAR_UPDATE_ISSUE`, `LINEAR_DELETE_ISSUE`, `LINEAR_ADD_COMMENT`, `LINEAR_GET_TEAMS`, `LINEAR_GET_USERS`, `LINEAR_GET_LABELS`, `LINEAR_GET_PROJECTS`, `LINEAR_GET_WORKFLOW_STATES`, `LINEAR_SEARCH_ISSUES`, `LINEAR_GET_ISSUE_COMMENTS`.

### Jira

No OAuth application is registered for this provider yet, so a managed connect flow cannot complete.

Tools: `JIRA_CREATE_ISSUE`, `JIRA_GET_ISSUE`, `JIRA_LIST_ISSUES`.

The same catalog as JSON is at [`/v1/specs/catalog`](/v1/specs/catalog). It needs no credential.