The Heap connector lets your AI agent act in each user's Heap account. Each user connects their own Heap API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 7 tools.
- Tools
- 7
- What they doRead · write · destructive
- 0 · 7 · 00 read7 write0 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. 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 Heap connection
In AgentKit > Connections, create a Heap connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'heap'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Heap:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'heap_account_properties_bulk_add',toolInput: { accounts: [] },})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "heap"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Heap:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={"accounts":[]},tool_name="heap_account_properties_bulk_add",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Heap credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolheap_account_properties_addSet custom properties on one account in Heap, such as payment tier or account owner.WriteAdd Account Properties
Set custom properties on one account in Heap, such as payment tier or account owner. The Account ID setting must be configured in Heap first. Returns an empty JSON object on success. Use this for one account. Use heap_account_properties_bulk_add for up to 1,000 accounts. The connection adds your environment ID (app_id) to the request body.
Inputs
account_idstringrequired- The account ID, matching the value Heap uses as the account ID property. Example: acme-corp.
propertiesobjectrequired- Key-value properties to attach to the account. Each key and value must be a number or a string under 1024 characters. Example: {"plan": "Pro", "seats": 12}.
heap_account_properties_bulk_addSet custom properties on up to 1,000 accounts in Heap in one request.WriteBulk Add Account Properties
Set custom properties on up to 1,000 accounts in Heap in one request. The Account ID setting must be configured in Heap first. Returns an empty JSON object on success. Use this for many accounts. Use heap_account_properties_add for one. The connection adds your environment ID (app_id) to the request body.
Inputs
accountsarrayrequired- Accounts to update, at most 1,000. Each item has an account_id and a properties object. Example: [{"account_id": "acme-corp", "properties": {"subscription": "Yearly"}}].
heap_event_trackSend one custom event for a user to Heap from the server, such as a completed order or a sent email.WriteTrack Event
Send one custom event for a user to Heap from the server, such as a completed order or a sent email. Returns an empty JSON object on success. Use this for a single event. Use heap_events_bulk_track for up to 1,000 events at once. The connection adds your environment ID (app_id) to the request body.
Inputs
eventstringrequired- Name of the custom event, up to 1024 characters. Name events broadly and use properties for details. Example: Send Transactional Email.
idempotency_keystring- A unique ID for this event. Heap ignores later calls with the same key, so retries do not create duplicates. Example: order-10045-completed.
identitystring- The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Provide identity or user_id, not both. Example: alice@example.com.
propertiesobject- Key-value properties to attach to the event. Each key and value must be a number or a string under 1024 characters. Array values are stored as one string joined with ||. Example: {"plan": "Pro", "seats": 12}.
session_idstring- Identifier of the user's session to attach the event to. Example: 7372837920834.
timestampstring- When it happened, in ISO 8601. Defaults to the current time. Example: 2026-03-10T22:21:56+00:00.
user_idstring- The anonymous user_id from the Heap SDK: a whole number between 0 and 2^53 - 1, sent as a string. Provide identity or user_id, not both. Example: 3482937204597382.
heap_events_bulk_trackSend up to 1,000 custom events to Heap in one request.WriteBulk Track Events
Send up to 1,000 custom events to Heap in one request. Returns an empty JSON object on success. Use this to backfill or batch events. Use heap_event_track for one event. The connection adds your environment ID (app_id) to the request body.
Inputs
eventsarrayrequired- Events to send, at most 1,000. Each event needs an event name and either identity or user_id, and can have timestamp (ISO 8601), properties, session_id and idempotency_key. Example: [{"identity": "alice@example.com", "event": "Phone Call", "timestamp": "2026-05-10T22:21:56+00:00", "properties": {"Duration": "15 minutes"}}].
heap_user_identifyAttach a known identity, such as an email, to an anonymous Heap user so that all of that user's events move to the identified user.WriteIdentify User
Attach a known identity, such as an email, to an anonymous Heap user so that all of that user's events move to the identified user. Returns an empty JSON object on success. Heap maps at most one identity to a user_id and at most 10 user_ids to an identity per month, and drops calls past those limits. Use this to merge an anonymous visitor into a known user. Use heap_user_properties_add to set properties on a user. The connection adds your environment ID (app_id) to the request body.
Inputs
identitystringrequired- The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Example: alice@example.com.
user_idstringrequired- The anonymous user_id from the Heap SDK: a whole number between 0 and 2^53 - 1, sent as a string. Example: 3482937204597382.
timestampstring- When it happened, in ISO 8601. Defaults to the current time. Example: 2026-03-10T22:21:56+00:00.
heap_user_properties_addSet custom properties on one identified Heap user, such as sign-up date or plan.WriteAdd User Properties
Set custom properties on one identified Heap user, such as sign-up date or plan. Existing properties with the same name are overwritten, and a user is created if the identity is new. Returns an empty JSON object on success. Use this for one user. Use heap_user_properties_bulk_add for up to 1,000 users. To fill Heap's built-in Email property, use the lowercase key email. The connection adds your environment ID (app_id) to the request body.
Inputs
identitystringrequired- The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Example: alice@example.com.
propertiesobjectrequired- Key-value properties to attach to the user. Each key and value must be a number or a string under 1024 characters. Example: {"plan": "Pro", "seats": 12}.
heap_user_properties_bulk_addSet custom properties on up to 1,000 identified Heap users in one request.WriteBulk Add User Properties
Set custom properties on up to 1,000 identified Heap users in one request. Returns an empty JSON object on success. Use this for many users. Use heap_user_properties_add for one. The connection adds your environment ID (app_id) to the request body.
Inputs
usersarrayrequired- Users to update, at most 1,000. Each item has an identity and a properties object. Use the lowercase key email to fill Heap's built-in Email property. Example: [{"identity": "alice@example.com", "properties": {"Role": "Admin"}}].
No tools match.