Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Heap

Scalekit connector
Open markdown

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

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. 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>
  3. Create the Heap connection

    In AgentKit > Connections, create a Heap connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. 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.actions
    const connector = 'heap'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { 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 call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'heap_account_properties_bulk_add',
    toolInput: { accounts: [] },
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each 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 to execute_tool
Try in PlaygroundRequest a tool
  • heap_account_properties_addSet custom properties on one account in Heap, such as payment tier or account owner.Write

    Add 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.Write

    Bulk 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.Write

    Track 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.Write

    Bulk 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.Write

    Identify 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.Write

    Add 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.Write

    Bulk 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"}}].