Connect AI agents to Grain

Scalekit connector

The Grain connector lets your AI agent act in each user's Grain account. Each user connects their own Grain access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 19 tools.

Tools: 19
What they doRead · write · destructive: 9 · 6 · 49 read6 write4 destructive
Users sign in with: Access token

Setup

Install the SDK
- Node.js
- Python
Terminal window
npm install @scalekit-sdk/node dotenv
Terminal window
pip install scalekit-sdk-python python-dotenv
Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Create the Grain connection
In AgentKit > Connections, create a Grain connection. The name you give it is the connection_name your code passes. See Configure connections.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'grain'
13
const identifier = 'user_123'
14

15
// Generate an authorization link for the user
16
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
17
console.log('Authorize Grain:', link)
18
const rl = createInterface({ input: process.stdin, output: process.stdout })
19
await rl.question('Press Enter after authorizing...')
20
rl.close()
21

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'grain_hooks_list',
27
  toolInput: {},
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "grain"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Grain:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="grain_hooks_list",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user opens the link once and enters their Grain credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

grain_hooks_listList the webhooks (hooks) registered on the Grain workspace, optionally filtered by event type or enabled/disabled state.Read-only
List Webhooks
List the webhooks (hooks) registered on the Grain workspace, optionally filtered by event type or enabled/disabled state.
Inputs
hook_typestring
Only return webhooks subscribed to this event type.one of recording_addedrecording_updatedrecording_deletedhighlight_addedhighlight_updatedhighlight_deletedstory_addedstory_updatedstory_deletedupload_status
statestring
Only return webhooks in this state.one of enableddisabled
grain_meeting_types_listList the meeting types configured in the Grain workspace, with their id, name, and scope (internal or external).Read-only
List Meeting Types
List the meeting types configured in the Grain workspace, with their id, name, and scope (internal or external). Use this to resolve meeting type ids needed by grain_recordings_list.
Inputs
This tool takes no inputs.
grain_recording_downloadDownload the underlying media file for a Grain recording (video/mp4 or audio/mp3, depending on the recording's media_type).Read-only
Download Recording
Download the underlying media file for a Grain recording (video/mp4 or audio/mp3, depending on the recording's media_type).
Inputs
recording_idstringrequired
UUID of the recording to download.
grain_recording_getGet a single Grain recording by id, with optional inclusion of highlights, participants, AI summary/action items, private notes, calendar event, HubSpot links, and screenshares.Read-only
Get Recording
Get a single Grain recording by id, with optional inclusion of highlights, participants, AI summary/action items, private notes, calendar event, HubSpot links, and screenshares.
Inputs
recording_idstringrequired
UUID of the recording to fetch. Use grain_recordings_list to discover recording ids.
include_ai_action_itemsboolean
Include AI-detected action items in the response.
include_ai_summaryboolean
Include the AI-generated meeting summary in the response.
include_calendar_eventboolean
Include the linked calendar event details in the response.
include_highlightsboolean
Include the recording's highlights in the response.
include_hubspotboolean
Include linked HubSpot company and deal ids in the response.
include_participantsboolean
Include the recording's participant list in the response.
include_private_notesboolean
Personal Access Token only. Include the caller's private notes on the recording.
include_screensharesboolean
Include screenshare timing segments in the response.
grain_recording_transcript_getGet the structured JSON transcript of a Grain recording: an array of segments, each with a start/end timestamp (ms), the spoken text, and the speaker's name and participant id.Read-only
Get Recording Transcript (JSON)
Get the structured JSON transcript of a Grain recording: an array of segments, each with a start/end timestamp (ms), the spoken text, and the speaker's name and participant id.
Inputs
recording_idstringrequired
UUID of the recording whose transcript should be fetched.
grain_recording_transcript_text_getGet a Grain recording's transcript as plain text, WebVTT, or SRT — ready to display or feed into subtitle/captioning tools, instead of the structured JSON segments returned by grain_recording_transcript_get.Read-only
Get Recording Transcript (Text Format)
Get a Grain recording's transcript as plain text, WebVTT, or SRT — ready to display or feed into subtitle/captioning tools, instead of the structured JSON segments returned by grain_recording_transcript_get.
Inputs
formatstringrequired
Text format to return: 'txt' (speaker name + text per line), 'vtt' (WebVTT), or 'srt' (SubRip subtitles).one of txtvttsrtdefault txt
recording_idstringrequired
UUID of the recording whose transcript should be fetched.
grain_recordings_listList meeting recordings in the Grain workspace (or, with a Personal Access Token, the caller's own recordings).Read-only
List Recordings
List meeting recordings in the Grain workspace (or, with a Personal Access Token, the caller's own recordings). Supports filtering by date range, title search, team, meeting type, attendance, and participant scope, plus optional inclusion of highlights, participants, AI summary/action items, and more. Returns a page of recordings and a cursor for the next page.
Inputs
after_datetimestring
Only return recordings whose start_datetime is after this ISO8601 timestamp (inclusive).
attendancestring
Personal Access Token only. 'hosted' returns only recordings the caller hosted; 'attended' returns only recordings the caller attended.one of hostedattended
before_datetimestring
Only return recordings whose start_datetime is before this ISO8601 timestamp (exclusive).
cursorstring
Pagination cursor from a previous response's cursor field, used to fetch the next page.
include_ai_action_itemsboolean
Include AI-detected action items in the response.
include_ai_summaryboolean
Include the AI-generated meeting summary in the response.
include_calendar_eventboolean
Include the linked calendar event details in the response.
include_highlightsboolean
Include each recording's highlights in the response.
include_hubspotboolean
Include linked HubSpot company and deal ids in the response.
include_participantsboolean
Include each recording's participant list in the response.
include_private_notesboolean
Personal Access Token only. Include the caller's private notes on each recording.
include_screensharesboolean
Include screenshare timing segments in the response.
meeting_type_idstring
Only return recordings matching this meeting type id (UUID). Use grain_meeting_types_list to discover meeting type ids.
participant_scopestring
'internal' returns only internal/team meetings; 'external' returns only external/customer meetings.one of internalexternal
team_idstring
Only return recordings belonging to this team id (UUID). Use grain_teams_list to discover team ids.
title_searchstring
Return recordings whose title matches this search string.
grain_teams_listList the teams configured in the Grain workspace, with their id and name.Read-only
List Teams
List the teams configured in the Grain workspace, with their id and name. Use this to resolve team ids needed by other tools such as grain_recording_share_team or grain_recordings_list.
Inputs
This tool takes no inputs.
grain_users_listList the users in the Grain workspace, with their id, name, and email.Read-only
List Workspace Users
List the users in the Grain workspace, with their id, name, and email. Use this to resolve user ids needed by other tools such as grain_recording_share_user or grain_recording_upload_url_create.
Inputs
This tool takes no inputs.
grain_hook_createRegister a webhook (hook) that Grain calls with an HTTP POST whenever the given event type occurs — new/updated/deleted recordings, highlights, or stories, or upload processing status changes.Write
Create Webhook
Register a webhook (hook) that Grain calls with an HTTP POST whenever the given event type occurs — new/updated/deleted recordings, highlights, or stories, or upload processing status changes.
Inputs
hook_typestringrequired
The event type this webhook subscribes to.one of recording_addedrecording_updatedrecording_deletedhighlight_addedhighlight_updatedhighlight_deletedstory_addedstory_updatedstory_deletedupload_status
hook_urlstringrequired
HTTPS URL that Grain will POST event payloads to.
grain_recording_share_teamShare a Grain recording with a specific team, granting all of the team's members access to view it.Write
Share Recording with Team
Share a Grain recording with a specific team, granting all of the team's members access to view it.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to share.
team_idstringrequired
UUID of the team to share the recording with. Use grain_teams_list to discover team ids.
grain_recording_share_userShare a Grain recording with a specific workspace user, granting them access to view it.Write
Share Recording with User
Share a Grain recording with a specific workspace user, granting them access to view it.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to share.
user_idstringrequired
UUID of the workspace user to share the recording with. Use grain_users_list to discover user ids.
grain_recording_tag_addAdd a tag to a Grain recording, for later filtering and organization.Write
Add Recording Tag
Add a tag to a Grain recording, for later filtering and organization.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to tag.
tagstringrequired
Tag to add. Must start with a letter or digit and contain only letters, digits, and hyphens.
grain_recording_updateUpdate a Grain recording's title.Write
Update Recording
Update a Grain recording's title.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to update.
titlestringrequired
New title for the recording.
grain_recording_upload_url_createGenerate a one-time upload URL for adding a new recording to Grain.Write
Create Recording Upload URL
Generate a one-time upload URL for adding a new recording to Grain. After calling this, PUT the raw file bytes (.mov, .mp4, .mp3, or .m4a) to the returned url; Grain processes the file asynchronously and reports progress via 'upload_status' webhooks.
Inputs
filenamestringrequired
Name of the file to upload, including its extension. Supported extensions: .mov, .mp4, .mp3, .m4a.
user_idstring
UUID of the workspace user who should own the uploaded recording. Required when authenticating with a Workspace Access Token; not used with a Personal Access Token. Use grain_users_list to discover user ids.
grain_hook_deleteDelete a registered Grain webhook so it stops receiving event calls.Destructive
Delete Webhook
Delete a registered Grain webhook so it stops receiving event calls.
- Idempotent
Inputs
hook_idstringrequired
UUID of the webhook to delete. Use grain_hooks_list to discover hook ids.
grain_recording_tag_removeRemove a tag from a Grain recording.Destructive
Remove Recording Tag
Remove a tag from a Grain recording.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to remove the tag from.
tagstringrequired
Exact tag name to remove.
grain_recording_unshare_teamRevoke a team's shared access to a Grain recording.Destructive
Unshare Recording from Team
Revoke a team's shared access to a Grain recording.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to unshare.
team_idstringrequired
UUID of the team whose access should be revoked.
grain_recording_unshare_userRevoke a workspace user's shared access to a Grain recording.Destructive
Unshare Recording from User
Revoke a workspace user's shared access to a Grain recording.
- Idempotent
Inputs
recording_idstringrequired
UUID of the recording to unshare.
user_idstringrequired
UUID of the workspace user whose access should be revoked.

Setup

Install the SDK

Set your credentials

Create the Grain connection

Authorize a user and make your first call

Tools

Call it

Returns

List Webhooks

Inputs

List Meeting Types

Inputs

Download Recording

Inputs

Get Recording

Inputs

Get Recording Transcript (JSON)

Inputs

Get Recording Transcript (Text Format)

Inputs

List Recordings

Inputs

List Teams

Inputs

List Workspace Users

Inputs

Create Webhook

Inputs

Share Recording with Team

Inputs

Share Recording with User

Inputs

Add Recording Tag

Inputs

Update Recording

Inputs

Create Recording Upload URL

Inputs

Delete Webhook

Inputs

Remove Recording Tag

Inputs

Unshare Recording from Team

Inputs

Unshare Recording from User

Inputs

Other ways to connect Grain

Related: other Transcription connectors